shannon 2002/06/05 08:01:10
Modified: src/documentation/xdocs/howto/xmlform-wizard
howto-xmlform-wizard.xml
Log:
Added notice at top about components
based on HEAD. I copied WARNING from
root HEAD cvs. Perhaps it's too much and
will scare users. I corrected a number
of grammatical issues, simplifying
sentences based on global English
concerns. Added a number of fixme
comments for the author to consider.
Revision Changes Path
1.2 +196 -84
xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard.xml
Index: howto-xmlform-wizard.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard/howto-xmlform-wizard.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- howto-xmlform-wizard.xml 1 Jun 2002 13:18:09 -0000 1.1
+++ howto-xmlform-wizard.xml 5 Jun 2002 15:01:10 -0000 1.2
@@ -2,113 +2,225 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
-
<header>
- <title>XMLForm's HowTo</title>
+ <title>XMLForm Wizard's How-To</title>
+
<authors>
- <person name="Heidi Brannan" email="[EMAIL PROTECTED]"/>
+ <person name="Heidi Brannan"
+ email="[EMAIL PROTECTED]" />
</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 title="Notice">
+ <p>This How-To is based on components included in the Cocoon 2.1
+ distribution. If you don't have this version, you can obtain it from
+ the Cocoon web site. See the <link
href="http://xml.apache.org/cocoon/";>xml.apache.org</link>
+ web site for details.</p>
+
+ <p> Some user accessible points in the Cocoon 2.1 distribution should be
+ considered "alpha". This means that the developer team is not
+ investing _any_ effort to provide backward compatibility between alpha
+ releases for these parts. This software will continue to be released as
+ "alpha" until its code, schemas, and APIs are considered stable.
+ </p>
+
+ <p>Until then, there will be no warranty that newer versions will
+ maintain backward compatibility for such parts, even in the most simple
+ cases. Of course Cocoon will be compatible to latest release, 2.0.x
+ release. However, once "beta" status is reached, backward
+ incompatible changes will be made only when absolutely necessary to
+ reach "final" status. </p>
+
+ <p>The Cocoon development team understands the importance of reliable
+ software as well protecting user investments through the creation of a
+ solid development platform that doesn't change. On the other hand,
+ the Cocoon project is a pioneer in many fields. Most of the technologies
+ it uses are at a "working draft" phase only. Thus, reliability
+ cannot be guaranteed before the software achieves its "final"
+ status. </p>
+
+ <p>Until then, no effort will be provided to guarantee backward
+ compatibility for any parts considered alpha. </p>
+
+ <p>You have been warned.</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>
+ <fixme author="DS">Be careful calling *anything* quick and easy. Let the
+ reader decide if it's easy. As for quick, well, it depends on your
+ reader, doesn't it? XMLForm introduces a *lot* of stuff that your
+ readers may not have dealt with yet. Once you've learned how to do
+ it, it may then become quick and easy, but be careful how you build
+ expecations during the learning process. I adjusted the language a bit
+ because of this. Do you agree?</fixme>
+
+ <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>. Form creation and
+ validation can be a quick and easy addition to your site, once you learn
+ how to apply use the XMLForm wizard. This How-To will guide your through
+ the steps needed to create a validating form which saves the data it
+ collects as a JavaBean. It will also describe <link
+
href="http://www.ascc.net/xml/resource/schematron/schematron.html";>Schematron</link>
+ validation and the XMLForm wizard components needed to accomplish this
+ within the Cocoon framework.</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>
+ <fixme author="DS">The purpose of this section, Purpose, is to describe
+ how the reader will benefit by reading your How-To. It's not meant
+ to describe the purpose of XML Form wizards. You may need to pull
+ content out of overview, above, and add some of purpose's existing
+ content to the overview.</fixme>
+
+ <p>You will learn how 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>
+ <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.</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 title="Requirements">
+ <fixme author="DS">Consider adding related jar info, even though they
+ are included in the HEAD branch. I find it useful to begin educating
+ users about what jars they may need when they explore new approahces.</fixme>
+
+ <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>
+
+ <p>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
+ such concepts first.</p>
</s1>
-
+
+ <s1 title="Steps">
+ <p>Follow these steps to create your own forms using the XMLForm Wizard:</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>
-
+ <p>Now that you have created the Mailing list forms in this How-To, you
+ can proceed to create your own validating forms. The possibilities for
+ adding dynamic form capabilities to your Cocoon-based web site are
+ endless. For example, you could:</p>
+
+ <ul>
+ <li>create a simple shopping cart using an XML database such as <link
+ href="http://xml.apache.org/xindice/";>Xindice</link>;</li>
+
+ <li>design your site to become more personalised and interactive for
+ your visitors;</li>
+
+ <li>run surveys and tests from your site;</li>
+
+ <li>add a voting system for new features to be added on your site;</li>
+
+ <li>add a suggestions/feedback form, for example, a simple form
+ soliciting more user feedback about your products;</li>
+
+ <li>develop even more exciting things, such as <strong>Web Services</strong>
+ (think <link
+
href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm";>REST</link>);
+ and</li>
+
+ <li>include Remote Portal Forms, by taking <link
+
href="http://my.netscape.com/publish/formats/rss-spec-0.91.html#example1";>RSS</link>
+ to the next generation of dynamic federated content.</li>
+ </ul>
+
+ <p>Consider examining the XMLForm Feedback Wizard demo in your Cocoon
+ distribution, found at src/webapp/samples/xmlform. It includes a variety
+ of XMLForm widgets. Additionally, it illustrates access to other Form
+ models, not only JavaBeans (as demonstrated in this How-To) 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:[EMAIL PROTECTED]";>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:[EMAIL PROTECTED]";>Ivelin Ivanov</link> </li>
- </ul>
- </s1>
-
+ <fixme author="DS">Do you really want people emailing you directly for
+ help? It doesn't sound very sustainable over the long run.</fixme>
+
+ <p>If you have a problem running the How-To example, try the following.</p>
+
+ <ul>
+ <li>Check the logs. Sometimes they have contain information than what
+ is displayed in your browser.</li>
+
+ <li>Check the mail archives at <link
+ href="http://marc.theaimsgroup.com";>MARC: Mailing list ARChives at
+ AIMS</link>. Chances are somebody else has already experienced a
+ similar problem!</li>
+
+ <li>Email <link href="mailto:[EMAIL PROTECTED]";>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 posting a description of your problem to the <link
+ href="http://xml.apache.org/cocoon/mail-lists.html";>Cocoon users email
+ list</link>. Remember to include the whole error message. For a prompt
+ reply, make sure you supply all relevant information.</li>
+
+ <li>If you think you found a bug in the implementation, contact the
+ XMLForm author, <link href="mailto:[EMAIL PROTECTED]";>Ivelin Ivanov,
+ </link> or submit a patch via Bugzilla.</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>
+ <fixme author="DS">Can you add a link to the Avalon White Paper?</fixme>
+
+ <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 white paper 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>
+ <p>XPath and the basics of JXPath are simple to learn. The W3C has a
+ helpful <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:[EMAIL PROTECTED]";>Heidi</link> with them. I will do my upmost to keep
this HowTo uptodate and error free.</p>
+ <p>Needless to say this How-To was written with no intentional mistakes
+ or errors. However, if you find any faults or can suggest any
+ improvements, please email me, <link
href="mailto:[EMAIL PROTECTED]";>Heidi</link>.
+ I will do my upmost to keep this How-To up to date and error free.</p>
</s1>
</body>
-
</document>
-
-
-
-
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
