<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.0//EN" "http://apache.org/forrest/dtd/howto-v10.dtd">

<howto>

  <header>
    <title>How to build an XMLForm Wizard</title>
    <authors>
      <person name="Heidi Brannan" email="heidi@wkwyw.net"/>
    </authors>
  <abstract>This How-To will guide your through the steps needed to create a validating form which saves the data collected as a JavaBean. It shows the components needed to do this within the Cocoon framework, Schematron validation and XMLForm wizard. XMLForm is a Cocoon form extension mechanism which was inspired by Struts and XForms. It was written by Ivelin Ivanov and is currently included in the scratchpad of Cocoon 2.0.2. Using the XMLForm wizard makes form validation a quick and easy task.</abstract>
  <last-modified-content-date date="2002-05-19"/>
  </header>

    <audience title="Intended audience">
       <p>This How-To is aimed at users who have developed an understanding of the basics of Cocoon and wish to incorporate dynamic and self validating forms into their sites. You will need to understand and be familiar with XML, XSL, HTML, XPath, JXPath, actions, action sets, cocoon-form format, Java, XForms. If you are unfamiliar with these technologies it is advised that you learn these concepts first.</p>
    </audience>

    <purpose title="Purpose">
    <!-- FIXME: purpose means, how will it help the reader. What will he or she get out of it,
                not the purpose of validation -->
      <p>You will be able to automate two-way mapping between their HTML forms, XML and JavaBeans. The XML schema language is used to validate the form input. The forms can display different options depending on the users previous input.  For example if a user ticks the checkbox to say they are interest in Cooking then they will later have the option to join Cookery mailing lists. If they did not tick the Cookery box they will not see the cookery mailing lists page.</p>
    </purpose>
    
    
    <prerequisites title="Prerequisites">
       <p>Configuration requirements:</p>
         <ul> 
             <li>A servlet engine such as Tomcat.</li>
             <li>JDK 1.2 or later</li>
             <li>Cocoon 2.0.2 CVS with scratchpad to be installed with the command: 
                  build webapp -Dinclude.webapp.libs=true -Dinclude.scratchpad.libs=true webapp
             </li>
         </ul>
       <p>Requisite skills:</p>
         <ul> 
             <li>basic Cocoon concepts, including Cocoon actions</li>
             <li>XML, XSL, HTML</li>
             <li>Java, JavaBeans</li>
             <li>XForms, XPath, JXPath</li>
         </ul>

    </prerequisites>
    
    <steps title="Five Steps">
     <p>Now you want to know how to create your own forms using the Wizard.  Below are the steps you can follow:</p>
     <ul>
       <li><link href="site:xmlform/step1">Step 1: XML forms</link></li>
       <li><link href="site:xmlform/step2">Step 2: Validation</link></li>
       <li><link href="site:xmlform/step3">Step 3: JavaBean</link></li>
       <li><link href="site:xmlform/step4">Step 4: HowtoWizardAction.java</link></li>
       <li><link href="site:xmlform/step5">Step 5: Sitemap</link></li>
     </ul>
    </steps>
    
     
    <extension title="Real World Extension">
     <p>Now you have created the Mailing list forms you should know which files are needed to create your own validating forms. The possibities are endless now that you can add dynamic forms to your Cocoon run site. </p>
     <ul>
       <li>A simple shopping cart could be created using an XML database such as
         <link href="ext:xindice">Xindice</link>.</li>
       <li>Your site can now become more personalised and interactive for your visitors.  They can create their own login details and set their own preferences with a few simple forms.  Making your web site a home from home for them. </li>
       <li>You can now run surveys and tests from your site</li> 
       <li>Add a voting system for new features to be added on your site</li>
       <li>A suggestions/ feedback form</li>
       <li>A simple form asking for more information to be sent regarding your products</li>
     </ul>
    </extension> 
     
    <tips title="Tips">
     <p>If you have a problem running the example given you can try the following tips:</p>
     <ul>
        <li>Check the logs sometimes they have more information than displayed in your browser.</li>
        <li>Check the <link href="ext:mail-archive">mail archive</link> as the chances are somebody else has had a similar problem too!</li>        
        <li>Email <link href="mailto:heidi@kutcha.org">me</link> I will try to help you. Again please send the entire error message and all relevant information.  Please use the title "XMLForm Help" in your emails.</li>
        <li>Try the <link href="ext:cocoon/ml">Cocoon users mail list</link> and remember to post the whole error message and try to supply all relevant information for a quick reply.</li>
     </ul>
    </tips> 
    
    <references title="Related Resources">
      <p>Cocoon resources</p>
     <ul>
        <li>For all Cocoon basics see the <link href="ext:cocoon">Cocoon Web site</link>.</li>
        <li>For actions take a look at the <link href="ext:cocoon/actions">actions page</link>. Actions are Avalon Components, so you may want to read Avalon's Whitepaper for more information.</li>
       </ul>
        <p>XPath is simple to learn and the basis of JXPath.</p>
        <ul>
          <li>The W3C has a clear and simple <link href="ext:xpath-tut">tutorial</link>.</li>
      </ul>
        <p>JXPath is now at beta stage and is based on XPath.</p>
        <ul>
        	<li>To learn more vist the home of <link href="ext:jxpath">JXPath</link></li>
		</ul>
    </references>
    
    <feedback title="Feedback">
      <p>Needless to say this How-To was written with no intentional mistakes or errors but if you find any faults or can see any improvements, please email me, <link href="mailto:heidi@kutcha.org">Heidi</link> with them. I will do my upmost to keep this HowTo uptodate and error free.</p>
    </feedback>
  
</howto>
