cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From shan...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/howto/xmlform-wizard howto-xmlform-wizard.xml
Date Wed, 05 Jun 2002 15:01:11 GMT
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&#39;s How-To</title>
  +
       <authors>
  -      <person name="Heidi Brannan" email="heidi@wkwyw.net"/>
  +      <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 title="Notice">
  +      <p>This How-To is based on components included in the Cocoon 2.1
  +      distribution. If you don&#39;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 &#34;alpha&#34;. 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
  +      &#34;alpha&#34; 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 &#34;beta&#34; status is reached, backward
  +      incompatible changes will be made only when absolutely necessary to
  +      reach &#34;final&#34; 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&#39;t change. On the other hand,
  +      the Cocoon project is a pioneer in many fields. Most of the technologies
  +      it uses are at a &#34;working draft&#34; phase only. Thus, reliability
  +      cannot be guaranteed before the software achieves its &#34;final&#34;
  +      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&#39;s easy. As for quick, well, it depends on your
  +      reader, doesn&#39;t it? XMLForm introduces a *lot* of stuff that your
  +      readers may not have dealt with yet. Once you&#39;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&#39;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&#39;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: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> 
  -    
  +      <fixme author="DS">Do you really want people emailing you directly for
  +      help? It doesn&#39;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: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 &#34;XMLForm Help&#34; 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:ivelin@apache.org">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&#39;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:heidi@kutcha.org">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:heidi@kutcha.org">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:     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


Mime
View raw message