home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / sample.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  10.3 KB  |  274 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18.  
  19. <document>
  20.   <header>
  21.     <title>Cocoon Forms: A Simple Example</title>
  22.     <authors>
  23.       <person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
  24.     </authors>
  25.   </header>
  26.   <body>
  27.     <s1 title="A simple CForms example">
  28.       <p>In this example we will show how to create a simple registration
  29.       form using CForms and flowscript. We will follow to following steps:</p>
  30.  
  31.       <ol>
  32.         <li>Create a form definition file</li>
  33.         <li>Create a template file for the Forms Template Transformer</li>
  34.         <li>Write a bit of flowscript</li>
  35.         <li>Add some pipelines to the sitemap</li>
  36.       </ol>
  37.  
  38.       <p>Here is a screenshot of the form we're going to create:</p>
  39.  
  40.       <figure src="images/forms_registrationform.png" alt="Screenshot of the sample we're going to create."/>
  41.     </s1>
  42.  
  43.     <s1 title="Create a form definition file">
  44.       <p>Below the form definition file is displayed. This lists all the widgets
  45.       in the form, together with their configuration information.</p>
  46.  
  47.       <source><![CDATA[<fd:form
  48.   xmlns:fd="http://apache.org/cocoon/forms/1.0#definition">
  49.  
  50.   <fd:widgets>
  51.     <fd:field id="name" required="true">
  52.       <fd:label>Name:</fd:label>
  53.       <fd:datatype base="string"/>
  54.       <fd:validation>
  55.         <fd:length min="2"/>
  56.       </fd:validation>
  57.     </fd:field>
  58.  
  59.     <fd:field id="email" required="true">
  60.       <fd:label>Email address:</fd:label>
  61.       <fd:datatype base="string"/>
  62.       <fd:validation>
  63.         <fd:email/>
  64.       </fd:validation>
  65.     </fd:field>
  66.  
  67.     <fd:field id="age">
  68.       <fd:label>Your age:</fd:label>
  69.       <fd:datatype base="long"/>
  70.       <fd:validation>
  71.         <fd:range min="0" max="150"/>
  72.       </fd:validation>
  73.     </fd:field>
  74.  
  75.     <fd:field id="password" required="true">
  76.       <fd:label>Password:</fd:label>
  77.       <fd:datatype base="string"/>
  78.       <fd:validation>
  79.         <fd:length min="5" max="20"/>
  80.       </fd:validation>
  81.     </fd:field>
  82.  
  83.     <fd:field id="confirmPassword" required="true">
  84.       <fd:label>Re-enter password:</fd:label>
  85.       <fd:datatype base="string"/>
  86.       <fd:validation>
  87.         <fd:assert test="password = confirmPassword">
  88.           <fd:failmessage>The two passwords are not equal.</fd:failmessage>
  89.         </fd:assert>
  90.       </fd:validation>
  91.     </fd:field>
  92.  
  93.     <fd:booleanfield id="spam">
  94.       <fd:label>Send me spam</fd:label>
  95.     </fd:booleanfield>
  96.   </fd:widgets>
  97.  
  98. </fd:form>
  99. ]]></source>
  100.       <p>All elements are in the Forms Definition namespace: <strong>fd</strong>.</p>
  101.  
  102.       <p>Every definition file has a <strong><fd:form></strong> element as the root element.</p>
  103.  
  104.       <p>The child widgets of the form are defined inside the <strong><fd:widgets></strong> element.
  105.       As you can see, most of the widgets are field widgets. The field widget is the most
  106.       important widget in CForms. It is very flexible because it can be associated with
  107.       different datatypes and with a selection list. See the reference docs for more
  108.       information on this and other widgets.</p>
  109.  
  110.       <p>A nice feature is that the <strong>fd:label</strong> tags can contain mixed content.
  111.       On the one hand, this can be used to provide rich formatting in the label. But it
  112.       also enables you to put i18n-elements in there, to be interpreted by the I18nTransformer.
  113.       This way, internationalisation is done using standard Cocoon techniques.</p>
  114.     </s1>
  115.  
  116.     <s1 title="Create a template file for the Forms Template Transformer">
  117.       <p>Here's the template for our registration form example:</p>
  118.  
  119.       <source><![CDATA[<html xmlns:ft="http://apache.org/cocoon/forms/1.0#template"
  120.   xmlns:fi="http://apache.org/cocoon/forms/1.0#instance">
  121.   <head>
  122.     <title>Registration form</title>
  123.   </head>
  124.   <body>
  125.     <h1>Registration</h1>
  126.     <ft:form-template action="#{$continuation/id}.continue" method="POST">
  127.       <ft:widget-label id="name"/>
  128.       <ft:widget id="name"/>
  129.       <br/>
  130.       <ft:widget-label id="email"/>
  131.       <ft:widget id="email"/>
  132.       <br/>
  133.       <ft:widget-label id="age"/>
  134.       <ft:widget id="age"/>
  135.       <br/>
  136.       <ft:widget-label id="password"/>
  137.       <ft:widget id="password">
  138.         <fi:styling type="password"/>
  139.       </ft:widget>
  140.       <br/>
  141.       <ft:widget-label id="confirmPassword"/>
  142.       <ft:widget id="confirmPassword">
  143.         <fi:styling type="password"/>
  144.       </ft:widget>
  145.       <br/>
  146.       <ft:widget id="spam"/>
  147.       <ft:widget-label id="spam"/>
  148.       <br/>
  149.  
  150.       <input type="submit"/>
  151.     </ft:form-template>
  152.   </body>
  153. </html>]]></source>
  154.  
  155.       <p>The CForms-specific elements here are in the "Forms Template" namespace: <strong>ft</strong>.</p>
  156.  
  157.       <p>The <ft:widget-label> tag will cause the label of a widget to be
  158.        inserted at the location of the tag. The <ft:widget> tag will cause
  159.        the XML representation of a widget to be inserted at the location of that tag.
  160.        The inserted XML will be in the "Forms Instance" namespace: <strong>fi</strong>.</p>
  161.  
  162.       <p>The XML representation of the widget will then be translated to HTML by an
  163.       XSLT stylesheet (forms-samples-styling.xsl in our case -- see sitemap snippets below).
  164.       This XSLT only has to handle individual widgets, and not the page as a whole,
  165.       and is thus not specific for one form but can be reused across forms.</p>
  166.  
  167.       <p>For certain widgets it may be necessary to provide extra presentation hints,
  168.       such as the width of a text box, the style of a selection list (drop down,
  169.       radio buttons, ...) or class and style attribute values. This can be done
  170.       by putting a fi:styling element inside the ft:widget element. This element
  171.       is in the fi namespace because it will be copied literally. The attributes
  172.       and/or content of the fi:styling element depend on what is supported by the
  173.       particular stylesheet used.</p>
  174.  
  175.       <p>As an alternative to the template approach, you could also use the FormsGenerator,
  176.       which will generate an XML representation of the whole form, and style that with a
  177.       custom-written XSLT. For most users we recommend the template approach though.</p>
  178.     </s1>
  179.  
  180.     <s1 title="Write a bit of flowscript">
  181.       <p>Flowscript is Cocoon's solution to handling the flow of a web interaction.
  182.       It is based on the concept of continuations. If you don't know yet about continuations
  183.       and flowscript, <link href="../flow/index.html">learn about it here</link>.</p>
  184.  
  185.       <p>Here's the flowscript for our example, <code>registration.js</code>:</p>
  186.  
  187.       <source><![CDATA[cocoon.load("resource://org/apache/cocoon/forms/flow/javascript/Form.js");
  188.  
  189. function registration() {
  190.     var form = new Form("forms/registration.xml");
  191.  
  192.     form.showForm("registration-display-pipeline");
  193.  
  194.     var model = form.getModel();
  195.     var bizdata = { "username" : model.name }
  196.     cocoon.sendPage("registration-success-pipeline", bizdata);
  197. }]]></source>
  198.  
  199.       <note>This sample still shows the "old" flowscript API. Will be updated eventually.</note>
  200.  
  201.       <p>The flowscript works as follows:</p>
  202.  
  203.       <p>First we create a Form object, specifying the form definition file to be used.
  204.       The Form object is actually a javascript wrapper around the "real" Java form instance object.</p>
  205.  
  206.       <p>Then the showForm function is called on the form object. This will (re)display
  207.       the form to the user until validation of the form succeeded. As parameter to
  208.       the showForm function, we pass the sitemap pipeline to be used to display the form.</p>
  209.  
  210.       <p>Finally we get some data from the form (the entered name), and call a sitemap
  211.       pipeline to display this data. This pipeline is based on the JXTemplate generator.</p>
  212.     </s1>
  213.  
  214.     <s1 title="Add some pipelines to the sitemap">
  215.       <p>First of all, do not forget to register the <code>registration.js</code>
  216.       file in the map:flow section of the sitemap, as follows:</p>
  217.  
  218.       <source><![CDATA[<map:flow language="javascript">
  219.   <map:script src="flow/registration.js"/>
  220. </map:flow>]]></source>
  221.  
  222.       <p>And here are the pipelines we need:</p>
  223.  
  224.       <source><![CDATA[<map:match pattern="registration">
  225.   <map:call function="registration"/>
  226. </map:match>
  227.  
  228. <map:match pattern="*.continue">
  229.   <map:call continuation="{1}"/>
  230. </map:match>
  231.  
  232. <map:match pattern="registration-display-pipeline">
  233.   <map:generate src="forms/registration_template.xml"/>
  234.   <map:transform type="forms"/>
  235.   <map:transform type="i18n">
  236.     <map:parameter name="locale" value="en-US"/>
  237.   </map:transform>
  238.   <map:transform src="resources/forms-samples-styling.xsl"/>
  239.   <map:serialize/>
  240. </map:match>
  241.  
  242. <map:match pattern="registration-success-pipeline">
  243.   <map:generate type="jx" src="forms/registration_success.jx"/>
  244.   <map:serialize/>
  245. </map:match>]]></source>
  246.  
  247.       <p>The first two are for managing the flowscript: when someone hits the registration
  248.       URL, we call the registration function in our flowscript.</p>
  249.  
  250.       <p>When a form is submitted, it will be matched by the second matcher,
  251.       *.continue, which will continue the execution of the flowscript.</p>
  252.  
  253.       <p>The third matcher is for displaying the form, and uses the Forms Template Transformer.</p>
  254.  
  255.       <p>The fourth pipeline is for showing the "success" page using the
  256.       JXTemplate generator, here is the contents of the registration_succcess.jx page:</p>
  257.  
  258.       <source><![CDATA[<html>
  259.   <head>
  260.     <title>Registration successful</title>
  261.   </head>
  262.   <body>
  263.     Registration was successful for ${username}!
  264.   </body>
  265. </html>]]></source>
  266.     </s1>
  267.  
  268.     <s1 title="Next steps">
  269.       <p>The example we've studied here is quite simple. To have a feel for the power
  270.       of CForms, take a look at the examples included included in the Forms block.</p>
  271.     </s1>
  272.   </body>
  273. </document>
  274.