home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _a687f17fe9680eb192c7c9fe33e407d0 < prev    next >
Text File  |  2000-03-23  |  10KB  |  279 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>CGI::XMLForm - Extension of CGI.pm which reads/generates formated XML.</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> CGI::XMLForm - Extension of CGI.pm which reads/generates formated XML.</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#toxml">toXML</A></LI>
  28.     </UL>
  29.  
  30.     <LI><A HREF="#syntax">SYNTAX</A></LI>
  31.     <UL>
  32.  
  33.         <LI><A HREF="#readxml">readXML</A></LI>
  34.         <LI><A HREF="#caveats">Caveats</A></LI>
  35.     </UL>
  36.  
  37.     <LI><A HREF="#author">AUTHOR</A></LI>
  38.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  39. </UL>
  40. <!-- INDEX END -->
  41.  
  42. <HR>
  43. <P>
  44. <H1><A NAME="name">NAME</A></H1>
  45. <P>CGI::XMLForm - Extension of CGI.pm which reads/generates formated XML.</P>
  46. <P>NB: This is a subclass of CGI.pm, so can be used in it's place.</P>
  47. <P>
  48. <HR>
  49. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  50. <UL>
  51. <LI>Linux</LI>
  52. <LI>Solaris</LI>
  53. <LI>Windows</LI>
  54. </UL>
  55. <HR>
  56. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  57. <PRE>
  58.   use CGI::XMLForm;</PRE>
  59. <PRE>
  60.   my $cgi = new CGI::XMLForm;</PRE>
  61. <PRE>
  62.   if ($cgi->param) {
  63.         print $cgi->header, $cgi->pre($cgi->escapeHTML($cgi->toXML));
  64.   }
  65.   else {
  66.         open(FILE, "test.xml") or die "Can't open: $!";
  67.         my @queries = ('/a', '/a/b*', '/a/b/c*', /a/d');
  68.     print $cgi->header,
  69.               $cgi->pre($cgi->escapeHTML(
  70.                   join "\n", $cgi->readXML(*FILE, @queries)));
  71.   }</PRE>
  72. <P>
  73. <HR>
  74. <H1><A NAME="description">DESCRIPTION</A></H1>
  75. <P>This module can either create form field values from XML based on XQL/XSL style
  76. queries (full XQL is _not_ supported - this module is designed for speed), or it
  77. can create XML from form values. There are 2 key functions: toXML and readXML.</P>
  78. <P>
  79. <H2><A NAME="toxml">toXML</A></H2>
  80. <P>The module takes form fields given in a specialised format,
  81. and outputs them to XML based on that format. The idea is that you
  82. can create forms that define the resulting XML at the back end.</P>
  83. <P>The format for the form elements is:</P>
  84. <PRE>
  85.   <input name="/body/p/ul/li"></PRE>
  86. <P>which creates the following XML:</P>
  87. <PRE>
  88.   <body>
  89.     <p>
  90.           <ul>
  91.             <li>Entered Value</li>
  92.           </ul>
  93.         </p>
  94.   </body></PRE>
  95. <P>It's the user's responsibility to design appropriate forms to make
  96. use of this module. Details of how come below...</P>
  97. <P>Also supported are attribute form items, that allow creation
  98. of element attributes. The syntax for this is:</P>
  99. <PRE>
  100.   <input name="/body/p[@id='mypara' and @onClick='someFunc()']/@class"></PRE>
  101. <P>Which creates the following XML:</P>
  102. <PRE>
  103.   <body>
  104.     <p id="mypara" onClick="someFunc()" class="Entered Value"></p>
  105.   </body></PRE>
  106. <P>Also possible are relative paths. So the following form elements:</P>
  107. <PRE>
  108.   <input type="hidden" name="/table/tr">
  109.   <input type="text" name="td">
  110.   <input type="text" name="td">
  111.   <input type="text" name="../tr/td"></PRE>
  112. <P>Will create the following XML:</P>
  113. <PRE>
  114.   <table>
  115.     <tr>
  116.           <td>value1</td>
  117.           <td>value2</td>
  118.         </tr>
  119.         <tr>
  120.           <td>value3</td>
  121.         </tr>
  122.   </table></PRE>
  123. <P>
  124. <HR>
  125. <H1><A NAME="syntax">SYNTAX</A></H1>
  126. <P>The following is a brief syntax guideline</P>
  127. <P>Full paths start with a ``/'' :</P>
  128. <PRE>
  129.   "/table/tr/td"</PRE>
  130. <P>Relative paths start with either ``..'' or just a tag name.</P>
  131. <PRE>
  132.   "../tr/td"
  133.   "td"</PRE>
  134. <P><STRONG>Relative paths go at the level above the previous path, unless the previous
  135. path was also a relative path, in which case it goes at the same level.</STRONG> This
  136. seems confusing at first (you might expect it to always go at the level above
  137. the previous element), but it makes your form easier to design. Take the
  138. following example: You have a timesheet (see the example supplied in the
  139. archive) that has monday,tuesday,etc. Our form can look like this:</P>
  140. <PRE>
  141.   <input type="text" name="/timesheet/projects/project/@Name">
  142.   <input type="text" name="monday">
  143.   <input type="text" name="tuesday">
  144.   ...</PRE>
  145. <P>Rather than:</P>
  146. <PRE>
  147.   <input type="text" name="/timesheet/projects/project/@Name">
  148.   <input type="text" name="monday">
  149.   <input type="text" name="../tuesday">
  150.   <input type="text" name="../wednesday">
  151.   ...</PRE>
  152. <P>If unsure I recommend using full paths, relative paths are great for repeating
  153. groups of data, but weak for heavily structured data. Picture the following
  154. paths:</P>
  155. <PRE>
  156.   /timesheet/employee/name/forename
  157.   ../surname
  158.   title
  159.   ../department</PRE>
  160. <P>This actually creates the following XML:</P>
  161. <PRE>
  162.   <timesheet>
  163.     <employee>
  164.           <name>
  165.             <forename>val1</forname>
  166.                 <surname>val2</surname>
  167.                 <title>val3></title>
  168.           </name>
  169.           <department>val4</department>
  170.         </employee>
  171.   </timesheet></PRE>
  172. <P>Confusing eh? Far better to say:</P>
  173. <PRE>
  174.   /timesheet/employee/name/forename
  175.   /timesheet/employee/name/surname
  176.   /timesheet/employee/name/title
  177.   /timesheet/employee/department</PRE>
  178. <P>Or alternatively, better still:</P>
  179. <PRE>
  180.   /timesheet/employee/name (Make hidden and no value)
  181.   forename
  182.   surname
  183.   title
  184.   ../department</PRE>
  185. <P>Attributes go in square brackets. Attribute names are preceded with an ``@'',
  186. and attribute values follow an ``='' sign and are enclosed in quotes. Multiple
  187. attributes are separated with `` and ''.</P>
  188. <PRE>
  189.   /table[@bgcolor="blue" and @width="100%"]/tr/td</PRE>
  190. <P>If setting an attribute, it follows after the tag that it is associated with,
  191. after a ``/'' and it's name is preceded with an ``@''.</P>
  192. <PRE>
  193.   /table/@bgcolor</PRE>
  194. <P>
  195. <H2><A NAME="readxml">readXML</A></H2>
  196. <P>readXML takes either a file handle or text as the first parameter and a list of
  197. queries following that. The XML is searched for the queries and it returns a
  198. list of tuples that are the query and the match.</P>
  199. <P>It's easier to demonstrate this with an example. Given the following XML:</P>
  200. <PRE>
  201.   <a>Foo
  202.     <b>Bar
  203.           <c>Fred</c>
  204.           <c>Blogs</c>
  205.         </b>
  206.         <b>Red
  207.           <c>Barbara</c>
  208.           <c>Cartland</c>
  209.         </b>
  210.         <d>Food</d>
  211.   </a></PRE>
  212. <P>And the following queries:</P>
  213. <PRE>
  214.   /a
  215.   /a/b*
  216.   c*
  217.   /a/d</PRE>
  218. <P>it returns the following result as a list:</P>
  219. <PRE>
  220.   /a
  221.   Foo
  222.   /a/b
  223.   Bar
  224.   c
  225.   Fred
  226.   c
  227.   Blogs
  228.   /a/b
  229.   Red
  230.   c
  231.   Barbara
  232.   c
  233.   Cartland
  234.   /a/d
  235.   Food</PRE>
  236. <P>(NB: This is slightly incorrect - for /a and /a/b it will return ``Foo\n    '' and
  237. ``Bar\n      '' respectively).</P>
  238. <P>The queries support relative paths like toXML (including parent paths), and
  239. they also support wildcards using ``.*'' or ``.*?'' (preferably ``.*?'' as it's
  240. probably a better match). If a wildcard is specified the results will have the
  241. actual value substituted with the wildcard. Wildcards are a bit experimental,
  242. so be careful ;-)</P>
  243. <P>
  244. <H2><A NAME="caveats">Caveats</A></H2>
  245. <P>There are a few caveats to using this module:</P>
  246. <UL>
  247. <LI><STRONG><A NAME="item_setting">Parameters must be on the form in the order they will appear in the XML.
  248. =item * There is no support for multiple attribute setting (i.e. you can only
  249. set one attribute for an element at a time).
  250. =item * You can't set an attribute <STRONG>and</STRONG> a value for that element, it's one or the
  251. other.
  252. =item * You can use this module in place of CGI.pm, since it's a subclass.
  253. =item * There are bound to be lots of bugs! Although it's in production use
  254. right now - just watch CPAN for regular updates.
  255. =back</A></STRONG><BR>
  256.  
  257. </UL>
  258. <P>
  259. <HR>
  260. <H1><A NAME="author">AUTHOR</A></H1>
  261. <P>Matt Sergeant <A HREF="mailto:msergeant@ndirect.co.uk,">msergeant@ndirect.co.uk,</A> <A HREF="mailto:sergeant@geocities.com">sergeant@geocities.com</A></P>
  262. <P>Based on an original concept, and discussions with, Jonathan Eisenzopf.
  263. Thanks to the Perl-XML mailing list for suggesting the XSL syntax.</P>
  264. <P>Special thanks to Francois Belanger (<A HREF="mailto:francois@sitepak.com">francois@sitepak.com</A>) for
  265. his mentoring and help with the syntax design.</P>
  266. <P>
  267. <HR>
  268. <H1><A NAME="see also">SEE ALSO</A></H1>
  269. <P>CGI(1), CGI::XML</P>
  270. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  271. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  272. <STRONG><P CLASS=block> CGI::XMLForm - Extension of CGI.pm which reads/generates formated XML.</P></STRONG>
  273. </TD></TR>
  274. </TABLE>
  275.  
  276. </BODY>
  277.  
  278. </HTML>
  279.