shannon 2002/06/10 06:15:24
Modified: src/documentation/xdocs/howto/xmlform-wizard Tag:
cocoon_2_0_3_branch howto-xmlform-wizard-1.xml
Log:
sync with HEAD
Revision Changes Path
No revision
No revision
1.2.2.2 +99 -68
xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard-1.xml
Index: howto-xmlform-wizard-1.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard-1.xml,v
retrieving revision 1.2.2.1
retrieving revision 1.2.2.2
diff -u -r1.2.2.1 -r1.2.2.2
--- howto-xmlform-wizard-1.xml 7 Jun 2002 19:49:00 -0000 1.2.2.1
+++ howto-xmlform-wizard-1.xml 10 Jun 2002 13:15:24 -0000 1.2.2.2
@@ -5,7 +5,7 @@
<title>XMLForm Wizard's How-To Step 1</title>
<authors>
- <person name="Heidi Brannan"
+ <person name="Heidi-Marie Brannan"
email="[EMAIL PROTECTED]" />
</authors>
</header>
@@ -14,6 +14,7 @@
<s1 title="Step 1: XMLForm markup language">
<fixme author="DS">It may help to use screen shots here. It gets a bit
confusing, otherwise. What do you think?</fixme>
+ <fixme author="HB">Will do so when I can find the time.</fixme>
<p>First, we need to create our own form pages in XML.</p>
@@ -78,48 +79,41 @@
]]>
</source>
- <fixme author="DS">Isn't the relevant text what is between
- "cocoon-action-" and "=true"? Note the addition of the
- hyphen after cocoon-action.</fixme>
-
- <p>The text between "cocoon-action" and "=true" is
+ <p>The text between "cocoon-action-" and "=true" is
passed to the method prepare of HowtoWizardAction.java (to be written
- in a next step). In the above case, this value to be passed is
- "-start".</p>
+ in step 4). In the above case, the value to be passed is
+ "start". This command, "start", will reset the state of
+ the form by removing any remaining form values.</p>
</s2>
- <fixme author="DS">Isn't start.xml, described earlier also an
- "actual XML page". What do you mean below?</fixme>
-
- <p>Next are the actual XML pages that make up the form. These are:</p>
+ <p>The remaining XML pages are listed below in order:</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">
- <fixme author="DS">Which is correct The title above, registration.xml,
- or the reference below to register.xml?</fixme>
+ <s2 title="registration.xml">
<p>registration.xml lets the user register a username, password and
email address in order to join the mailing lists (chosen next).</p>
-
- <p>The important part of the form, which you will need to change in
- your own forms, is located inside the xf:form tag. Make sure the value
- of the xf:form's id attribute, form-feedback, is matched by the
- sitemap's map:parameter name-value pair shown here:</p>
+
+ <p>XMLForms has the ability to choose the scope of form persistence
+ to be either per-session or per-request. This is selected in the
+ xmlform-scope parameter when the action is set up in the sitemap.
+ In forms that span multiple screens, you will always want to use
+ per-session. Additionally, multiple forms can be active at once.
+ The xf:form's id attribute is the discriminator that allows this
+ functionality. </p>
+ <p> It is mentioned early because this discriminator is also required
+ in the form source themselves. Our session identifier (as seen in
+ registration.xml below in the xf:form element), form-feedback, is
+ matched by the sitemap's map:parameter name-value pair shown here:</p>
<source>
@@ -127,32 +121,43 @@
</source>
- <fixme author="DS">This is confusing. Your view is named register,
- your filename is registration. You appear to be contradicting your own
- instructions.</fixme>
-
- <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>
-
- <fixme author="DS">Should you show how validation is set in the
- sitemap, or does that appear later?</fixme>
-
- <p>The caption element is the page heading. Next, we have error
- elements which are used if you have a validation set in your sitemap.
- When an error is found, the error will be displayed once the user
+ <p>The view attribute of the xf:form element should contain the name of
+ the current xml file. As it is used by the form action
+ to determine which page was submitted, mapping the data on the form to
+ current logic in the action. The name of the view should simply be
+ unique within the form, but it is most convenient to name the view after
+ the base of the filename. So in this case, we will name our view
+ "registration". In step 4 static string constants are used to unify
+ the naming and allow for easier maintenance </p>
+
+ <p>The action attribute should contain the URL you are using in
+ the sitemap. When implementing, it is easier to put all your pages for a
+ given form in a single folder but have the relative URL the same between
+ the different folders. This allows a single sitemap template to be used for
+ each of your different forms if desired. The URL is encoded directly to the
+ HTML action that is generated, so if this parameter is incorrect you will
see
+ a "Resource Not Found" error from Cocoon 2.</p>
+
+ <p>The caption element is the page heading. Following that, we have error
+ elements which are used if you have validation set in your sitemap.
+ When an error is found, the error text will be displayed once the user
clicks the next button on your form.</p>
<p>Next we see the input options for the user, such as xf:textbox,
which will display a textbox. Each of these options has a very
- important ref attribute whose value is mapped to the JavaBean. If we
- are validating this input, then it must have a violations element
- inside of it. The violations element serves as a container or
- placeholder for validation errors. It has a single optional attribute
- "class" which references the CSS class to use when displaying
- validation errors.</p>
+ important ref attribute whose value is mapped to the JavaBean.
+ If you are validating this input then it must have a violations
+ element inside it. The violations element 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>The format of the ref item is XPath, and the mapping is through
+ <link href="http://jakarta.apache.org/commons/jxpath/";>JXPath</link>.
+ JXPath is very flexible, it is beyond the scope of this document to
+ describe it in detail.</p>
- <p>Finally, the form needs a submit element This enables the user
+ <p>Finally, the form needs a submit element This enables the user to
continue on through the rest of the form.</p>
<source>
@@ -198,15 +203,12 @@
<s2 title="interest.xml">
<p>This XML page lets the user select areas of interest. Based on
- selected areas of interest, a user will later view a group of mailing
- lists on subsequent pages. The logic that determines what pages are
- shown next is found in a java file (which will be explained in later
- steps).</p>
+ their selections a user will later view a group of mailing
+ lists on subsequent pages. The logic that determines which pages are
+ shown next is found in the file, HowtoWizardAction.java which will
+ be explained later in step 4.</p>
- <fixme author="DS">Can you describe the example below this sentence?</fixme>
-
- <p>This page consists of tick boxes which are either true or false.
- </p>
+ <p>This page consists mainly of check boxes which are either true or false.</p>
<source>
<![CDATA[
@@ -216,6 +218,12 @@
]]>
</source>
+ <p>The page asks the user what their areas of interest are. There are 3
+ check boxes with the following captions of organic gardening, cooking
+ and Smallholding management. At the bottom of the page is a previous and
+ next button.
+ </p>
+
<p>Below is the page which you can copy into the folder
"howto".</p>
@@ -259,11 +267,16 @@
<s2 title="organicGardening.xml">
<p>If the user ticked the organic gardening box on the previous page,
- interest.xml, organicGardening.xml is the next page is shown. This
+ interest.xml, organicGardening.xml will be the next page to display. This
page shows a selection of mailing lists from which the user can chose.
It is very similar to the previous page which contained three tick
boxes. The user has the choice of moving forward through the form or
- back to the previous page to adjust the areas of interest.</p>
+ back to the previous page to adjust their areas of interest. This is
decided
+ in the perform method of HowtoWizardAction.java.</p>
+ <p>In a MVC pattern, it's clear to see that the form action is the
controller,
+ dealing only with the logic behind the presentation. The pages that we are
+ discussing here are the views, and the model is the bean that is describe
+ in step 3.</p>
<source>
<![CDATA[
@@ -306,7 +319,10 @@
<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>
+ ticked the organic gardening option on the interest.xml page. Again
+ the perform method checks the beans value and depending on these decides
+ whether or not to show this page. Conceptually the pages displayed are
+ sequenced by the controller and the logic therein.</p>
<source>
<![CDATA[
@@ -319,8 +335,8 @@
<xf:caption>Cooking Mailing Lists:</xf:caption>
- <xf:selectBoolean ref="/traditionalReciepes">
- <xf:caption>Traditional Reciepes</xf:caption>
+ <xf:selectBoolean ref="/traditionalRecipes">
+ <xf:caption>Traditional Recipes</xf:caption>
</xf:selectBoolean>
<xf:selectBoolean ref="/soups">
@@ -394,14 +410,16 @@
</s2>
<s2 title="confirm.xml">
- <p>This page shows the user all of the previously submitted data. This
- information is the result of querying a JavaBean where all of this
- data was stored. This is accomplished using the xf:output element
- which specifies what value to display with the ref attribute. A user
+ <p>This page shows the user all of the previously submitted data. A user
can change any of the information by clicking the previous button and
adjusting previous selections. Otherwise, the user can click the
finish button to go to the final page, end.xml.</p>
-
+ <p>While the pages were being filled out and submitted to the form
+ action, the fields were being individually validated against the schema
+ and the results applied to our bean using the JXPath expressions that were
+ entered in the ref attributes on each field of the page. By the time you
+ get to this point, the model bean will contain all the data that was
+ assigned to it, and you can start to use it.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
@@ -457,8 +475,8 @@
</xf:output>
<!-- from page4 -->
- <xf:output ref="/traditionalReciepes">
- <xf:caption>Traditional Reciepes</xf:caption>
+ <xf:output ref="/traditionalRecipes">
+ <xf:caption>Traditional Recipes</xf:caption>
</xf:output>
<xf:output ref="/soups">
@@ -497,13 +515,26 @@
</document>
]]>
</source>
+ <p>The final confirmation page is generated by querying the model
+ bean and displaying it. This is accomplished using the xf:output
+ element which specifies what value to display with the ref attribute,
+ again in JXPath syntax.</p>
+ <p>It's interesting to note that because this is a bean, business
+ logic could be embedded in the bean. So if this were a shopping cart
+ bean, we could have read-only business methods such as getTotalCost(),
+ which would be the sum of the individual item costs plus calculated
+ costs such as shipping and tax. You would have no problem displaying
+ that information on the form since the xf:output simply needs a JXPath
+ expression to query those methods. In such an example, the perform
+ method could be used to transactionally add the cart to the order
+ queue.</p>
</s2>
<s2 title="end.xml">
<p>end.xml is the final page. It informs the user of successful form
completion and provides the user with the option to return to the
start page.</p>
-
+
<source>
<![CDATA[
<?xml version="1.0" ?>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
