You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by cr...@apache.org on 2002/05/25 09:29:52 UTC
cvs commit: xml-forrest/src/documentation/library/xslt directory2revisions.xsl faq2document.xsl howto2document.xsl
crossley 02/05/25 00:29:52
Modified: src/documentation/conf sitemap.xmap
src/documentation/content/xdocs book.xml
src/documentation/library/xslt faq2document.xsl
howto2document.xsl
Added: src/documentation/content/xdocs/community placeholder
src/documentation/content/xdocs/community/howto book.xml
index.xml
src/documentation/content/xdocs/community/howto/bugzilla-patch
book.xml howto-bugzilla-patch.xml
src/documentation/content/xdocs/community/howto/bugzilla-patch/my-images
bugzilla-screen.gif
src/documentation/content/xdocs/community/howto/v10 book.xml
howto-v10.xml
src/documentation/content/xdocs/community/howto/xmlform
book.xml howto-xmlform.xml
revision-howto-xmlform-2002-05-20.xml
revision-howto-xmlform-2002-05-25.xml
revision-step1-2002-05-20.xml step1.xml step2.xml
step3.xml step4.xml step5.xml
src/documentation/library/xslt directory2revisions.xsl
Log:
Added new section for How-To samples.
Submitted by: Dianna Shannon <sh...@apache.org>
Revision Changes Path
1.2 +39 -3 xml-forrest/src/documentation/conf/sitemap.xmap
Index: sitemap.xmap
===================================================================
RCS file: /home/cvs/xml-forrest/src/documentation/conf/sitemap.xmap,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- sitemap.xmap 21 May 2002 14:45:17 -0000 1.1
+++ sitemap.xmap 25 May 2002 07:29:51 -0000 1.2
@@ -8,6 +8,7 @@
<map:generators default="file">
<map:generator name="file" src="org.apache.cocoon.generation.FileGenerator" label="content"/>
+ <map:generator name="directory" src="org.apache.cocoon.generation.DirectoryGenerator" label="content"/>
<!-- FIXME: Change this once better view handling is implemented -->
<map:generator name="file-nolabel" src="org.apache.cocoon.generation.FileGenerator"/>
</map:generators>
@@ -156,14 +157,44 @@
</map:call>
</map:match>
- <map:match pattern="body-**howto**.xml">
- <map:generate type="file-nolabel" src="content/xdocs/{1}howto{2}.xml"/>
- <map:transform src="library/xslt/howto2document.xsl" label="content"/>
+ <!-- index pages for contribution categories -->
+ <map:match pattern="body-community/*/index.xml">
+ <map:generate src="content/xdocs/community/{1}/index.xml"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
+ </map:match>
+
+ <!-- no special transformation, yet, for revision pages -->
+ <map:match pattern="body-community**revision-*.xml">
+ <map:generate src="content/xdocs/community{1}revision-{2}.xml"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
+ </map:match>
+
+ <!-- all contribution docs -->
+ <map:match pattern="body-community/*/*/**.xml">
+ <map:aggregate element="all" >
+ <map:part src="content/xdocs/community/{1}/{2}/{3}.xml"/>
+ <map:part src="cocoon:/revisions-community/{1}/{2}/{3}" />
+ </map:aggregate>
+ <map:transform src="library/xslt/{1}2document.xsl" label="content"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
</map:call>
</map:match>
+ <!-- revisions only implemented for community pages -->
+ <map:match pattern="revisions-community/*/*/**">
+ <map:generate type="directory" src="content/xdocs/community/{1}/{2}" />
+ <map:transform src="library/xslt/directory2revisions.xsl" label="content" >
+ <map:parameter name="use-request-parameters" value="true"/>
+ <map:parameter name="page" value="{3}"/>
+ </map:transform>
+ <map:serialize type="xml" />
+ </map:match>
+
<!-- Generate the "doclist" - list of all documentation
The first match generates each book.xml and adds a new attribute "uri".
The second match aggregates each book.xml into a doclist and
@@ -263,6 +294,11 @@
<map:parameter name="path" value="images/{2}.{3}"/>
<map:parameter name="mime-type" value="image/{3}"/>
</map:call>
+ </map:match>
+
+ <!-- DS: handles images local to a contributor directory -->
+ <map:match pattern="**my-images/**.*">
+ <map:read src="content/xdocs/{1}my-images/{2}.{3}" mime-type="image/{3}"/>
</map:match>
<map:match pattern="images/**.*">
1.9 +1 -1 xml-forrest/src/documentation/content/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/book.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- book.xml 22 May 2002 12:08:02 -0000 1.8
+++ book.xml 25 May 2002 07:29:51 -0000 1.9
@@ -30,7 +30,7 @@
<menu label="Document Samples">
<menu-item label="document-v11" href="document-v11.html"/>
- <menu-item label="howto-v10" href="howto-v10.html"/>
+ <menu-item label="How-Tos" href="community/howto/index.html"/>
</menu>
</book>
1.1 xml-forrest/src/documentation/content/xdocs/community/placeholder
Index: placeholder
===================================================================
CVS happy
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "book-cocoon-v10.dtd">
<book software="Forrest"
title="Forrest Community HOWTOs"
copyright="2002 The Apache Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="How-To">
<menu-item label="Single Page" href="v10/howto-v10.html"/>
<menu-item label="Multi-Page" href="xmlform/howto-xmlform.html"/>
<menu-item label="With Images" href="bugzilla-patch/howto-bugzilla-patch.html"/>
</menu>
</book>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>How-To Samples overview</title>
<authors>
<person name="Diana Shannon" email="shannon@apache.org"/>
</authors>
</header>
<body>
<section title="Status of development">
<p>
The structure and presentation of the How-To documents are under
development. The following documents and the associated DTDs,
stylesheets, and sitemap matches, are under constant change.
The content of these documents is just sample content and may not
even apply to Forrest. Over time, these samples will change so that
they are applicable to any project.
</p>
<p>
We are also conducting an experiment with feedback integration.
Go to the bottom of the Multi-page sample to see the revisions which
are automatically appended by the sitemap during 'build docs'.
Any snippet document with the filename
<code>revision-howto-xmlform-YYYY-MM-DD.xml</code> is appended to the
main page.
</p>
</section>
<section title="Sample How-Tos">
<ul>
<li><link href="v10/howto-v10.html">Single Page How-To</link></li>
<li><link href="xmlform/howto-xmlform.html">Multi-Page How-To with Revisions</link></li>
<li><link href="bugzilla-patch/howto-bugzilla-patch.html">How-To with Images</link></li>
</ul>
</section>
</body>
</document>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/bugzilla-patch/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "book-cocoon-v10.dtd">
<book software="Forrest"
title="Forrest"
copyright="2002 The Apache Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="How-Tos">
<menu-item label="Index" href="../index.html"/>
</menu>
</book>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/bugzilla-patch/howto-bugzilla-patch.xml
Index: howto-bugzilla-patch.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.0//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to Contribute a Patch via Bugzilla</title>
<authors>
<person name="David Crossley" email="crossley@apache.org"/>
</authors>
<abstract>Bugzilla is the Internet-based mechanism to facilitate contributions to any
Apache project. This includes changes to code and documents
(Patches), and also reports of bugs and suggestions for enhancement.
We will explain how to create your Bugzilla account, how to enter a patch
description, and, finally, how to attach the actual patch file.</abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<audience title="Intended Audience">
<p>
This document is meant for first-time users of Bugzilla.
The Bugzilla interface can be daunting, so this concise explanation will help you get started. Once you can submit a patch via Bugzilla, you can proceed to make more substantial
contributions. Of course, this how-to concentrates on Cocoon-specific contributions.
</p>
</audience>
<prerequisites title="Prerequisites">
<p>
Bugzilla contributors should:
</p>
<ul>
<li>Understand what a Patch is and how to make one.
<!-- See <link href="howto-patch.html">How to Prepare a Patch</link> -->
<!-- See <link href="">How to Prepare a Patch</link> (Doc under development). -->
Note that a new complete document is still just a "patch."
</li>
<li>Understand that Bugzilla is the Apache Bug Database. Bugzilla does not
distinguish between a Bug report, a Patch submission, and an Enhancement suggestion. They are all <em>"Bugs"</em> as far as Bugzilla is concerned.
</li>
</ul>
</prerequisites>
<steps title="Steps">
<p>
Here is how to proceed. Go to
<fork href="http://nagoya.apache.org/bugzilla/">Bugzilla</fork>
in another browser window.
</p>
<section title="1. Open a Bugzilla Account" >
<p>
Read the online instructions from the home page. To create your Bugzilla account, click on the "Open a new Bugzilla account" link. Do not worry, you will
not be sent spam email nor bombarded with advertisements by setting up this account.
</p>
<p>
Note that you can conduct queries in Bugzilla and review submissions without
having an account. However, to make a contribution you must have an account.
This ensures legitimacy. It also enables the system to send you
email automatically when your patch is applied by a Cocoon committer.
</p>
</section>
<section title="2. Enter a new bug report" >
<p><img src="my-images/bugzilla-screen.gif" alt="Bugzilla Screen" height="342" width="479" /></p>
<p>
Choose the "Enter a new bug report" link from the Bugzilla home page. First, you will be asked to select the relevant project ... choose Cocoon 2 of course. Next, you will be
asked to provide your account details. Following that, you will be presented
an input form for the various details ...
</p>
<section title="Specify Version" >
<p>
<!--FIXME: (DS) Default in my browser is 2.0, not Current CVS. Does it matter?-->
Specify the version of Cocoon that you prepared your patch against here. Choose
<code>Current CVS</code> if you have an up-to-date local working copy
of HEAD branch or a very recent nightly build. Otherwise, choose the relevant
release version.
</p>
</section>
<section title="Specify Component" >
<p>
Follow the "Component" link for description of the available
components. If you do not know which component is relevant, then just use <code>core</code>.
</p>
</section>
<section title="Specify Platform" >
<p>
This choice informs bug reporting. Perhaps it's relevant for your patch.
Otherwise, specify the <code>All</code> option.
</p>
</section>
<section title="Specify Operating System (OS)" >
<p>
This choice informs bug reporting. Perhaps it's relevant for your patch.
Otherwise, specify the <code>All</code> option.
</p>
</section>
<section title="Specify Severity" >
<p>
Severity defined here means the impact that would arise if your patch is not applied. For a documentation
patch, the severity would usually be the default <code>Normal</code>.
However, if your patch addressed some serious lack, or if it fixed a misguided configuration
statement, then the impact could be <code>major</code>.
</p>
<p>
<!--FIXME: (DS) Why include this if it isn't recommended for a patch? -->
(The <code>enhancement</code> option should not be used for a patch, as it is
intended for suggesting something that should be done. Use this option wisely. It
would be better to discuss it on the mailing list first, and then, when clear, describe it here.)
</p>
</section>
<section title="Specify Initial State" >
<p>
Use the <code>New</code> option.
</p>
</section>
<section title="Specify Assigned To" >
<p>
Leave this blank. Your patch will be automatically assigned to the
<code>cocoon-dev</code> mailing list. When a committer takes on your patch,
that committer will assign the bug to him or herself. This prevents duplication of effort by other committers.
</p>
<p>
The Cc field can be used if you need to copy bug reports and any
follow-up to some other person. Remember that your report will be sent automatically
to the <code>cocoon-dev</code> mailing list, so you don't need to Cc anyone there.
</p>
</section>
<section title="Specify URL" >
<p>
If the patch refers to a particular document, then provide the website URL.
If it refers to an issue with one of the local Cocoon Samples, then provide
the localhost URL.
</p>
</section>
<section title="Carefully choose the Summary" >
<p>
The summary will become the all-important title of the bug. Use it wisely. You want
to draw attention to your patch. Just as with posting email to the listervers,
choosing a poor title may cause your posting to be easily overlooked.
Use up all the characters available ... about 60 maximum.
</p>
<p>
Start the Summary with the <code>[PATCH]</code> tag. This will insure that it is
included in the Cocoon automated patch queue summary posted to the mailing lists.
The patch queue summary reminds people what patches are pending. If you omit this tag, then your patch may easily be overlooked.
</p>
</section>
<section title="Description" >
<p>
Provide a brief explanation of what your patch does. Supply any instructions
to help the committer apply your patch efficiently. Note any issues that may
remain. It may help to list each file that you are submitting and briefly
describe what it is. A committer will need to provide a descriptive log message
when committing your work. Providing a clear description here will help them.
</p>
<p>
Consider writing the Description and Summary text before entering
your patch report. You could save it in a local text file beforehand and
then copy-and-paste it when the time comes.
</p>
<p>
<!--FIXME (DS): Do we need this? It's a patch, not a bug. It may be confusing. -->
If this were a bug report, then it would need extensive description.
</p>
</section>
</section>
<section title="3. Send the patch report" >
<p>
Review your options, then press the <strong>Commit</strong> button. This will
add an entry to the bug database and email a report to the
<code>cocoon-dev</code> mailing list and a copy to you. Your submission will be
assigned a unique Bug Number which you can use to review its progress.
</p>
<p>
The next steps will show you how to attach your patch to the report that you
have just created ...
</p>
</section>
<section title="4. Create an attachment of the actual patch" >
<p>
You will be presented with a status screen saying that your bug report
was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
</p>
<p>
Now you have a choice ... proceed to review your bug report by selecting the
link "Back to Bug #XXXXX". If you forgot to mention something,
then you can add more comments. From that screen, follow the link
"Create a new attachment".
</p>
<p>
Otherwise follow the link from this status screen to "Attach a file to
this bug".
</p>
<section title="Specify the file to be uploaded" >
<p>
Provide the local pathname to your patchfile, e.g.
<code>/home/me/work/cocoon/patch/howto-bugzilla.tar.gz</code>
</p>
</section>
<section title="Describe the attachment" >
<p>
Provide a concise one line description, e.g.
<code>Gzipped TAR archive with new docs and diffs</code>
</p>
</section>
<section title="Specify the contentType of the attachment" >
<p>
If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then select
"<code>Binary file (application/octet-stream)</code>".
If it is just a single xml document, then select
"<code>Plain text (text/plain)</code>".
If the patch is just a single diff file, then select
"<code>Patch file (text/plain, diffs)</code>".
</p>
</section>
</section>
<section title="5. Submit the attachment" >
<p>
When you are ready, press the <strong>Submit</strong> button. As with Step 3,
you will be presented with a status screen saying that your attachment
was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
</p>
</section>
<section title="6. Be patient" >
<p>
Now your patch will wait inside Bugzilla until one of the Cocoon committers
assigns the patch to him or herself and starts to process it and apply it to the
master CVS repository. As the registered owner of the Bug, you will be sent an automatic email at each of these stages.
</p>
</section>
<section title="7. Add more description or attachments if necessary" >
<p>
Until the patch is applied by the committer and the Bug report is closed, you
can still add more to your bug report. However, only do this when
absolutely necessary because the patch should not be
changing while the committer is trying to commit it. If you just want to make further changes, then it would be better to wait until your patch is
applied. Then you can make a new patch. Remember that the committer has full
veto and may decide to make some slight modifications to your patch. So it
is far better to wait.
</p>
</section>
<section title="8. Adding subsequent patches to the same document or program" >
<p>
If you want to make more patches to the same file, then please open a new Bug
rather than re-open the old one. After all, once the original patch is
applied by the committer, its corresponding Bug report is closed.
</p>
</section>
</steps>
<extension title="Real World Extension">
<!--FIXME: (DS) The purpose of this is to provide examples of how they can use
the knowledge gained in this how-to -->
<p>Contributing patches, in the form of documentation or code, is a vital way to give back to the Cocoon community. For example, you might consider contributing a timely patch in the form of a new FAQ, how-to, or tutorial. Or, you may also consider submitting a patch which updates Cocoon's existing user and developer guides. </p>
</extension>
<tips title="Tips">
<section title="Setting user preferences">
<p>
You can configure certain preferences, though the Bugzilla defaults work just
fine.
</p>
</section>
<section title="Review the bugzilla documentation">
<p>
There are various explanations of terminology and procedures ... follow the
links should you need to know more.
</p>
</section>
<section title="Search Bugzilla">
<p>
Bugzilla has a very powerful search interface. Now that you have a login account,
Bugzilla can remember customized queries which you can run with a single click.
</p>
</section>
</tips>
<references title="References">
<ul>
<li>
Bugzilla is at
<link href="http://nagoya.apache.org/bugzilla/">http://nagoya.apache.org/bugzilla/</link>
</li>
<li>
Very helpful Bug Writing Guidelines are available directly from the
Bug entry interface.
</li>
</ul>
</references>
</howto>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/bugzilla-patch/my-images/bugzilla-screen.gif
<<Binary file>>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/v10/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "book-cocoon-v10.dtd">
<book software="Forrest"
title="Forrest"
copyright="2002 The Apache Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="How-Tos">
<menu-item label="Index" href="../index.html"/>
</menu>
</book>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/v10/howto-v10.xml
Index: howto-v10.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.0//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to Author a How-To</title>
<version>0.2</version>
<authors>
<person name="Diana Shannon" email="shannon@apache.org"/>
</authors>
<notice>This document is a sample to test the new howto-v11.dtd</notice>
<abstract>This How-To describes the steps necessary to write a How-To for Cocoon. The Cocoon documentation project needs your help. Writing a Cocoon How-To is a valuable way to give back to the community.</abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<audience title="Intended Audience">
<p>
Cocoon users who are ready to share their knowledge and experiences with the larger Cocoon community.
</p>
</audience>
<purpose title="Purpose">
<p>
These guidelines are based on successful how-to document structures used by other open source projects with diverse author groups. Following these tried and true guidelines will help to insure the effectiveness of your work.
</p>
</purpose>
<prerequisites title="Prerequisites">
<p>
How-To authors should have:
</p>
<ul>
<li>A unique How-To topic, related to using Cocoon, which fulfills a specific need. Check out existing How-Tos to find a niche for your work. Consider posting your idea for the How-To to cocoon-user list, to make sure another author's draft is not already in process.</li>
<li>A sufficient ability in English to write the FAQ. If you need a little extra help with language, consider partnering with another user with more advanced English writing skills.</li>
<li>Currently, the Cocoon documentation project is still working out the exact details for a How-To dtd and template. For now, just edit the most recent version of any existing How-To, filling in your own content as necessary. Make sure you use most recent version of document dtd to validate your How-To before submitting. You will find it in <code>src/documentation/xdocs/dtd</code> in your cocoon distribution.</li>
</ul>
<note>Within Forrest, the dtd is located in <code>src/resources/schema/dtd</code>.</note>
</prerequisites>
<steps title="Steps">
<p>
Here's how to proceed.</p>
<section title="Write the Overview">
<p>
An overview helps potential readers to determine quickly if a particular How-To matches their interests or needs. In a few sentences, summarize the main points of your How-To. Make sure to include any critical definitions which will help readers evaluate the utility of your How-To. Consider writing the overview last, after you have completed all other sections.
</p>
</section>
<section title="Describe your Intended Audience">
<p>
If your How-To is targetted at a specific audience, describe it here. For example, potential readers will have different levels of skill using Cocoon. They will also bring different areas of expertise and backgrounds to their How-To learning experience. When you clarify your target audience up front, you will save all other readers time and confusion.
</p>
</section>
<section title="State the Purpose">
<p>
State the purpose of your How-To. Explain how the reader will benefit by reading it. Give your reader an incentive or two to continue.
</p>
</section>
<section title="List any Prerequsites">
<p>
Inform your reader about any required knowledge, configuration, or resources they may need before stepping through your How-To. Assist them in this preparation by linking to other useful resources on the Cocoon site or the web. Helping your readers to prepare increases the likelihood that they will continue reading your How-To.
</p>
</section>
<section title="Describe the Steps of your How-To">
<p>
In a precise, step-by-step approach, walk your reader through the process. Make sure your reader can reproduce your intended result by following your exact steps. Make the learning process efficient by supplying sample code snippets or configuration details as necessary.
</p>
</section>
<section title="Extend the Learning">
<p>
Provide your reader with a few real-world examples of how the techniques or capabilities gained from your How-To could be applied. Reward the reader for successfully completing the How-To with a few ideas about how it will pay off.
</p>
</section>
<section title="Summarize the Entire Process">
<p>
In a few sentences, remind the reader what they have just learned. This helps to reinforce the main points of your How-To.
</p>
</section>
<section title="Additional Tips or FAQs">
<p>
In some cases, step-by-step instructions simply aren't enough. Use this section to pass on any other tips or frequently asked questions. Anticipating the needs of your readers will increase the overall success of your writing effort.
</p>
</section>
<section title="References">
<p>
Remember to acknowledge any third-party resources or individuals who contributed to the development of your How-To. Consider providing links for those motivated readers who want to learn more.
</p>
</section>
<section title="Get some feedback">
<p>
Ask a few other Cocoon users to proofread your How-To. Or, post a text version of it to the cocoon-user list, and ask for comments.
</p>
</section>
<section title="Submit via Bugzilla">
<p>
Create an attachment for your How-To document, and submit it via Bugzilla.
<!-- link to How-To Bugzilla here -->
</p>
</section>
</steps>
<extension title="Extension">
<p>
Cocoon solutions can be extended to cover many different problem domains. A nearly unlimited number of potential How-To topics, from simple to complex, are available right now, limited only by your imagination.
</p>
</extension>
<faqs title="Frequently Asked Questions">
<faq>
<question>
What is the difference between a How-To and a tutorial?
</question>
<answer>
<p>
The goal of a How-To is to help the reader to accomplish a specific task with clear and consise instructions. While tutorials may contain How-To-like instructions and content, they also include additional background and conceptual content to help teach their readers higher order concepts along the way. How-Tos are concerned about filling an immediate, short-term need. Tutorials often provide long-term knowledge which can be applied across a range of needs.
</p>
</answer>
</faq>
<faq>
<question>
What spelling convention should I follow?
</question>
<answer>
<p>
Use whatever spelling convention (American, British, etc.) that is most intuitive to you.
</p>
</answer>
</faq>
</faqs>
<tips title="Tips">
<section title="How-To dtd">
<p>
The document structure of Cocoon's How-To page is likely to change soon. Please note that this HOWTO page is likely to change as well.
</p>
</section>
</tips>
<references title="References">
<p>
This is not the first, nor will it be the last, How-To on writing How-Tos. For other ideas and opinions on the matter, check out the following sources.
</p>
<ul>
<li>
Joel D. Canfield's <link href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How to Write a How-To</link> on evolt.org.
</li>
<li>
The Linux Documentation Project's <link href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</link> index page provides many excellent How-To documents to inspire your efforts.
</li>
</ul>
</references>
</howto>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "book-cocoon-v10.dtd">
<book software="Forrest"
title="Forrest"
copyright="2002 The Apache Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="How-Tos">
<menu-item label="Index" href="../index.html"/>
</menu>
<menu label="XMLForm How-To">
<menu-item label="Intro" href="howto-xmlform.html"/>
<menu-item label="Step 1" href="step1.html"/>
<menu-item label="Step 2" href="step2.html"/>
<menu-item label="Step 3" href="step3.html"/>
<menu-item label="Step 4" href="step4.html"/>
<menu-item label="Step 5" href="step5.html"/>
</menu>
</book>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/howto-xmlform.xml
Index: howto-xmlform.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.0//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to build an XMLForm Wizard</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
<abstract>This How-To will guide your through the steps needed to create a validating form which saves the data collected as a JavaBean. It shows the components needed to do this within the Cocoon framework, Schematron validation and XMLForm wizard. XMLForm is a Cocoon form extension mechanism which was inspired by Struts and XForms. It was written by Ivelin Ivanov and is currently included in the scratchpad of Cocoon 2.0.2. Using the XMLForm wizard makes form validation a quick and easy task.</abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<audience title="Intended audience">
<p>This How-To is aimed at users who have developed an understanding of the basics of Cocoon and wish to incorporate dynamic and self validating forms into their sites. You will need to understand and be familiar with XML, XSL, HTML, XPath, JXPath, actions, action sets, cocoon-form format, Java, XForms. If you are unfamiliar with these technologies it is advised that you learn these concepts first.</p>
</audience>
<purpose title="Purpose">
<!-- FIXME: purpose means, how will it help the reader. What will he or she get out of it,
not the purpose of validation -->
<p>You will be able to automate two-way mapping between their HTML forms, XML and JavaBeans. The XML schema language is used to validate the form input. The forms can display different options depending on the users previous input. For example if a user ticks the checkbox to say they are interest in Cooking then they will later have the option to join Cookery mailing lists. If they did not tick the Cookery box they will not see the cookery mailing lists page.</p>
</purpose>
<prerequisites title="Prerequisites">
<p>Configuration requirements:</p>
<ul>
<li>A servlet engine such as Tomcat.</li>
<li>JDK 1.2 or later</li>
<li>Cocoon 2.0.2 CVS with scratchpad to be installed with the command:
build webapp -Dinclude.webapp.libs=true -Dinclude.scratchpad.libs=true webapp
</li>
</ul>
<p>Requisite skills:</p>
<ul>
<li>basic Cocoon concepts, including Cocoon actions</li>
<li>XML, XSL, HTML</li>
<li>Java, JavaBeans</li>
<li>XForms, XPath, JXPath</li>
</ul>
</prerequisites>
<steps title="Five Steps">
<p>Now you want to know how to create your own forms using the Wizard. Below are the steps you can follow:</p>
<ul>
<li><link href="step1.html">Step 1: XML forms</link></li>
<li><link href="step2.html">Step 2: Validation</link></li>
<li><link href="step3.html">Step 3: JavaBean</link></li>
<li><link href="step4.html">Step 4: HowtoWizardAction.java</link></li>
<li><link href="step5.html">Step 5: Sitemap</link></li>
</ul>
</steps>
<extension title="Real World Extension">
<p>Now you have created the Mailing list forms you should know which files are needed to create your own validating forms. The possibities are endless now that you can add dynamic forms to your Cocoon run site. </p>
<ul>
<li>A simple shopping cart could be created using an XML database such as <link href="http://xml.apache.org/xindice/">Xindices</link>.</li>
<li>Your site can now become more personalised and interactive for your visitors. They can create their own login details and set their own preferences with a few simple forms. Making your web site a home from home for them. </li>
<li>You can now run surveys and tests from your site</li>
<li>Add a voting system for new features to be added on your site</li>
<li>A suggestions/ feedback form</li>
<li>A simple form asking for more information to be sent regarding your products</li>
</ul>
</extension>
<tips title="Tips">
<p>If you have a problem running the example given you can try the following tips:</p>
<ul>
<li>Check the logs sometimes they have more information than displayed in your browser.</li>
<li>Check the 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>
</ul>
</tips>
<references title="Related Resources">
<p>Cocoon resources</p>
<ul>
<li>For all Cocoon basics see the <link href="http://xml.apache.org/cocoon">Cocoon Web site</link>.</li>
<li>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.</li>
</ul>
<p>XPath is simple to learn and the basis of JXPath.</p>
<ul>
<li>The W3C has a clear and simple <link href="http://www.w3schools.com/xpath/">tutorial</link>.</li>
</ul>
<p>JXPath is now at beta stage and is based on XPath.</p>
<ul>
<li>To learn more vist the home of <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link></li>
</ul>
</references>
<feedback title="Feedback">
<p>Needless to say this How-To was written with no intentional mistakes or errors but if you find any faults or can see any improvements, please email me, <link href="mailto:heidi@kutcha.org">Heidi</link> with them. I will do my upmost to keep this HowTo uptodate and error free.</p>
</feedback>
</howto>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/revision-howto-xmlform-2002-05-20.xml
Index: revision-howto-xmlform-2002-05-20.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Sample Revision</title>
<authors>
<person name="Motivated User" email="motivated@user.org"/>
</authors>
</header>
<body>
<section title="Some text here.">
<p>There is a problem with this approach</p>
<ul>
<li>Problem A.</li>
<li>Problem B.</li>
</ul>
</section>
</body>
</document>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/revision-howto-xmlform-2002-05-25.xml
Index: revision-howto-xmlform-2002-05-25.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Another Sample Revision</title>
<authors>
<person name="Motivated User" email="motivated@user.org"/>
</authors>
</header>
<body>
<p>
I see that the revision2document.xsl adds a footer to suggest that the
author should be contacted to make revisions. This is not the opensource way.
This would create a bottleneck at the author. Community feedback should be
encouraged to go to the relevant listserver, and patches submitted via Bugzilla.
</p>
<p>
The author of the howto also suggests that feedback should go via the author.
</p>
</body>
</document>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/revision-step1-2002-05-20.xml
Index: revision-step1-2002-05-20.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Sample Revision for Step 1</title>
<authors>
<person name="Motivated User" email="motivated@user.org"/>
</authors>
</header>
<body>
<section title="Other comments.">
<p>There is a problem with this approach</p>
<ul>
<li>Problem d.</li>
<li>Problem e.</li>
</ul>
</section>
</body>
</document>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/step1.xml
Index: step1.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to build an XMLForm Wizard, Step One</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
<abstract></abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<steps title="Step One">
<p>First we need to create our own forms in XML.</p>
<ul>
<li>Create a folder called "howto" in src\scratchpad\webapp\mount\xmlform.</li>
<li>Copy the following xml files below and save them in the folder you created.</li>
</ul>
<section title="start.xml">
<p>Below is the first page which you can copy and save as start.xml in the folder src\scratchpad\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>
</section>
<p>Next are the actual XML pages that make up the form. These are:</p>
<ul>
<li>register.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>
<section title="register.xml">
<p>Register.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 as 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 saying which class it belongs to.</p>
<p>Finally the form needs a submit tag tag. This lets the user navigate forward to the rest of the form.</p>
<source>
<![CDATA[
<?xml version="1.0" ?>
<!--
XMLForm instance document for the Cocoon Feedback Wizard.
Original Author: Torsten Curdt, tcurdt@dff.st, March 2002
Author: Ivelin Ivanov, ivelin@apache.org, April 2002
-->
<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>
</section>
<section 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" ?>
<!--
XMLForm instance document for the Cocoon Feedback Wizard.
Original Author: Torsten Curdt, tcurdt@dff.st, March 2002
Author: Ivelin Ivanov, ivelin@apache.org, April 2002
-->
<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>
</section>
<section 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" ?>
<!--
XMLForm instance document for the Cocoon Feedback Wizard.
Original Author: Torsten Curdt, tcurdt@dff.st, March 2002
Author: Ivelin Ivanov, ivelin@apache.org, April 2002
-->
<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>
</section>
<section 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" ?>
<!--
XMLForm instance document for the Cocoon Feedback Wizard.
Original Author: Torsten Curdt, tcurdt@dff.st, March 2002
Author: Ivelin Ivanov, ivelin@apache.org, April 2002
-->
<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>
</section>
<section 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" ?>
<!--
XMLForm instance document for the Cocoon Feedback Wizard.
Original Author: Torsten Curdt, tcurdt@dff.st, March 2002
Author: Ivelin Ivanov, ivelin@apache.org, April 2002
-->
<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>
</section>
<section 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" ?>
<!--
XMLForm instance document for the Cocoon Feedback Wizard.
Original Author: Torsten Curdt, tcurdt@dff.st, March 2002
Author: Ivelin Ivanov, ivelin@apache.org, April 2002
-->
<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>
</section>
<section 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 feedback 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>
</section>
<p><link href="step2.html">Step 2: Validation</link></p>
</steps>
</howto>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/step2.xml
Index: step2.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to build an XMLForm Wizard, Step Two</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
<abstract></abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<steps title="Step Two: 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 apache\xml-cocoon2\src\scratchpad\webapp\mount\xmlform\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" ?>
<!--
Validating Schematron schema for the xmlform example wizard
Schematron Schema language home page:
http://www.ascc.net/xml/schematron/
Author: Ivelin Ivanov, ivelin@apache.org, April 2002
-->
<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" diagnostics="dname dcount">
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" diagnostics="dname dcount">
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="step3.html">Step 3: Java Bean</link> </p>
</steps>
</howto>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/step3.xml
Index: step3.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to build an XMLForm Wizard, Step Three</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
<abstract></abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<steps title="Step Three: JavaBean">
<section 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 JXPath.</p>
<p>Copy the file below and save it as HowToBean.java in the folder \apache\xml-cocoon2\src\scratchpad\src\org\apache\cocoon\samples\xmlform</p>
<source>
<![CDATA[
package org.apache.cocoon.samples.xmlform;
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 domain object used as a Form model.
* Notice that it has mixed content:
* JavaBean properties and
* DOM Nodes, which are handled correctly by the
* framework when referenced via XPath.
*
*/
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="step4.html">Step 4:HowtoWizardAction.java</link></p>
</section>
</steps>
</howto>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/step4.xml
Index: step4.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to build an XMLForm Wizard, Step Four</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
<abstract></abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<steps title="Step Four: HowtoWizardAction.java">
<p>This is based on the WizardAction.java. The prepare, perform and reset methods need to be altered. Your XML pages also need to be defined.</p>
<section 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>
</section>
<section 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 passes 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[
/**
* 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;
}
]]>
</source>
</section>
<section title="Perform Method">
<p>The perform method controls the logic of the forms pages to be displayed.</p>
<p>First the model is saved to the JavaBean</p>
<source>
<![CDATA[
/**
* 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();
// 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 );
}
]]>
</source>
</section>
<section title="Reset Method">
<p>The reset method is used to tidy up any checkboxes and can be used to reset other fields in the form.</p>
<source>
<![CDATA[
/**
*
* 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 );
}
}
]]>
</source>
</section>
<p>The whole file HowtoWizardAction.java is below for you to copy to the folder C:\projects\apache\xml-cocoon2\src\scratchpad\src\org\apache\cocoon\samples:</p>
<source>
<![CDATA[
/*
* $Header: /home/cvspublic/xml-cocoon2/src/scratchpad/src/org/apache/cocoon/samples/xmlform/HowtoWizardAction.java,
v 1.2 2002/05/09 07:26:07 ivelin Exp $
* $Revision: 1.1 $
* $Date: 2002/05/25 07:29:52 $
*
* ====================================================================
* The Apache Software License, Version 1.1
*
*
*
* Copyright (c) 1999-2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 2001, Plotnix, Inc,
* <http://www.plotnix.com/>.
* For more information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.cocoon.samples.xmlform;
// 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 Form
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 Ivelin Ivanov <iv...@apache.org>
*/
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>
<p>Finally <link href="step5.html">Step 5: the Sitemap</link></p>
</steps>
</howto>
1.1 xml-forrest/src/documentation/content/xdocs/community/howto/xmlform/step5.xml
Index: step5.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "howto-v10.dtd">
<howto>
<header>
<title>How to build an XMLForm Wizard, Step Five</title>
<authors>
<person name="Heidi Brannan" email="heidi@wkwyw.net"/>
</authors>
<abstract></abstract>
<last-modified-content-date date="2002-05-19"/>
</header>
<steps title="Step Five: 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.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 AbstractXMLFormAction -->
<map:parameter name="xmlform-validator-schema-ns" value="http://www.ascc.net/xml/schematron"/>
<map:parameter name="xmlform-validator-schema" value="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.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="stylesheets/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 \apache\xml-cocoon2\src\scratchpad\webapp\mount\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.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="stylesheets/xmlform2html.xsl"/>
<map:serialize type="html"/>
</map:act>
</map:match>
<map:match pattern="">
<map:redirect-to uri="wizard.html"/>
</map:match>
<!-- A non-trivial example - Feedback HowTo Wizard -->
<map:match pattern="howto-wizard.html">
<map:act type="HowtoWizardAction">
<!-- 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/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.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="stylesheets/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 -Dinclude.scratchpad.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/mount/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.html">start</link></p>
</steps>
</howto>
1.3 +1 -1 xml-forrest/src/documentation/library/xslt/faq2document.xsl
Index: faq2document.xsl
===================================================================
RCS file: /home/cvs/xml-forrest/src/documentation/library/xslt/faq2document.xsl,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- faq2document.xsl 12 May 2002 18:40:44 -0000 1.2
+++ faq2document.xsl 25 May 2002 07:29:52 -0000 1.3
@@ -47,4 +47,4 @@
<xsl:apply-templates/>
</xsl:template>
-</xsl:stylesheet>
\ No newline at end of file
+</xsl:stylesheet>
1.2 +50 -6 xml-forrest/src/documentation/library/xslt/howto2document.xsl
Index: howto2document.xsl
===================================================================
RCS file: /home/cvs/xml-forrest/src/documentation/library/xslt/howto2document.xsl,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- howto2document.xsl 19 May 2002 21:06:44 -0000 1.1
+++ howto2document.xsl 25 May 2002 07:29:52 -0000 1.2
@@ -6,14 +6,31 @@
<xsl:import href="copyover.xsl"/>
- <xsl:template match="howto">
+ <xsl:template match="all">
<document>
- <xsl:copy-of select="header"/>
- <body><xsl:apply-templates select="*[not(name()='header')]"/></body>
+ <xsl:copy-of select="howto/header"/>
+ <body>
+ <xsl:apply-templates select="howto"/>
+ <xsl:apply-templates select="revisions"/>
+ </body>
+
</document>
</xsl:template>
- <xsl:template match="overview | purpose | prerequisites | audience | steps | extension | tips | references">
+ <xsl:template match="howto">
+ <xsl:if test="normalize-space(header/abstract)!=''">
+ <xsl:apply-templates select="header/abstract"/>
+ </xsl:if>
+ <xsl:apply-templates select="*[not(name()='header')]"/>
+ </xsl:template>
+
+ <xsl:template match="howto/header/abstract">
+ <section title="Overview" >
+ <xsl:apply-templates/>
+ </section>
+ </xsl:template>
+
+ <xsl:template match="purpose | prerequisites | audience | steps | extension | faqs | tips | references | feedback ">
<section>
<xsl:choose>
<xsl:when test="normalize-space(@title)!=''">
@@ -23,8 +40,35 @@
<xsl:attribute name="title"><xsl:value-of select="name()"/></xsl:attribute>
</xsl:otherwise>
</xsl:choose>
- <xsl:apply-templates/>
+ <xsl:apply-templates/>
</section>
</xsl:template>
-</xsl:stylesheet>
\ No newline at end of file
+ <xsl:template match="faq">
+ <section title="{question}" >
+ <xsl:apply-templates select="answer" />
+ </section>
+ </xsl:template>
+
+ <xsl:template match="answer">
+ <xsl:copy-of select="."/>
+ </xsl:template>
+
+ <xsl:template match="question">
+ </xsl:template>
+
+ <xsl:template match="revisions">
+ <section title="Revisions" >
+ <p>Find a problem with this document? Consider contacting the author or submitting your own revision. For instructions, read the How To Submit a Revision.</p>
+ <ul>
+ <xsl:apply-templates select="revision"/>
+ </ul>
+ </section>
+ </xsl:template>
+
+ <xsl:template match="revision">
+ <xsl:variable name="href"><xsl:value-of select="concat(substring-before(@name,'.xml'),'.html')" /></xsl:variable>
+ <li>Revision, <a href="{ $href}"><xsl:value-of select="@date"/></a></li>
+ </xsl:template>
+
+</xsl:stylesheet>
1.1 xml-forrest/src/documentation/library/xslt/directory2revisions.xsl
Index: directory2revisions.xsl
===================================================================
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:dir="http://apache.org/cocoon/directory/2.0">
<xsl:param name="page" />
<xsl:variable name="revisionPage"><xsl:value-of select="concat('revision-',$page)" /></xsl:variable>
<xsl:template match="dir:directory">
<revisions>
<xsl:apply-templates select="dir:file" />
</revisions>
</xsl:template>
<xsl:template match="dir:file">
<xsl:if test="starts-with(@name,$revisionPage)" >
<revision>
<xsl:attribute name="name"><xsl:value-of select="@name"/></xsl:attribute>
<xsl:attribute name="date"><xsl:value-of select="@date"/></xsl:attribute>
</revision>
</xsl:if>
</xsl:template>
</xsl:stylesheet>