This How-To is based on components included in the Cocoon 2.1 distribution. If you don't have this version, you can obtain it from the Apache Cocoon web site.

Some user accessible points in the Cocoon 2.1 distribution should be considered "alpha". This means that the developer team is not investing _any_ effort to provide backward compatibility between alpha releases for these parts. This software will continue to be released as "alpha" until its code, schemas, and APIs are considered stable.

Until then, there will be no warranty that newer versions will maintain backward compatibility for such parts, even in the most simple cases. Of course Cocoon will be compatible to latest release, 2.0.x release. However, once "beta" status is reached, backward incompatible changes will be made only when absolutely necessary to reach "final" status.

The Cocoon development team understands the importance of reliable software as well protecting user investments through the creation of a solid development platform that doesn't change. On the other hand, the Cocoon project is a pioneer in many fields. Most of the technologies it uses are at a "working draft" phase only. Thus, reliability cannot be guaranteed before the software achieves its "final" status.

Until then, no effort will be provided to guarantee backward compatibility for any parts considered alpha.

You have been warned.

XMLForm is a Cocoon form extension mechanism which was inspired by Struts and XForms. 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.

Form creation and validation can be a quick and easy addition to your site, once you learn how to apply and use the XMLForm wizard. This How-To will guide you through the steps needed to create a validating form which saves the data it collects as a JavaBean. It will also describe Schematron validation and the XMLForm wizard components needed to accomplish this within the Cocoon framework.

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 the following:

• A servlet engine such as Tomcat.
• JDK 1.2 or later
• commons-jxpath.jar, included in the current Cocoon 2.1 lib/optional directory

Cocoon 2.1 CVS to be installed with the command:

	build -Dinclude.webapp.libs=true webapp

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.

Follow these steps to create your own forms using the XMLForm Wizard:

• Step 1: XMLForm markup language
• Step 2: Validation
• Step 3: JavaBean
• Step 4: HowtoWizardAction.java
• Step 5: Sitemap

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:

• create a simple shopping cart using an XML database such as Xindice;
• design your site to become more personalised and interactive for your visitors;
• run surveys and tests from your site;
• add a voting system for new features to be added on your site;
• add a suggestions/feedback form, for example, a simple form soliciting more user feedback about your products;
• develop even more exciting things, such as Web Services (think REST); and
• include Remote Portal Forms, by taking RSS to the next generation of dynamic federated content.

See XMLForm in action in version 2.1 of Cocoon from your local webapp distribution in 2.1 via http://localhost:8080/cocoon/samples/xmlform/.

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.

If you have a problem running the How-To example, try the following.

• Check the logs. Sometimes they have contain information than what is displayed in your browser.
• Check the mail archives at MARC: Mailing list ARChives at AIMS. Chances are somebody else has already experienced a similar problem!
• Try posting a description of your problem to the Cocoon users email list. Remember to include the whole error message. For a prompt reply, make sure you supply all relevant information.
• If you think you found a bug in the implementation, contact the XMLForm author, Ivelin Ivanov , or submit a patch via Bugzilla.

For all Cocoon basics see the Cocoon documentation. The XMLForm Handling and the actions page are especially helpful. Actions are Avalon Components, so you may want to read the Avalon white paper for more information.

XPath and the basics of JXPath are simple to learn. The W3C has a helpful tutorial.

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, Heidi-Marie Brannan. I will do my upmost to keep this How-To up to date and error free.