xmlform(3)
NAME
CGI::XMLForm - Extension of CGI.pm which reads/generates
formated XML.
NB: This is a subclass of CGI.pm, so can be used in it's
place.
SYNOPSIS
use CGI::XMLForm;
my $cgi = new CGI::XMLForm;
if ($cgi->param) {
print $cgi->header, $cgi->pre($cgi->escapeHTML($cgi->toXML));
}
else {
open(FILE, "test.xml") or die "Can't open: $!";
my @queries = ('/a', '/a/b*', '/a/b/c*', /a/d');
print $cgi->header,
$cgi->pre($cgi->escapeHTML(
join "0, $cgi->readXML(*FILE,
@queries)));
}
DESCRIPTION
This module can either create form field values from XML
based on XQL/XSL style queries (full XQL is _not_ sup
ported - this module is designed for speed), or it can
create XML from form values. There are 2 key functions:
toXML and readXML.
toXML
The module takes form fields given in a specialised for
mat, and outputs them to XML based on that format. The
idea is that you can create forms that define the result
ing XML at the back end.
- The format for the form elements is:
- <input name="/body/p/ul/li">
- which creates the following XML:
<body><p><ul><li>Entered Value</li></ul></p>- </body>
- It's the user's responsibility to design appropriate forms
to make use of this module. Details of how come below... - Also supported are attribute form items, that allow cre
ation of element attributes. The syntax for this is:
<input name="/body/p[@id='mypara' and @onClick='some- Func()']/@class">
- Which creates the following XML:
<body><p id="mypara" onClick="someFunc()" class="EnteredValue"></p>- </body>
- Also possible are relative paths. So the following form
elements:
<input type="hidden" name="/table/tr">
<input type="text" name="td">
<input type="text" name="td">
<input type="text" name="../tr/td">- Will create the following XML:
<table><tr><td>value1</td>
<td>value2</td></tr>
<tr><td>value3</td></tr>- </table>
SYNTAX
The following is a brief syntax guideline
- Full paths start with a "/" :
- "/table/tr/td"
- Relative paths start with either ".." or just a tag name.
"../tr/td"
"td"- Relative paths go at the level above the previous path,
unless the previous path was also a relative path, in
which case it goes at the same level. This seems confusing
at first (you might expect it to always go at the level
above the previous element), but it makes your form easier
to design. Take the following example: You have a
timesheet (see the example supplied in the archive) that
has monday,tuesday,etc. Our form can look like this:
<input type="text"- name="/timesheet/projects/project/@Name">
<input type="text" name="monday">
<input type="text" name="tuesday">
... - Rather than:
<input type="text"- name="/timesheet/projects/project/@Name">
<input type="text" name="monday">
<input type="text" name="../tuesday">
<input type="text" name="../wednesday">
... - If unsure I recommend using full paths, relative paths are
great for repeating groups of data, but weak for heavily
structured data. Picture the following paths:
/timesheet/employee/name/forename
../surname
title
../department- This actually creates the following XML:
<timesheet><employee><name><forename>val1</forname><surname>val2</surname>
<title>val3></title></name>
<department>val4</department></employee></timesheet>- Confusing eh? Far better to say:
/timesheet/employee/name/forename
/timesheet/employee/name/surname
/timesheet/employee/name/title
/timesheet/employee/department - Or alternatively, better still:
/timesheet/employee/name (Make hidden and no value)
forename
surname
title
../department - Attributes go in square brackets. Attribute names are pre
ceded with an "@", and attribute values follow an "=" sign
and are enclosed in quotes. Multiple attributes are sepa
rated with " and ".
/table[@bgcolor="blue" and @width="100%"]/tr/td - If setting an attribute, it follows after the tag that it
is associated with, after a "/" and it's name is preceded
with an "@".
/table/@bgcolor - readXML
- readXML takes either a file handle or text as the first
parameter and a list of queries following that. The XML is
searched for the queries and it returns a list of tuples
that are the query and the match. - It's easier to demonstrate this with an example. Given the
following XML:
<a>Foo<b>Bar<c>Fred</c>
<c>Blogs</c></b>
<b>Red<c>Barbara</c>
<c>Cartland</c></b>
<d>Food</d></a> - And the following queries:
/a
/a/b*
c*
/a/d - it returns the following result as a list:
/a
Foo
/a/b
Bar
c
Fred
c
Blogs
/a/b
Red
c
Barbara
c
Cartland
/a/d
Food - (NB: This is slightly incorrect - for /a and /a/b it will
return "Foo " and "Bar " respectively). - The queries support relative paths like toXML (including
parent paths), and they also support wildcards using ".*"
or ".*?" (preferably ".*?" as it's probably a better
match). If a wildcard is specified the results will have
the actual value substituted with the wildcard. Wildcards
are a bit experimental, so be careful ;-) - Caveats
- There are a few caveats to using this module:
AUTHOR
Matt Sergeant msergeant@ndirect.co.uk, sergeant@geoci
ties.com
Based on an original concept, and discussions with,
Jonathan Eisenzopf. Thanks to the Perl-XML mailing
list for suggesting the XSL syntax.
Special thanks to Francois Belanger (fran
cois@sitepak.com) for his mentoring and help with the
syntax design.
SEE ALSO
- CGI(1), CGI::XML