Return-Path: Delivered-To: apmail-cocoon-cvs-archive@www.apache.org Received: (qmail 2157 invoked from network); 27 Sep 2007 20:00:27 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 27 Sep 2007 20:00:27 -0000 Received: (qmail 61951 invoked by uid 500); 27 Sep 2007 20:00:06 -0000 Delivered-To: apmail-cocoon-cvs-archive@cocoon.apache.org Received: (qmail 61888 invoked by uid 500); 27 Sep 2007 20:00:06 -0000 Mailing-List: contact cvs-help@cocoon.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@cocoon.apache.org list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list cvs@cocoon.apache.org Received: (qmail 61872 invoked by uid 99); 27 Sep 2007 20:00:06 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 27 Sep 2007 13:00:06 -0700 X-ASF-Spam-Status: No, hits=-100.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 27 Sep 2007 20:02:14 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 772C11A9860; Thu, 27 Sep 2007 12:58:54 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r580139 [15/28] - in /cocoon/site/site/2.2: ./ blocks/ blocks/ajax/ blocks/ajax/1.0/ blocks/ajax/1.0/apidocs/ blocks/ajax/1.0/css/ blocks/ajax/1.0/images/ blocks/ajax/1.0/images/logos/ blocks/css/ blocks/forms/ blocks/forms/1.0/ blocks/form... Date: Thu, 27 Sep 2007 19:57:38 -0000 To: cvs@cocoon.apache.org From: reinhard@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20070927195854.772C11A9860@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: cocoon/site/site/2.2/blocks/forms/1.0/752_1_1.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/blocks/forms/1.0/752_1_1.html?rev=580139&view=auto ============================================================================== --- cocoon/site/site/2.2/blocks/forms/1.0/752_1_1.html (added) +++ cocoon/site/site/2.2/blocks/forms/1.0/752_1_1.html Thu Sep 27 12:56:05 2007 @@ -0,0 +1,469 @@ + + + + + + + + + + + + + + Cocoon Forms + + + + + + + +
+

Apache » Cocoon »

+
+ + + +
+ + +

Improving the simple sample

This section describes some possible improvements to the simple sample.

Automatic layouting

A very common way of layouting a form is in a table with two columns: the +left column contains the labels, the right column the input fields. The CForms +XSL stylesheets support some tags to do this automatically for you. Here is the +template for the simple sample, using automatic two-column styling:

<html xmlns:ft="http://apache.org/cocoon/forms/1.0#template"
+  xmlns:fi="http://apache.org/cocoon/forms/1.0#instance"
+  xmlns:jx="http://apache.org/cocoon/templates/jx/1.0">
+
+  <jx:import uri="resource://org/apache/cocoon/forms/generation/jx-macros.xml"/>
+
+  <head>
+    <title>Registration form</title>
+  </head>
+  <body>
+    <h1>Registration</h1>
+    <ft:form-template action="#{$continuation/id}.continue" method="POST">
+      <fi:group>
+        <fi:styling layout="columns"/>
+        <fi:items>
+          <ft:widget id="name"/>
+          <ft:widget id="email"/>
+          <ft:widget id="age"/>
+          <ft:widget id="password">
+            <fi:styling type="password"/>
+          </ft:widget>
+          <ft:widget id="confirmPassword">
+            <fi:styling type="password"/>
+          </ft:widget>
+          <ft:widget id="spam"/>
+        </fi:items>
+      </fi:group>
+      <input type="submit"/>
+    </ft:form-template>
+  </body>
+</html>
+

As you see, it is no longer needed to use the ft:widget-label tags. +Furthermore, the stylesheets will properly use the HTML label tag to +associate the label with the input field.

Other supported stylings include "tabs" (for tabbed panes), "choice" (similar +to tabs but with a dropdown to switch), "fieldset" (groups the fields in a frame +with a label). See the CForms samples for examples of how to use them.

Using i18n

As mentioned before, you can internationalize the form labels by embedding +i18n tags that will be handled by the i18n transformer. Let's look at +the concrete steps to achieve this.

First, the form definition. Here we need to add the declaration of the i18n +namespace, and for now we'll just apply i18n for the name field. This is done as +follows:

<fd:form
+  xmlns:fd="http://apache.org/cocoon/forms/1.0#definition"
+  xmlns:i18n="http://apache.org/cocoon/i18n/2.1">
+
+  <fd:widgets>
+    <fd:field id="name" required="true">
+      <fd:label><i18n:text key="name"/>:</fd:label>
+      <fd:datatype base="string"/>
+      <fd:validation>
+        <fd:length min="2"/>
+      </fd:validation>
+    </fd:field>
+[...]
+

Then, the resource bundle. Resource bundles for the i18n transformer are in +an XML format. Create a subdirectory called i18n and put a file called +messages.xml in it, containing the following:

<?xml version="1.0"?>
+<catalogue>
+  <message key="name">Name</message>
+</catalogue>
+

The only thing left now is to change the configuration of the i18n +transformer to make it aware of this resource bundle. Change the configuration +of the i18n transformer in the sitemap as follows:

      <map:transformer name="i18n"
+        src="org.apache.cocoon.transformation.I18nTransformer">
+        <catalogues default="mymessages">
+          <catalogue id="mymessages" name="messages" location="i18n"/>
+          <catalogue id="forms" name="messages"
+            location="resource://org/apache/cocoon/forms/system/i18n"/>
+        </catalogues>
+        <cache-at-startup>true</cache-at-startup>
+      </map:transformer>
+

The location attribute of the catalogue is relative to the location of the +sitemap, so the value i18n refers to the subdirectory you created in the +previous step. As we did not mention the catalogue explicitely on the +i18n:text element, we need to make it the default (the forms catalogue +does not need to be the default). For more information on this see the i18n +transformer documentation.

If you now try the sample again, everything should work as before; you should +still see the "Name" label.

But now we still need to tell the i18n transformer what locale to use. To +make our explanation more complete, we should not only tell the i18n transformer +what locale to use, but the same locale should typically also be used when +parsing form data and formatting form data for output (this does not matter for +string fields, but important for dates and numbers). This can be done as +follows. In the flowscript (registration.js), specify a locale property on the +form. Let us take french as an example:

[...]
+    var form = new Form("registration.xml");
+    form.locale = new java.util.Locale("fr");
+[...]
+

The locale you specify here will also be automatically added to the viewData +for the pipeline when calling showForm.

In the sitemap, we need to pass the locale to the template generator and the +i18n transformer:

     <map:match pattern="registration-display-pipeline">
+       <map:generate type="jx" src="registration_template.xml">
+         <map:parameter name="locale" value="{flow-attr:locale}"/>
+       </map:generate>
+       <map:transform type="i18n">
+         <map:parameter name="locale" value="{flow-attr:locale}"/>
+       </map:transform>
+       <map:transform src="forms-samples-styling.xsl"/>
+       <map:serialize/>
+     </map:match>
+

The "flow-attr" input module is used to retrieve values from the +viewData.

Finally, create a french resource bundle: i18n/messages_fr.xml:

<?xml version="1.0"?>
+<catalogue>
+  <message key="name">Nom</message>
+</catalogue>
+

If you now try the registration sample again, "Name" should be replaced by +"Nom".

Errors and Improvements? If you see any errors or potential improvements in this document please help + us: View, Edit or comment on the latest development version (registration required). +
+
+ + + + + + Added: cocoon/site/site/2.2/blocks/forms/1.0/753_1_1.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/blocks/forms/1.0/753_1_1.html?rev=580139&view=auto ============================================================================== --- cocoon/site/site/2.2/blocks/forms/1.0/753_1_1.html (added) +++ cocoon/site/site/2.2/blocks/forms/1.0/753_1_1.html Thu Sep 27 12:56:05 2007 @@ -0,0 +1,459 @@ + + + + + + + + + + + + + + Cocoon Forms + + + + + + + +
+

Apache » Cocoon »

+
+ + + +
+ + +

Selection lists

This section explains selection lists and their available implementations. +Selection lists can be used with the field or +multivaluefield widgets. Selection lists are closely +related to the datatype of the widget, since the items in the selection list +should of course match the datatype of the widget.

Default selection list implementation

The selection list can be defined inline or read from an external source. +Example of inline declaration:

<fd:datatype base="long"/>
+<fd:selection-list>
+  <fd:item value="1"/>
+  <fd:item value="2"/>
+  <fd:item value="3">
+    <fd:label>three</fd:label>
+  </fd:item>
+  <fd:item value="4"/>
+  <fd:item value="5"/>
+</fd:selection-list>

Each item in the selection-list can have a value (specified in the value +attribute) and optionally a label (specified in the fd:label element). If no +label is specified, the value is used as label. The fd:label element can contain +mixed content.

To set a default selection, just set the value of the widget containing the +selection list.

Example of getting a selection list from an external source:

<fd:datatype base="string"/>
+<fd:selection-list src="cocoon:/mychoices.xml"/>

All Cocoon-supported protocols can be used. The format of the XML produced by +the source should be the same as in case of inline specification of the +selection list, thus the root element should be a fd:selection-list element.

By default, the selection list will be retrieved form the source once, and +then become part of the form definition, just like when you would have defined +it inline. This has the consequence that if the XML produced by the source +changes, you won't see the selection list changed. If you'd like CForms to +retrieve the content of the selection list each time it needs it, add an +attribute called "dynamic" with value "true", for example:

<fd:datatype base="string"/>
+<fd:selection-list src="cocoon:/mychoices.xml" dynamic="true"/>

If the datatype is different from string, CForms will need to convert the +string values that appear in the selection list to their object equivalent. This +conversion is normally done using the same convertor as the datatype in which +the selection list appears, but you can also specify a different one. Here's an +example for a date selection list:

<fd:datatype base="date"/>
+<fd:selection-list>
+  <fd:convertor type="formatting">
+    <fd:patterns>
+      <fd:pattern>yyyyMMdd</fd:pattern>
+    </fd:patterns>
+  </fd:convertor>
+  <fd:item value="13020711"/>
+  <fd:item value="19120623"/>
+  <fd:item value="19690721"/>
+  <fd:item value="19700506"/>
+  <fd:item value="19781014"/>
+  <fd:item value="20010911"/>
+</fd:selection-list>

If there is a fd:convertor element, it should always be the first child +element of the fd:selection-list element. This works of course also for +selection lists retrieved from external sources.

Selection list implementations are pluggable. Everything said until now +applies to the default selection list implementation. An alternative +implementation can be specified by using a type attribute on +the fd:selection-list element. The sections below describe the alternative +implementations currently available.

flow-jxpath selection list implementation

See the javadoc of the +FlowJXPathSelectionListBuilder +class for now.

Example:

In flowscript:

var data = new Object();
+
+data.cityList = new Array(2);
+data.cityList[0] = {value:"AL", label:"Alabama"};
+data.cityList[1] = {value:"AK", label:"Alaska"};
+
+form.showForm("flow/myform.form", data);

and the corresponding selection list definition:

<fd:selection-list type="flow-jxpath" list-path="cityList"
+                   value-path="value" label-path="label" />

Hint: the label can be any kind of object, its toString() method will be +called to get the string to be displayed. In case the object supplied as label +implements the XMLizable interface, its toSAX method will be called instead. One +practical application of this is using i18n labels:

importClass (Packages.org.apache.cocoon.forms.util.I18nMessage);
+...
+mylist[0] = {value: "x", label: new I18nMessage("myI18nKey") };

enum selection list implementation

This type of selection list outputs a list of items corresponding to the +possible instances of an enumerated type (see below).

Example:

<fd:selection-list type="enum" class="com.example.Sex"/>

outputs:

<fi:selection-list>
+  <fi:item value=""/>
+  <fi:item value="com.example.Sex.MALE">
+    <fi:label>
+      <i18n:text>com.example.Sex.MALE</i18n:text>
+    </fi:label>
+  </fi:item>
+  <fi:item value="com.example.Sex.FEMALE">
+    <fi:label>
+      <i18n:text>com.example.Sex.FEMALE</i18n:text>
+    </fi:label>
+  </fi:item>
+</fi:selection-list>

If you don't want an initial null value, add a +nullable="false" attribute to the +fd:selection-list element. You can specify an i18n key to use +as a label for the null element using the +null-text="i18.key.here" attribute. This applies only to +enum type selection lists.

Note : since the enum pattern is based on Class.getDeclaredFields() method, +it's not always granted that the enum selection list items will be in the same +order the fields are declared in the enumeration class. This is reported to +happen expecially on IBM JRE. A good solution to this problem is to use the +apache commons Enum as a super class of your enumeration classes. Due to the way +this enumeration pattern is implemented, it's possible to grant the element +orders in a portable way.

Errors and Improvements? If you see any errors or potential improvements in this document please help + us: View, Edit or comment on the latest development version (registration required). +
+
+ + + + + + Added: cocoon/site/site/2.2/blocks/forms/1.0/754_1_1.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/blocks/forms/1.0/754_1_1.html?rev=580139&view=auto ============================================================================== --- cocoon/site/site/2.2/blocks/forms/1.0/754_1_1.html (added) +++ cocoon/site/site/2.2/blocks/forms/1.0/754_1_1.html Thu Sep 27 12:56:05 2007 @@ -0,0 +1,453 @@ + + + + + + + + + + + + + + Cocoon Forms + + + + + + + +
+

Apache » Cocoon »

+
+ + + +
+ + +

Form

Concept

The form itself is not really a widget, but we include its reference +documentation here nonetheless.

Definition

<fd:form id="..." state="...">
+  <fd:widgets>
+    [...]
+  </fd:widgets>
+  <fd:validation>
+     [...]
+  </fd:validation>
+  <fd:on-create>
+     [...]
+  </fd:on-create>
+  <fd:attributes>
+    <fd:attribute name="..." value="..."/>    
+  </fd:attributes>
+</fd:form>
+

The widgets contained by the form are defined inside the fd:widgets element. +For an explanation of the other elements and attributes, see the +field widget. Specifying an id for the form is optional. +

Template

A form is inserted into a template by use of the ft:form-template tag:

<ft:form-template>
+  [...]
+</ft:form-template>
+

You can add the usual HTML form attributes such as action and method on the +ft:form-tempate, they will be replicated in the output.

Errors and Improvements? If you see any errors or potential improvements in this document please help + us: View, Edit or comment on the latest development version (registration required). +
+
+ + + + + + Added: cocoon/site/site/2.2/blocks/forms/1.0/755_1_1.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/blocks/forms/1.0/755_1_1.html?rev=580139&view=auto ============================================================================== --- cocoon/site/site/2.2/blocks/forms/1.0/755_1_1.html (added) +++ cocoon/site/site/2.2/blocks/forms/1.0/755_1_1.html Thu Sep 27 12:56:05 2007 @@ -0,0 +1,432 @@ + + + + + + + + + + + + + + Cocoon Forms + + + + + + + +
+

Apache » Cocoon »

+
+ + + +
+ + +

Templating

Introduction

CForms templates make it possible to define the layout for your form in a +simple way. The basic principle is that you create a template file containing +<ft:widget id="xyz"/> elements where you want to insert the +widgets. After execution of the template, these will be replaced by the XML +representation of the corresponding widgets. The ft:widget elements can thus be +embedded in e.g. a HTML layout. After processing of the template tags you will +end up with HTML with here and there a piece of XML describing a widget. This +XML description contains all state information of the widget: its value, +validation errors, selection-list data if any, and so on. These +widget-XML-descriptions will then typically be translated to HTML by an XSLT. +This XSLT is not specific to one form, as it simply needs to know how to +translate individual widgets to HTML, and does not have to create the complete +page layout. CForms contains just such an XSLT so you don't have to write it +yourself (except if you need to do heavy customisation). The image below +illustrates this process.

forms_template_transformer

Note: A completely different approach would be to do everything with +XSLT, starting from the output of the FormsGenerator. In +general we recommend to use the CForms templating approach though.

Available implementations

There are two different mechanisms available to process the form tags:

The JXTemplate-based approach is the newer one and is more powerful as you +can make use of standard JX constructs in addition to the CForms template tags. +

Locating the form instance object

In the most common case, the form object is passed by the flow controller to +the pipeline in the view data under a key named "CocoonFormsInstance". There are +alternative ways to locate the form, though these are dependent on the template +implementation (JX or the transformer).

Forms transformer element reference

The elements to which the forms transformer reacts are all in the "ft" (Forms +Template) namespace, which is identified by the following URI:

http://apache.org/cocoon/forms/1.0#template

These will generally be replaced by elements in the "fi" (Forms Instance) +namespace, which is identified by the following URI:

http://apache.org/cocoon/forms/1.0#instance
+

A template should always consist of a ft:form-template +tag which then contains the tags to insert the individual widgets. Widgets +are most often inserted using the ft:widget tag, but some widgets might need +specific tags. See the descriptions of the individual widgets for the +appropriate template tags.

ft:widget

The ft:widget element is replaced by the forms transformer by the XML +representation of a widget. Which widget is specified by the id attribute. The +ft:widget element can contain a fi:styling element containing parameters to +influence the styling process (the XSLT). The forms transformer will simply copy +the fi:styling element over to its output.

For example:

<ft:widget id="pass">
+  <fi:styling type="password"/>
+<ft:widget/>

will be replaced by:

<fi:field id="pass">
+  [... label, validation errors, ...]
+  <fi:styling type="password"/>
+</fi:field>

ft:widget-label

The ft:widget-label element will be replaced by the forms transformer with +the label of a certain widget (specified by an id attribute). The label will not +be wrapped in another element.

ft:continuation-id

The ft:continuation-id element will be replaced by the forms transformer by: +

<fi:continuation-id>
+  ID-of-the current-continuation
+</fi:continuation-id>

This might be useful for embedding the continuation ID in a hidden form +field, for example.

Errors and Improvements? If you see any errors or potential improvements in this document please help + us: View, Edit or comment on the latest development version (registration required). +
+
+ + + + + + Added: cocoon/site/site/2.2/blocks/forms/1.0/904_1_1.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/blocks/forms/1.0/904_1_1.html?rev=580139&view=auto ============================================================================== --- cocoon/site/site/2.2/blocks/forms/1.0/904_1_1.html (added) +++ cocoon/site/site/2.2/blocks/forms/1.0/904_1_1.html Thu Sep 27 12:56:05 2007 @@ -0,0 +1,364 @@ + + + + + + + + + + + + + + Cocoon Forms + + + + + + + +
+

Apache » Cocoon »

+
+ + + +
+ + +

HandleFormSubmitAction

Summary

No summary available. The summary needs to be defined using the + @cocoon.sitemap.component.documentation annotation in the Java source file for this component:

Basic information

Component typeorg.apache.cocoon.forms.acting.HandleFormSubmitAction
Cocoon blockAction
Java classforms
Cachable

Documentation

No documentation available yet.

Errors and Improvements? If you see any errors or potential improvements in this document please help + us: View, Edit or comment on the latest development version (registration required). +
+
+ + + + + + Added: cocoon/site/site/2.2/blocks/forms/1.0/915_1_1.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/blocks/forms/1.0/915_1_1.html?rev=580139&view=auto ============================================================================== --- cocoon/site/site/2.2/blocks/forms/1.0/915_1_1.html (added) +++ cocoon/site/site/2.2/blocks/forms/1.0/915_1_1.html Thu Sep 27 12:56:05 2007 @@ -0,0 +1,360 @@ + + + + + + + + + + + + + + Cocoon Forms + + + + + + + +
+

Apache » Cocoon »

+
+ + + +
+ + +

FormsGenerator

Summary

No summary available. The summary needs to be defined using the + @cocoon.sitemap.component.documentation annotation in the Java source file for this component:

Basic information

Component typeorg.apache.cocoon.forms.generation.FormsGenerator
Cocoon blockGenerator
Java classforms
CachableNo

Documentation

No documentation available yet.

Errors and Improvements? If you see any errors or potential improvements in this document please help + us: View, Edit or comment on the latest development version (registration required). +
+
+ + + + + +