Provided by: libcgi-xmlform-perl_0.10-14_all bug

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 "\n", $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_ supported - 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 format, and outputs them to XML based
       on that format. The idea is that you can create forms that define the resulting 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 creation of element attributes. The
       syntax for this is:

         <input name="/body/p[@id='mypara' and @onClick='someFunc()']/@class">

       Which creates the following XML:

         <body>
           <p id="mypara" onClick="someFunc()" class="Entered Value"></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 preceded with an "@", and attribute
       values follow an "=" sign and are enclosed in quotes. Multiple attributes are separated
       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\n    " and "Bar\n
       " 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:

       •   Parameters must be on the form in the order they will appear in the XML.

       •   There is no support for multiple attribute setting (i.e. you can only set one
           attribute for an element at a time).

       •   You can't set an attribute and a value for that element, it's one or the other.

       •   You can use this module in place of CGI.pm, since it's a subclass.

       •   There are bound to be lots of bugs! Although it's in production use right now - just
           watch CPAN for regular updates.

AUTHOR

       Matt Sergeant msergeant@ndirect.co.uk, sergeant@geocities.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 (francois@sitepak.com) for his mentoring and help with
       the syntax design.

SEE ALSO

       CGI(1), CGI::XML