Debian Codegraph @

README

raw
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