cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Created: Templating
Date Sun, 23 Oct 2005 15:28:17 GMT
A new document has been created.

Document ID: 755
Branch: main
Language: default
Name: Templating
Document Type: Cocoon Document
Created: 10/23/05 3:28:04 PM
Creator (owner): Bruno Dumon
State: publish


Mime type: text/xml
Size: 4174 bytes


<p>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
<tt>&lt;ft:widget id="xyz"/&gt;</tt> elements where you want to insert
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.</p>

<p align="center"><img src="daisy:405"/></p>

<p class="note">A completely different approach would be to do everything with
XSLT, starting from the output of the
<a href="../../../../g1/476.html">FormsGenerator</a>. In general we recommend
use the CForms templating approach though.</p>

<h1>Available implementations</h1>

<p>There are two different mechanisms available to process the form tags:</p>

<li>A <a href="daisy:480">set of form macros for the JXTemplate Generator</a>
<li>A <a href="daisy:475">form template transformer</a></li>

<p>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.

<h1>Locating the form instance object</h1>

<p>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).</p>

<h1>Forms transformer element reference</h1>

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


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


<p>A template should always consist of a <a href="daisy:754">ft:form-template
tag</a> 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.</p>


<p>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.</p>

<p>For example:</p>

<pre>&lt;ft:widget id="pass"&gt;
  &lt;fi:styling type="password"/&gt;

<p>will be replaced by:</p>

<pre>&lt;fi:field id="pass"&gt;
  [... label, validation errors, ...]
  &lt;fi:styling type="password"/&gt;


<p>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.</p>


<p>The ft:continuation-id element will be replaced by the forms transformer by:

  ID-of-the current-continuation

<p>This might be useful for embedding the continuation ID in a hidden form
field, for example.</p>


The document belongs to the following collections: documentation

View raw message