| 1 |
0.07 Wed Jan 27 1999 |
| 2 |
- Speed improvements. Now faster than XML::XQL (DOM) for all cases |
| 3 |
- Some minor bug fixes |
| 4 |
- Fixes to Stream mode - see README - needs to patch XML::Parser version |
| 5 |
2.19 |
| 6 |
|
| 7 |
==================================================================== |
| 8 |
*** WARNING *** WARNING *** WARNING *** WARNING *** |
| 9 |
|
| 10 |
This module requires XML::Parser version 2.20, but that's not been released |
| 11 |
yet. To get around this you need to make 2 patches to XML::Parser (1 of them |
| 12 |
is non-essential). First, the non-essential bug fix: |
| 13 |
|
| 14 |
In XML::Parser, the Stream style has a function doText which looks like: |
| 15 |
|
| 16 |
sub doText { |
| 17 |
... |
| 18 |
|
| 19 |
if ($_) { |
| 20 |
... |
| 21 |
} |
| 22 |
} |
| 23 |
|
| 24 |
change that to: |
| 25 |
|
| 26 |
sub doText { |
| 27 |
... |
| 28 |
|
| 29 |
if (defined $_) { |
| 30 |
... |
| 31 |
} |
| 32 |
} |
| 33 |
|
| 34 |
And the other, required fix is to add the following function to Expat.pm: |
| 35 |
|
| 36 |
sub finish { |
| 37 |
my ($self) = @_; |
| 38 |
|
| 39 |
foreach (keys %{$self->{_Setters}}) { |
| 40 |
&{$self->{_Setters}->{$_}}($self->{Parser}, undef); |
| 41 |
} |
| 42 |
} |
| 43 |
|
| 44 |
The first patch fixes a bug where you have <tag>0</tag> and the finish function |
| 45 |
allows you to break out of a parse phase. |
| 46 |
|
| 47 |
END OF WARNING. |
| 48 |
==================================================================== |
| 49 |
|
| 50 |
NAME |
| 51 |
CGI::XMLForm - Extension of CGI.pm which reads/generates |
| 52 |
formated XML. |
| 53 |
|
| 54 |
This is currently alpha software, and I'm looking for feedback. |
| 55 |
Note though that it is proving quite stable in our mod_perl |
| 56 |
environment, so it is ready for production use. |
| 57 |
|
| 58 |
NB: This is a subclass of CGI.pm, so can be used in it's place. |
| 59 |
|
| 60 |
SYNOPSIS |
| 61 |
use CGI::XMLForm; |
| 62 |
|
| 63 |
my $cgi = new CGI::XMLForm; |
| 64 |
|
| 65 |
if ($cgi->param) { |
| 66 |
print $cgi->header, $cgi->pre($cgi->escapeHTML($cgi->toXML)); |
| 67 |
} |
| 68 |
else { |
| 69 |
open(FILE, "test.xml") or die "Can't open: $!"; |
| 70 |
my @queries = ('/a', '/a/b*', '/a/b/c*', /a/d'); |
| 71 |
print $cgi->header, |
| 72 |
$cgi->pre($cgi->escapeHTML( |
| 73 |
join "\n", $cgi->readXML(*FILE, @queries))); |
| 74 |
} |
| 75 |
|
| 76 |
DESCRIPTION |
| 77 |
This module can either create form field values from XML based |
| 78 |
on XQL style queries (full XQL is _not_ supported - this module |
| 79 |
is designed for speed), or it can create XML from form values. |
| 80 |
There are 2 key functions: toXML and readXML. |
| 81 |
|
| 82 |
toXML |
| 83 |
|
| 84 |
The module takes form fields given in a specialised format, and |
| 85 |
outputs them to XML based on that format. The idea is that you |
| 86 |
can create forms that define the resulting XML at the back end. |
| 87 |
|
| 88 |
The format for the form elements is: |
| 89 |
|
| 90 |
<input name="/body/p/ul/li"> |
| 91 |
|
| 92 |
which creates the following XML: |
| 93 |
|
| 94 |
<body> |
| 95 |
<p> |
| 96 |
<ul> |
| 97 |
<li>Entered Value</li> |
| 98 |
</ul> |
| 99 |
</p> |
| 100 |
</body> |
| 101 |
|
| 102 |
It's the user's responsibility to design appropriate forms to |
| 103 |
make use of this module, although coming later will be a small |
| 104 |
module that uses my XML::DTDParser to create all the form |
| 105 |
elements given a DTD. |
| 106 |
|
| 107 |
Also supported are attribute form items, that allow creation of |
| 108 |
element attributes. The syntax for this is: |
| 109 |
|
| 110 |
<input name="/body/p[@id="mypara" and @onClick="someFunc()"]/@class"> |
| 111 |
|
| 112 |
Which creates the following XML: |
| 113 |
|
| 114 |
<body> |
| 115 |
<p id="mypara" onClick="someFunc()" class="Entered Value"></p> |
| 116 |
</body> |
| 117 |
|
| 118 |
Also possible are relative paths. So the following form |
| 119 |
elements: |
| 120 |
|
| 121 |
<input type="hidden" name="/table/tr"> |
| 122 |
<input type="text" name="td"> |
| 123 |
<input type="text" name="td"> |
| 124 |
<input type="text" name="../tr/td"> |
| 125 |
|
| 126 |
Will create the following XML: |
| 127 |
|
| 128 |
<table> |
| 129 |
<tr> |
| 130 |
<td>value1</td> |
| 131 |
<td>value2</td> |
| 132 |
</tr> |
| 133 |
<tr> |
| 134 |
<td>value3</td> |
| 135 |
</tr> |
| 136 |
</table> |
| 137 |
|
| 138 |
SYNTAX |
| 139 |
The following is a brief syntax guideline |
| 140 |
|
| 141 |
Full paths start with a "/" : |
| 142 |
|
| 143 |
"/table/tr/td" |
| 144 |
|
| 145 |
Relative paths start with either ".." or just a tag name. |
| 146 |
|
| 147 |
"../tr/td" |
| 148 |
"td" |
| 149 |
|
| 150 |
Relative paths go at the level above the previous path, unless |
| 151 |
the previous path was also a relative path, in which case it |
| 152 |
goes at the same level. This seems confusing at first (you might |
| 153 |
expect it to always go at the level above the previous element), |
| 154 |
but it makes your form easier to design. Take the following |
| 155 |
example: You have a timesheet (see the example supplied in the |
| 156 |
archive) that has monday,tuesday,etc. Our form can look like |
| 157 |
this: |
| 158 |
|
| 159 |
<input type="text" name="/timesheet/projects/project/@Name"> |
| 160 |
<input type="text" name="monday"> |
| 161 |
<input type="text" name="tuesday"> |
| 162 |
... |
| 163 |
|
| 164 |
Rather than: |
| 165 |
|
| 166 |
<input type="text" name="/timesheet/projects/project/@Name"> |
| 167 |
<input type="text" name="monday"> |
| 168 |
<input type="text" name="../tuesday"> |
| 169 |
<input type="text" name="../wednesday"> |
| 170 |
... |
| 171 |
|
| 172 |
If unsure I recommend using full paths, relative paths are great |
| 173 |
for repeating groups of data, but weak for heavily structured |
| 174 |
data. Picture the following paths: |
| 175 |
|
| 176 |
/timesheet/employee/name/forename |
| 177 |
../surname |
| 178 |
title |
| 179 |
../department |
| 180 |
|
| 181 |
This actually creates the following XML: |
| 182 |
|
| 183 |
<timesheet> |
| 184 |
<employee> |
| 185 |
<name> |
| 186 |
<forename>val1</forname> |
| 187 |
<surname>val2</surname> |
| 188 |
<title>val3></title> |
| 189 |
</name> |
| 190 |
<department>val4</department> |
| 191 |
</employee> |
| 192 |
</timesheet> |
| 193 |
|
| 194 |
Confusing eh? Far better to say: |
| 195 |
|
| 196 |
/timesheet/employee/name/forename |
| 197 |
/timesheet/employee/name/surname |
| 198 |
/timesheet/employee/name/title |
| 199 |
/timesheet/employee/department |
| 200 |
|
| 201 |
Or alternatively, better still: |
| 202 |
|
| 203 |
/timesheet/employee/name (Make hidden and no value) |
| 204 |
forename |
| 205 |
surname |
| 206 |
title |
| 207 |
../department |
| 208 |
|
| 209 |
Attributes go in square brackets. Attribute names are preceded |
| 210 |
with an "@", and attribute values follow an "=" sign and are |
| 211 |
enclosed in quotes. Multiple attributes are separated with " and |
| 212 |
". |
| 213 |
|
| 214 |
/table[@bgcolor="blue" and @width="100%"]/tr/td |
| 215 |
|
| 216 |
If setting an attribute, it follows after the tag that it is |
| 217 |
associated with, after a "/" and it's name is preceded with an |
| 218 |
"@". |
| 219 |
|
| 220 |
/table/@bgcolor |
| 221 |
|
| 222 |
readXML |
| 223 |
|
| 224 |
readXML takes either a file handle or text as the first |
| 225 |
parameter and a list of queries following that. The XML is |
| 226 |
searched for the queries and it returns a list of tuples that |
| 227 |
are the query and the match. |
| 228 |
|
| 229 |
It's easier to demonstrate this with an example. Given the |
| 230 |
following XML: |
| 231 |
|
| 232 |
<a>Foo |
| 233 |
<b>Bar |
| 234 |
<c>Fred</c> |
| 235 |
<c>Blogs</c> |
| 236 |
</b> |
| 237 |
<b>Red |
| 238 |
<c>Barbara</c> |
| 239 |
<c>Cartland</c> |
| 240 |
</b> |
| 241 |
<d>Food</d> |
| 242 |
</a> |
| 243 |
|
| 244 |
And the following queries: |
| 245 |
|
| 246 |
/a |
| 247 |
/a/b* |
| 248 |
c* |
| 249 |
/a/d |
| 250 |
|
| 251 |
it returns the following result as a list: |
| 252 |
|
| 253 |
/a |
| 254 |
Foo |
| 255 |
/a/b |
| 256 |
Bar |
| 257 |
c |
| 258 |
Fred |
| 259 |
c |
| 260 |
Blogs |
| 261 |
/a/b |
| 262 |
Red |
| 263 |
c |
| 264 |
Barbara |
| 265 |
c |
| 266 |
Cartland |
| 267 |
/a/d |
| 268 |
Food |
| 269 |
|
| 270 |
(NB: This is slightly incorrect - for /a and /a/b it will return |
| 271 |
"Foo\n " and "Bar\n " respectively). |
| 272 |
|
| 273 |
The queries support relative paths like toXML (including parent |
| 274 |
paths), and they also support wildcards using ".*" or ".*?" |
| 275 |
(preferably ".*?" as it's probably a better match). If a |
| 276 |
wildcard is specified the results will have the actual value |
| 277 |
substituted with the wildcard. Wildcards are a bit experimental, |
| 278 |
so be careful ;-) |
| 279 |
|
| 280 |
Caveats |
| 281 |
|
| 282 |
There are a few caveats to using this module: |
| 283 |
|
| 284 |
AUTHOR |
| 285 |
Matt Sergeant [email protected], |
| 286 |
[email protected] |
| 287 |
|
| 288 |
Based on an original concept, and discussions with, Jonathan |
| 289 |
Eisenzopf. Thanks to the Perl-XML mailing list for |
| 290 |
suggesting the XSL syntax. |
| 291 |
|
| 292 |
Special thanks to Francois Belanger ([email protected]) |
| 293 |
for his mentoring and help with the syntax design. |
| 294 |
|
| 295 |
SEE ALSO |
| 296 |
CGI(1), CGI::XML |
| 297 |
|