You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by sh...@apache.org on 2002/06/01 15:18:09 UTC
cvs commit: xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard book.xml howto-xmlform-wizard.xml howto-xmlform-wizard-1.xml howto-xmlform-wizard-2.xml howto-xmlform-wizard-3.xml howto-xmlform-wizard-4.xml howto-xmlform-wizard-5.xml
shannon 2002/06/01 06:18:09
Added: src/documentation/xdocs/howto/xmlform-wizard book.xml
howto-xmlform-wizard.xml howto-xmlform-wizard-1.xml
howto-xmlform-wizard-2.xml
howto-xmlform-wizard-3.xml
howto-xmlform-wizard-4.xml
howto-xmlform-wizard-5.xml
Log:
Moved to better How-To location.
Fixed minor validation and navigation
issues. Could not preserve cvs history
because of filename changes. Changed
filenames to reflect proposed
filename conventions.
Revision Changes Path
1.1 xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../../dtd/book-cocoon-v10.dtd">
<book software="Apache Cocoon"
title="Apache Cocoon XMLForm HowTo"
copyright="1999-2002 The Apache Software Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="Navigation">
<menu-item label="Main" href="../../index.html"/>
</menu>
<menu label="How-Tos">
<menu-item label="Index" href="../index.html"/>
</menu>
<menu label="XMLForm Wizard">
<menu-item label="Introduction" href="howto-xmlform-wizard.html"/>
<menu-item label="Step 1" href="howto-xmlform-wizard-1.html"/>
<menu-item label="Step 2" href="howto-xmlform-wizard-2.html"/>
<menu-item label="Step 3" href="howto-xmlform-wizard-3.html"/>
<menu-item label="Step 4" href="howto-xmlform-wizard-4.html"/>
<menu-item label="Step 5" href="howto-xmlform-wizard-5.html"/>
</menu>
</book>
1.1 xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard.xml
Index: howto-xmlform-wizard.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XMLForm's HowTo</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
</header>
<body>
<s1 title="XMLForm's HowTo">
<p>XMLForm is a Cocoon form extension mechanism which was inspired by
<link href="http://jakarta.apache.org/struts/">Struts</link>
and
<link href="http://www.w3.org/MarkUp/Forms/">XForms</link>. It makes form creation and
validation a quick and easy addition to your site.
XMLForm is currently included in the Cocoon 2.1 distribution.
If you don't have this version, you can obtain if from CVS. See the
<link href="http://xml.apache.org/cocoon/">xml.apache.org</link> website for details.</p>
</s1>
<s1 title="Overview">
<p>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,
<link href="http://www.ascc.net/xml/resource/schematron/schematron.html">Schematron</link>
validation and XMLForm wizard. Following the Steps in the XMLForm Wizard makes this a quick and easy task.</p>
</s1>
<s1 title="Purpose">
<p>You will be able to automate two-way mapping between the HTML forms, XML and JavaBeans. XML schema languages are 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>
</s1>
<s1 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, Java, JavaBeans, XForms, XPath, Schematron and Cocoon actions. If you are unfamiliar with these technologies it is advised that you learn these concepts first.</p>
</s1>
<s1 title="Configuration Requirements">
<p>You will need the following:</p>
<ul>
<li>A servlet engine such as Tomcat.</li>
<li>JDK 1.2 or later</li>
</ul>
<p>Cocoon 2.1 CVS to be installed with the command:</p>
<source>build -Dinclude.webapp.libs=true webapp</source>
</s1>
<s1 title="Requisite Skills">
<p>Knowledge of basic Cocoon concepts, XML, XSL, HTML, Java, JavaBeans, XForms, XPath, Schematron and Cocoon actions.</p>
</s1>
<s1 title="5 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="howto-xmlform-wizard-1.html">Step 1: XMLForm markup language</link></li>
<li><link href="howto-xmlform-wizard-2.html">Step 2: Validation</link></li>
<li><link href="howto-xmlform-wizard-3.html">Step 3: JavaBean</link></li>
<li><link href="howto-xmlform-wizard-4.html">Step 4: HowtoWizardAction.java</link></li>
<li><link href="howto-xmlform-wizard-5.html">Step 5: Sitemap</link></li>
</ul>
</s1>
<s1 title="Summary">
<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="http://xml.apache.org/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 away 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>
<li>Even more exciting things as <strong>Web Services</strong> (think
<link href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">REST</link>) and
</li>
<li>Remote Portal Forms, by taking
<link href="http://my.netscape.com/publish/formats/rss-spec-0.91.html#example1">RSS</link>
to the new generation of dynamic federated content.
</li>
</ul>
<p>
You may now want to examing the XMLForm Feedback Wizard demo under webapp/samples/xmlform.
It shows a variety of XMLForm widgets as well as access to Form models which are not only
JavaBeans, but also DOM nodes.
</p>
</s1>
<s1 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 mail archives at <link href="http://marc.theaimsgroup.com">MARC: Mailing list ARChives at AIMS</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="http://xml.apache.org/cocoon/mail-lists.html">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>
<li>If you think you found a bug in the implementation or have a patch to contribute,
contact the XMLForm author: <link href="mailto:ivelin@apache.org">Ivelin Ivanov</link> </li>
</ul>
</s1>
<s1 title="Related resources/documents">
<s2 title="Cocoon">
<p>For all Cocoon basics see the <link href="http://xml.apache.org/cocoon">Cocoon Web site</link>. For actions take a look at the <link href=" http://xml.apache.org/cocoon/userdocs/concepts/actions.html">actions page</link>Actions are Avalon Components, so you may want to read Avalon's Whitepaper for more information.</p>
</s2>
<s2 title="XPath">
<p>XPath is simple to learn and the basis of JXPath. The W3C has a clear and simple <link href="http://www.w3schools.com/xpath/">tutorial</link>.</p>
</s2>
</s1>
<s1 title="Feedback">
<p>Needless to say this HowTo 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>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard-1.xml
Index: howto-xmlform-wizard-1.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XMLForm's HowTo Step 1</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
</header>
<body>
<s1 title="XMLForm's HowTo Step 1: XMLForm markup language">
<p>First we need to create our own forms in XML.</p>
<ul>
<li>Create a folder called "howto" in src\webapp\sample\xmlform.</li>
<li>Copy the following xml files below and save them in the folder you created.</li>
</ul>
<s2 title="start.xml">
<p>Below is the first page which you can copy and save as start.xml in the folder src\webapp\mount\xmlform\howto</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document>
<br/><br/><br/>
<table align="center" width="50%" cellspacing="20">
<tr>
<td align="center">
<h1>
Welcome to the XLMForm HowTo!
</h1>
</td>
</tr>
<tr>
<td align="center" class="info">
<code>
The following form allows users to join mailing lists.
They are given a choice of areas of interest.
Depending on their interests they will see a selection of mailing lists which they can sign up to.
</code>
</td>
</tr>
<tr>
<td align="center">
<h3>
<a href="howto-wizard.html?cocoon-action-start=true">
Start!
</a>
</h3>
</td>
</tr>
</table>
</document>
]]>
</source>
<p>The important part to notice is the link: </p>
<source>
<![CDATA[
<a href="howto-wizard.html?cocoon-action-start=true">
]]>
</source>
<p>The text between "cocoon-action" and "=true" is passed to the method prepare of HowtoWizardAction.java which we will write soon.</p>
</s2>
<p>Next are the actual XML pages that make up the form. These are:</p>
<ul>
<li>registration.xml</li>
<li>interest.xml</li>
<li>organicGardening.xml</li>
<li>cooking.xml</li>
<li>smallholding.xml</li>
<li>confirm.xml</li>
<li>end.xml</li>
</ul>
<s2 title="register.xml">
<p>registration.xml lets the user register their username, password and email address so they can join the mailing lists they will next choose.</p>
<p>The important part of the form you will need to change in your own forms are inside the xf:form tag. The id attribute value should match the sitemaps xmlform-id parameters value:</p>
<source>
<![CDATA[
<map:parameter name="xmlform-id" value="form-feedback"/>
]]>
</source>
<p>The view attribute should contain the name of the current xml file, the action attribute should contain the name of the url you are using in the sitemap.</p>
<p>The caption tag is the page heading. Next we have the error tags which are used if you have a validation set in your sitemap. If an error is found then this will display them when the user clicks the next button on your form.</p>
<p>Now we see the input options for the user, such as xf:textbox which will display a textbox. Each such option has a ref attribute which is very important as this is the value we will map to the JavaBean. If we are validating this input then it must have a violations tag inside it. The violations tag serves as a container or place holder for validation errors. It has a single optional attribute "class" which refers to the CSS class to use when displaying validation errors.</p>
<p>Finally the form needs a submit tag. This lets the user navigate forward to the rest of the form.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002">
<xf:form id="form-feedback" view="registration" action="howto-wizard.html">
<xf:caption>Registration</xf:caption>
<error>
<xf:violations class="error"/>
</error>
<xf:textbox ref="/userName">
<xf:caption>Last Name</xf:caption>
<xf:violations class="error"/>
</xf:textbox>
<xf:textbox ref="/email">
<xf:caption>Email</xf:caption>
<xf:violations class="error"/>
</xf:textbox>
<xf:password ref="/password">
<xf:caption>Password</xf:caption>
<xf:violations class="error"/>
</xf:password>
<xf:submit id="next" class="button">
<xf:caption>Next</xf:caption>
</xf:submit>
</xf:form>
</document>
]]>
</source>
</s2>
<s2 title="interest.xml">
<p>This XML page lets the user select areas of interest and depending on their answers they will be shown a selection of mailing lists they can join. The intelligence for deciding which pages to show next are in a java file which we will show you how to write later.</p>
<p>This page consists of tick boxes which are either true or false.</p>
<source>
<![CDATA[
<xf:selectBoolean ref="/organicGardening">
<xf:caption>Organic Gardening</xf:caption>
</xf:selectBoolean>
]]>
</source>
<p>Below is the page which you can copy into the folder "howto".</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002">
<xf:form id="form-feedback" view="interest" action="howto-wizard.html">
<xf:caption>Areas of Interest</xf:caption>
<xf:selectBoolean ref="/organicGardening">
<xf:caption>Organic Gardening</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/cooking">
<xf:caption>Cooking</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/smallholdingManagement">
<xf:caption>Smallholding Management</xf:caption>
</xf:selectBoolean>
<xf:submit id="prev" class="button">
<xf:caption>Prev</xf:caption>
</xf:submit>
<xf:submit id="next" class="button">
<xf:caption>Next</xf:caption>
</xf:submit>
</xf:form>
</document>
]]>
</source>
</s2>
<s2 title="organicGardening.xml">
<p>The next page is shown if the user ticked the organic gardening box in the previous page, interest.xml. This page consists a selection of mailing lists the user can chose. It is very similar to the previous page containing 3 tick boxes. The user has the choice of moving forward through the form or back to the previous page so they can alter their area of interest.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002">
<xf:form id="form-feedback" view="organicGardening" action="howto-wizard.html">
<xf:caption>Organic Gardening Mailing Lists:</xf:caption>
<xf:selectBoolean ref="/flowers">
<xf:caption>Flowers</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/vegetables">
<xf:caption>Vegetables</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/fruitTrees">
<xf:caption>Fruit Trees</xf:caption>
</xf:selectBoolean>
<xf:submit id="prev" class="button">
<xf:caption>Prev</xf:caption>
</xf:submit>
<xf:submit id="next" class="button">
<xf:caption>Next</xf:caption>
</xf:submit>
</xf:form>
</document>
]]>
</source>
</s2>
<s2 title="cooking.xml">
<p>The next page is a selection of cookery mailing lists, very similar to the organicGardening.xml page. This page will appear if the user ticked the organic gardening option on the interest.xml page.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002">
<xf:form id="form-feedback" view="cooking" action="howto-wizard.html">
<xf:caption>Cooking Mailing Lists:</xf:caption>
<xf:selectBoolean ref="/traditionalReciepes">
<xf:caption>Traditional Reciepes</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/soups">
<xf:caption>Soups</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/veganCookery">
<xf:caption>Vegan Cookery</xf:caption>
</xf:selectBoolean>
<xf:submit id="prev" class="button">
<xf:caption>Prev</xf:caption>
</xf:submit>
<xf:submit id="next" class="button">
<xf:caption>Next</xf:caption>
</xf:submit>
</xf:form>
</document>
]]>
</source>
</s2>
<s2 title="smallholdingManagement.xml">
<p>Again this page is similar to organicGardening.xml, cooking.xml as it gives the user a choice of mailing lists. This page will only appear if the user selected Smallholding Management as an interest on the interest.xml page.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002">
<xf:form id="form-feedback" view="smallholdingManagement" action="howto-wizard.html">
<xf:caption>Smallholding Management Mailing Lists</xf:caption>
<xf:selectBoolean ref="/pigKeeping">
<xf:caption>Pig Keeping</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/pygmyGoats">
<xf:caption>Pygmy Goats</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/henKeeping">
<xf:caption>Hen Keeping</xf:caption>
</xf:selectBoolean>
<xf:submit id="prev" class="button">
<xf:caption>Prev</xf:caption>
</xf:submit>
<xf:submit id="next" class="button">
<xf:caption>Next</xf:caption>
</xf:submit>
</xf:form>
</document>
]]>
</source>
</s2>
<s2 title="confirm.xml">
<p>This page shows the user the data that has been collected from them. The JavaBean that stores all the data is queried and the information collected is displayed. This is done using the xf:output tag, specifying which value to display with the ref attribute. If they wish to change any of the information they can do this now by clicking the previous button and altering their answers. Otherwise they can click the finish button which will take them to the end page, end.xml.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002">
<xf:form id="form-feedback" view="confirm" action="howto-wizard.html">
<xf:caption>Confirm Input</xf:caption>
<!-- from page1 -->
<xf:output ref="/userName">
<xf:caption>User Name</xf:caption>
</xf:output>
<xf:output ref="/email">
<xf:caption>Email</xf:caption>
</xf:output>
<xf:output ref="/password">
<xf:caption>Password</xf:caption>
</xf:output>
<!-- from page2 -->
<xf:output ref="/organicGardening">
<xf:caption>Organic Gardening</xf:caption>
</xf:output>
<xf:output ref="/cooking">
<xf:caption>Cooking</xf:caption>
</xf:output>
<xf:output ref="/smallholdingManagement">
<xf:caption>Smallholding Management</xf:caption>
</xf:output>
<!-- from page3 -->
<xf:output ref="/flowers">
<xf:caption>Flowers</xf:caption>
</xf:output>
<xf:output ref="/vegetables">
<xf:caption>Vegetables</xf:caption>
</xf:output>
<xf:output ref="/fruitTrees">
<xf:caption>Fruit Trees</xf:caption>
</xf:output>
<!-- from page4 -->
<xf:output ref="/traditionalReciepes">
<xf:caption>Traditional Reciepes</xf:caption>
</xf:output>
<xf:output ref="/soups">
<xf:caption>Soups</xf:caption>
</xf:output>
<xf:output ref="/veganCookery">
<xf:caption>Vegan Cooking</xf:caption>
</xf:output>
<!-- from page5 -->
<xf:output ref="/pigKeeping">
<xf:caption>Pig Keeping</xf:caption>
</xf:output>
<xf:output ref="/pygmyGoats">
<xf:caption>Pygmy Goats</xf:caption>
</xf:output>
<xf:output ref="/henKeeping">
<xf:caption>Hen Keeping</xf:caption>
</xf:output>
<!-- submit -->
<xf:submit id="prev" class="button">
<xf:caption>Prev</xf:caption>
</xf:submit>
<xf:submit id="next" class="button">
<xf:caption>Finish</xf:caption>
</xf:submit>
</xf:form>
</document>
]]>
</source>
</s2>
<s2 title="end.xml">
<p>This page displays the final page. It tells the reader they have succesfully filled in the form and gives them the option to return to the start.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<document>
<br/><br/><br/>
<table align="center" width="50%" cellspacing="20">
<tr>
<td align="center">
<h1>
You have reached the last page of the How To Form example!
</h1>
</td>
</tr>
<tr>
<td align="center" class="info">
<code>
Your registration form was processed successfully.
</code>
</td>
</tr>
<tr>
<td align="center">
<h3>
<a href="howto-wizard.html">Go to home page.</a>
</h3>
</td>
</tr>
</table>
</document>
]]>
</source>
</s2>
<p><link href="howto-xmlform-wizard-2.html">Step 2: Validation</link></p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard-2.xml
Index: howto-xmlform-wizard-2.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XMLForm's HowTo Step 2</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
</header>
<body>
<s1 title="XMLForm's HowTo Step 2: Validation">
<p>The next step validation is optional, you do not have to validate your forms but its very easy to do so, so we will.</p>
<p>In the sitemap there are 2 parameters, xmlform-validator-schema and xmlform-validator-schema-ns. If these are left empty then no validation will be carried out. xmlform-validator-schema contains the name of the xml schema file we are using and xmlform-validator-schema-ns is the validator namespace we are using. Below are the 2 parameters in the sitemap we are referring to.</p>
<source>
<![CDATA[
<map:parameter name="xmlform-validator-schema-ns" value="http://www.ascc.net/xml/schematron"/>
<map:parameter name="xmlform-validator-schema" value="schematron/wizard-xmlform-sch-report.xml"/>
]]>
</source>
<p>Copy the "howto-xmlform-sch-report.xml" and place this in the folder src\scratchpad\webapp\samples\xmlform\howto\schematron.</p>
<p>The schema is simple and only validates the registration.xml page. The phase tag relates to an xml page that contains values which will be validated. The id attribute contains the page name. Inside the phase tag is the active tag which contains the pattern attribute which match up to the pattern tags below. Each pattern can contain one or more rule tags. Each rule tag has a context attribute which maps to a javaBean value, for example userName. Nested inside the rule tag is one or more assert tag. Each assert tag contains a test attribute. The test value can check the value passes certain criteria, for example, the value is more than 7 characters long. Nested between the beginning and closing assert tags is an error message which will be displayed if the test is not met.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<schema ns="http://xml.apache.cocoon/xmlform" xmlns="http://www.ascc.net/xml/schematron">
<title>Schema for the XML Form example</title>
<phase id="registration">
<p>For user identity information.</p>
<active pattern="reg"/>
</phase>
<phase id="confirm">
<p>For final total validation and tracking
some tricky problems.</p>
<active pattern="reg" />
</phase>
<pattern name="User Info Validation Pattern" id="reg">
<rule context="/userName">
<assert test="string-length(.) > 7">
Username should be at least 8 characters.
</assert>
<assert test="string-length(.) < 20">
Username should be less than 20 characters.
</assert>
</rule>
<rule context="/password">
<assert test="string-length(.) > 7">
Password should be at least 8 characters.
</assert>
<assert test="string-length(.) < 20">
Password should be less than 20 characters.
</assert>
</rule>
<rule context="/email">
<assert test="contains( string(.),'@')">
Email format is invalid.
</assert>
</rule>
</pattern>
</schema>
]]>
</source>
<p>Now you are ready for <link href="howto-xmlform-wizard-3.html">Step 3: Form instance model</link> </p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard-3.xml
Index: howto-xmlform-wizard-3.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XMLForm's HowTo Step 3</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
</header>
<body>
<s1 title="XMLForm's HowTo Step 3: Form instance model">
<s2 title="HowToBean.java">
<p>Next we create the simple JavaBean which holds the data filled in the form. Each value has a set and get method. Each value must map with the form data. This is done using
<link href="http://jakarta.apache.org/commons/jxpath/index.html">JXPath</link> (an XPath implementation applicable for JavaBeans, DOM nodes and mix of the two).
</p>
<p>Copy the file below and save it as HowToBean.java in the folder \src\java\org\apache\cocoon\samples\xmlform\howto</p>
<source>
<![CDATA[
package org.apache.cocoon.samples.xmlform.howto;
import java.util.Set;
import java.util.HashSet;
import java.util.List;
import java.util.ArrayList;
import org.w3c.dom.*;
import javax.xml.parsers.*;
import javax.xml.transform.*;
/**
*
* A sample JavaBean used as a Form model.
*
*/
public class HowToBean
{
private String username = "DonaldDuck";
private String email = "donald@disney.com";
private String password = "secret123";
private boolean organicGardening = true;
private boolean cooking = true;
private boolean smallholdingManagement = true;
private boolean flowers = true;
private boolean vegetables = true;
private boolean fruitTrees = true;
private boolean traditionalReciepes = true;
private boolean soups = true;
private boolean veganCookery = true;
private boolean pigKeeping = true;
private boolean pygmyGoats = true;
private boolean henKeeping = true;
private Node system;
public HowToBean ()
{
}
public String getUserName() {
return username;
}
public void setUserName(String newUserName) {
username = newUserName;
}
public String getPassword() {
return password;
}
public void setPassword(String newPassword) {
password = newPassword;
}
public String getEmail() {
return email;
}
public void setEmail(String newEmail) {
email = newEmail;
}
public boolean getOrganicGardening()
{
return organicGardening;
}
public void setOrganicGardening( boolean newOrganicGardening )
{
organicGardening = newOrganicGardening;
}
public boolean getCooking()
{
return cooking;
}
public void setCooking( boolean newCooking )
{
cooking = newCooking;
}
public boolean getSmallholdingManagement()
{
return smallholdingManagement;
}
public void setSmallholdingManagement( boolean newSmallholdingManagement )
{
smallholdingManagement = newSmallholdingManagement;
}
public boolean getFlowers()
{
return flowers;
}
public void setFlowers( boolean newFlowers )
{
flowers = newFlowers;
}
public boolean getVegetables()
{
return vegetables;
}
public void setVegetables( boolean newVegetables )
{
vegetables = newVegetables;
}
public boolean getFruitTrees()
{
return fruitTrees;
}
public void setFruitTrees( boolean newFruitTrees )
{
fruitTrees = newFruitTrees;
}
public boolean getTraditionalReciepes()
{
return traditionalReciepes;
}
public void setTraditionalReciepes( boolean newTraditionalReciepes )
{
traditionalReciepes = newTraditionalReciepes;
}
public boolean getSoups()
{
return soups;
}
public void setSoups( boolean newSoups )
{
soups = newSoups;
}
public boolean getVeganCookery()
{
return veganCookery;
}
public void setVeganCookery( boolean newVeganCookery )
{
veganCookery = newVeganCookery;
}
public boolean getPigKeeping()
{
return pigKeeping;
}
public void setPigKeeping( boolean newPigKeeping )
{
pigKeeping = newPigKeeping;
}
public boolean getPygmyGoats()
{
return pygmyGoats;
}
public void setPygmyGoats( boolean newPygmyGoats )
{
pygmyGoats = newPygmyGoats;
}
public boolean getHenKeeping()
{
return henKeeping;
}
public void setHenKeeping( boolean newHenKeeping )
{
henKeeping = newHenKeeping;
}
}
]]>
</source>
<p>Now we move on to <link href="howto-xmlform-wizard-4.html">Step 4: Writing the Action</link></p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard-4.xml
Index: howto-xmlform-wizard-4.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XMLForm's HowTo Step 4</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
</header>
<body>
<s1 title="XMLForm's HowTo Step 4: Writing the Action">
<p>HowtoWizardAction.java is based on the WizardAction.java, which is part of the XMLForm feedback wizard demo distributed with Cocoon. The prepare, perform and reset methods need to be altered. You also need to define the pages which comprise the navigation states.</p>
<s2 title="XML Pages defined">
<source>
<![CDATA[
// different form views
// participating in the wizard
final String VIEW_START = "start";
final String VIEW_REGISTRATION = "registration";
final String VIEW_INTEREST = "interest";
final String VIEW_GARDENING = "organicGardening";
final String VIEW_COOKING = "cooking";
final String VIEW_SMALLHOLDING = "smallholdingManagement";
final String VIEW_CONFIRM = "confirm";
final String VIEW_END = "end";
]]>
</source>
</s2>
<s2 title="Prepare Method">
<p>This method prepares the form and the pages to be returned before the actual form population starts.</p>
<p>The first time the URL http://localhost:8080/cocoon/mount/xmlform/howto-wizard.html is called there is no command passed so the if statement test is met and the start page is returned.</p>
<p>After the start page has been viewed and the user clicks on "Start" the command start is passed so the else test is met and the registration page is returned. Any old forms are removed and a form listener is added to the form.</p>
<p>If neither of these tests are met then nothing is returned.</p>
<source>
<![CDATA[
package org.apache.cocoon.samples.xmlform.howto;
// Java classes
import java.util.Map;
import java.util.HashMap;
import java.util.SortedSet;
import java.util.Iterator;
import java.util.Properties;
import java.io.InputStream;
import java.io.FileInputStream;
import java.io.File;
// XML classes
import javax.xml.transform.stream.StreamSource;
import javax.xml.transform.TransformerException;
import org.xml.sax.InputSource;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
// Framework classes
import org.apache.avalon.framework.parameters.Parameters;
import org.apache.avalon.excalibur.pool.Poolable;
import org.apache.avalon.framework.configuration.Configuration;
import org.apache.avalon.framework.configuration.ConfigurationException;
// Cocoon classes
import org.apache.cocoon.environment.Redirector;
import org.apache.cocoon.environment.SourceResolver;
import org.apache.cocoon.acting.*;
import org.apache.cocoon.environment.Request;
import org.apache.cocoon.environment.ObjectModelHelper;
import org.apache.cocoon.environment.Session;
import org.apache.cocoon.environment.Context;
// Schematron classes
import org.apache.cocoon.validation.SchemaFactory;
import org.apache.cocoon.validation.Schema;
import org.apache.cocoon.validation.Validator;
import org.apache.cocoon.validation.Violation;
// Cocoon XMLForm
import org.apache.cocoon.acting.AbstractXMLFormAction;
import org.apache.cocoon.xmlform.Form;
import org.apache.cocoon.xmlform.FormListener;
/**
* This action demonstrates
* a relatively complex form handling scenario.
*
* @author Heidi Brannan, heidi@wkwyw.net
*/
public class HowtoWizardAction
extends AbstractXMLFormAction
implements FormListener
{
// different form views
// participating in the wizard
final String VIEW_START = "start";
final String VIEW_REGISTRATION = "registration";
final String VIEW_INTEREST = "interest";
final String VIEW_GARDENING = "organicGardening";
final String VIEW_COOKING = "cooking";
final String VIEW_SMALLHOLDING = "smallholdingManagement";
final String VIEW_CONFIRM = "confirm";
final String VIEW_END = "end";
// action commands used in the wizard
final String CMD_START = "start";
final String CMD_NEXT = "next";
final String CMD_PREV = "prev";
/**
* The first callback method which is called
* when an action is invoked.
*
* It is called before population.
*
*
* @return null if the Action is prepared to continue.
* an objectModel map which will be immediately returned by the action.
*
* This method is a good place to handle buttons with Cancel
* kind of semantics. For example
* <pre>if getCommand().equals("Cancel") return page("input");</pre>
*
*/
protected Map prepare()
{
if ( getCommand() == null )
{
return page( VIEW_START );
}
else if ( getCommand().equals( CMD_START ) )
{
// reset state by removing old form
// if one exists
Form.remove( getObjectModel(), getFormId() );
getForm().addFormListener( this );
return page( VIEW_REGISTRATION );
}
// get ready for action
// if not ready return page("whereNext");
return null;
}
/**
* Invoked after form population
*
* Semanticly similar to Struts Action.perform()
*
* Take appropriate action based on the command
*
*/
public Map perform ()
{
// get the actual model which this Form encapsulates
// and apply additional buziness logic to the model
HowToBean jBean = (HowToBean) getForm().getModel();
//jBean.incrementCount();
// set the page control flow parameter
// according to the validation result
if ( getCommand().equals( CMD_NEXT ) &&
getForm().getViolations () != null )
{
// errors, back to the same page
return page( getFormView() );
}
else
{
// validation passed
// continue with control flow
// clear validation left overs in case the user
// did not press the Next button
getForm().clearViolations();
// get the user submitted command (through a submit button)
String command = getCommand();
// get the form view which was submitted
String formView = getFormView();
// apply control flow rules
if ( formView.equals ( VIEW_REGISTRATION ) )
{
if ( command.equals( CMD_NEXT ) )
{
return page( VIEW_INTEREST );
}
}
else if ( formView.equals ( VIEW_INTEREST ) )
{
if ( command.equals( CMD_NEXT ) )
{
if ( jBean.getOrganicGardening() == true )
{
return page( VIEW_GARDENING );
}
else if ( jBean.getCooking() == true )
{
return page( VIEW_COOKING );
}
else if ( jBean.getSmallholdingManagement() == true )
{
return page( VIEW_SMALLHOLDING );
}
//else if ( getForm().get
return page( VIEW_CONFIRM );
}
if ( command.equals( CMD_PREV ) )
{
return page( VIEW_REGISTRATION );
}
}
else if ( formView.equals ( VIEW_GARDENING ) )
{
if ( command.equals ( CMD_NEXT ) )
{
if ( jBean.getCooking() == true )
{
return page( VIEW_COOKING );
}
else if ( jBean.getSmallholdingManagement() == true )
{
return page( VIEW_SMALLHOLDING );
}
return page( VIEW_CONFIRM );
}
else if( command.equals( CMD_PREV ) )
{
return page( VIEW_INTEREST );
}
}
else if ( formView.equals ( VIEW_COOKING ) )
{
if ( command.equals ( CMD_NEXT ) )
{
if ( jBean.getSmallholdingManagement() == true )
{
return page( VIEW_SMALLHOLDING );
}
return page( VIEW_CONFIRM );
}
else if ( command.equals( CMD_PREV ) )
{
if ( jBean.getOrganicGardening() == true )
{
return page( VIEW_GARDENING );
}
return page( VIEW_INTEREST );
}
}
else if ( formView.equals ( VIEW_SMALLHOLDING ) )
{
if ( command.equals( CMD_NEXT ) )
{
return page( VIEW_CONFIRM );
}
else if ( command.equals( CMD_PREV ) )
{
if ( jBean.getCooking() == true )
{
return page( VIEW_COOKING );
}
else if ( jBean.getOrganicGardening() == true )
{
return page( VIEW_GARDENING );
}
return page( VIEW_INTEREST );
}
}
else if ( formView.equals ( VIEW_CONFIRM ) )
{
if ( command.equals( CMD_NEXT ) )
{
return page( VIEW_END );
}
else if( command.equals( CMD_PREV ) )
{
if ( jBean.getOrganicGardening() == true )
{
return page( VIEW_GARDENING );
}
return page( VIEW_INTEREST );
}
}
}
// should never reach this statement
return page( VIEW_START );
}
/**
*
* FormListener callback
* called in the beginning Form.populate()
* before population starts.
*
* This is the place to handle unchecked checkboxes.
*
*/
public void reset( Form form )
{
// based on the current form view
// make some decisions regarding checkboxes, etc.
String formView = getFormView();
if ( formView.equals ( VIEW_INTEREST ) )
{
// deal with the organicGardening checkbox
form.setValue( "/organicGardening", Boolean.FALSE );
// deal with the cooking checkbox
form.setValue( "/cooking", Boolean.FALSE );
// deal with the smallholdingManagement checkbox
form.setValue( "/smallholdingManagement", Boolean.FALSE );
}
else if ( formView.equals ( VIEW_GARDENING ) )
{
// deal with the flowers checkbox
form.setValue( "/flowers", Boolean.FALSE );
// deal with the vegetables checkbox
form.setValue( "/vegetables", Boolean.FALSE );
// deal with the fruitTrees checkbox
form.setValue( "/fruitTrees", Boolean.FALSE );
}
else if ( formView.equals ( VIEW_COOKING ) )
{
// deal with the traditionalReciepes checkbox
form.setValue( "/traditionalReciepes", Boolean.FALSE );
// deal with the soups checkbox
form.setValue( "/soups", Boolean.FALSE );
// deal with the veganCookery checkbox
form.setValue( "/veganCookery", Boolean.FALSE );
}
else if ( formView.equals ( VIEW_SMALLHOLDING ) )
{
// deal with the pigKeeping checkbox
form.setValue( "/pigKeeping", Boolean.FALSE );
// deal with the pygmyGoats checkbox
form.setValue( "/pygmyGoats", Boolean.FALSE );
// deal with the henKeeping checkbox
form.setValue( "/henKeeping", Boolean.FALSE );
}
}
/**
* FormListener callback
*
* Invoked during Form.populate();
*
* It is invoked before a request parameter is mapped to
* an attribute of the form model.
*
* It is appropriate to use this method for filtering
* custom request parameters which do not reference
* the model.
*
* Another appropriate use of this method is for graceful filtering of invalid
* values, in case that knowledge of the system state or
* other circumstainces make the standard validation
* insufficient. For example if a registering user choses a username which
* is already taken - the check requires database transaction, which is
* beyond the scope of document validating schemas.
* Of course customized Validators can be implemented to do
* this kind of domain specific validation
* instead of using this method.
*
*
* @return false if the request parameter should not be filtered.
* true otherwise.
*/
public boolean filterRequestParameter (Form form, String parameterName)
{
// TBD
return false;
}
public String getFile( String FileName ) {
try
{
final String FILE_PREFIX = "file:";
String path = getSourceResolver().resolve(FileName).getSystemId();
if(path.startsWith(FILE_PREFIX))
path = path.substring(FILE_PREFIX.length());
return path;
}
catch(Exception e)
{
getLogger().error("could not read mapping file",e);
return null;
}
}
private Validator validator_ = null;
private boolean initialized_ = false;
}
]]>
</source>
</s2>
<p>Finally <link href="howto-xmlform-wizard-5.html">Step 5: The Sitemap</link></p>
</s1>
</body>
</document>
1.1 xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard-5.xml
Index: howto-xmlform-wizard-5.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XMLForm's HowTo Step 5</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
</header>
<body>
<s1 title="XMLForm's HowTo Step 5: The Sitemap">
<p>The Sitemap finally pulls all the previous files together into an understandable whole.</p>
<p>In the components section we add a map:action tag named HowToWizardAction. This points to the Java file HowToWizardAction which we met in step 4.</p>
<source>
<![CDATA[
<!-- =========================== Components ================================ -->
<map:components>
<map:actions>
<map:action name="WizardAction" src="org.apache.cocoon.samples.xmlform.WizardAction"
logger="webapp.xmlform"/>
<map:action name="HowtoWizardAction" src="org.apache.cocoon.samples.xmlform.howton.HowtoWizardAction"
logger="webapp.xmlform"/>
</map:actions>
<map:generators default="file"/>
<map:transformers default="xslt">
<map:transformer name="xmlform" src="org.apache.cocoon.transformation.XMLFormTransformer"
logger="webapp.xmlform"/>
</map:transformers>
<map:readers default="resource"/>
<map:serializers default="html"/>
<map:selectors default="browser"/>
<map:matchers default="wildcard">
<map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
</map:matchers>
</map:components>
]]>
</source>
<p>We add to the pipeline the following tags:</p>
<source>
<![CDATA[
<!-- A non-trivial example - Feedback HowTo Wizard -->
<map:match pattern="howto-wizard.html">
<map:act type="HowtoWizardAction">
<!-- XMLForm parameters for the HowtoWizardAction -->
<map:parameter name="xmlform-validator-schema-ns" value="http://www.ascc.net/xml/schematron"/>
<map:parameter name="xmlform-validator-schema" value="howto/schematron/howto-xmlform-sch-report.xml"/>
<map:parameter name="xmlform-id" value="form-feedback"/>
<map:parameter name="xmlform-scope" value="session"/>
<map:parameter name="xmlform-model" value="org.apache.cocoon.samples.xmlform.howto.HowToBean"/>
<!-- Content transformation logic -->
<map:generate src="howto/{page}.xml"/>
<map:transform type="xmlform" label="xml"/>
<map:transform src="stylesheets/wizard2html.xsl"/>
<map:transform src="context://stylesheets/xmlform/xmlform2html.xsl"/>
<map:serialize type="html"/>
</map:act>
</map:match>
]]>
</source>
<p>The whole sitemap.xmap is below so you can just copy this over your current sitemap if you like. Your current sitemap is located in \src\webapp\samples\xmlform</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<!-- =========================== Components ================================ -->
<map:components>
<map:actions>
<map:action name="WizardAction" src="org.apache.cocoon.samples.xmlform.WizardAction"
logger="webapp.xmlform"/>
<map:action name="HowtoWizardAction" src="org.apache.cocoon.samples.xmlform.howto.HowtoWizardAction"
logger="webapp.xmlform"/>
</map:actions>
<map:generators default="file"/>
<map:transformers default="xslt">
<map:transformer name="xmlform" src="org.apache.cocoon.transformation.XMLFormTransformer"
logger="webapp.xmlform"/>
</map:transformers>
<map:readers default="resource"/>
<map:serializers default="html"/>
<map:selectors default="browser"/>
<map:matchers default="wildcard">
<map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
</map:matchers>
</map:components>
<!-- =========================== Resources ================================= -->
<map:resources>
</map:resources>
<!-- =========================== Pipelines ================================= -->
<map:pipelines>
<map:pipeline>
<map:match pattern="">
<map:redirect-to uri="wizard.html"/>
</map:match>
<!-- A non-trivial example - Feedback Wizard -->
<map:match pattern="wizard.html">
<map:act type="WizardAction">
<!-- XMLForm parameters for the AbstractXMLFormAction -->
<map:parameter name="xmlform-validator-schema-ns" value="http://www.ascc.net/xml/schematron"/>
<map:parameter name="xmlform-validator-schema" value="schematron/wizard-xmlform-sch-report.xml"/>
<map:parameter name="xmlform-id" value="form-feedback"/>
<map:parameter name="xmlform-scope" value="session"/>
<map:parameter name="xmlform-model" value="org.apache.cocoon.samples.xmlform.UserBean"/>
<!-- Content transformation logic -->
<map:generate src="wizard/{page}.xml"/>
<map:transform type="xmlform" label="xml"/>
<map:transform src="stylesheets/wizard2html.xsl"/>
<map:transform src="context://stylesheets/xmlform/xmlform2html.xsl"/>
<map:serialize type="html"/>
</map:act>
</map:match>
<!-- A non-trivial example - Feedback HowTo Wizard -->
<map:match pattern="howto-wizard.html">
<map:act type="HowtoWizardAction">
<!-- XMLForm parameters for the HowtoWizardAction -->
<map:parameter name="xmlform-validator-schema-ns" value="http://www.ascc.net/xml/schematron"/>
<map:parameter name="xmlform-validator-schema" value="howto/schematron/howto-xmlform-sch-report.xml"/>
<map:parameter name="xmlform-id" value="form-howto"/>
<map:parameter name="xmlform-scope" value="session"/>
<map:parameter name="xmlform-model" value="org.apache.cocoon.samples.xmlform.howto.HowToBean"/>
<!-- Content transformation logic -->
<map:generate src="howto/{page}.xml"/>
<map:transform type="xmlform" label="xml"/>
<map:transform src="stylesheets/wizard2html.xsl"/>
<map:transform src="context://stylesheets/xmlform/xmlform2html.xsl"/>
<map:serialize type="html"/>
</map:act>
</map:match>
</map:pipeline>
</map:pipelines>
</map:sitemap>
<!-- end of file -->
]]>
</source>
<p>Congratulations! Now you have covered everything you need to create the mailing list forms. Now all you need to do is to build the files and then deploy them in your web server.</p>
<p>Use the command:</p>
<p>build webapp -Dinclude.webapp.libs=true webapp</p>
<p>Place cocoon.war in your webapp folder if you are using Tomcat then restart Tomcat.</p>
<p>In a browser go to http://localhost:8080/cocoon/samples/xmlform/howto-wizard.html and you should see the start page of the mailing list forms.</p>
<p>To return to the <link href="howto-xmlform-wizard.html">start</link></p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org