COB-INF.bean-editor.docs.forms.xml Maven / Gradle / Ivy
The newest version!
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<page
xmlns:cinclude="http://apache.org/cocoon/include/1.0"
>
<content>
<p>
At this point, our application allows us to navigate in
our TaskBean objects, and we're ready to start editing them.
</p>
<p>
To take advantage of the Cocoon Forms editing features, we need the
following:
<ul>
<li>
A pipeline to call the Flowscript <em>handleForm()</em> function
(provided by the Cocoon Forms Flowscript library, <em>Form.js</em>)
with the appropriate parameters.
</li>
<li>
A <em>Form Model</em> file, to define the data model
of our form.
</li>
<li>
A <em>Form Template</em> file, to define the layout
of our form while letting Cocoon Forms create the appropriate
HTML elements to edit our <em>form widgets</em>.
</li>
<li>
A <em>Form Binding</em> file, to define a
mapping between the Form data model and our Java beans.
</li>
</ul>
This seems a lot of work when described in this way, but notice
once again how modular things are: each "concern" of our bean editor
is clearly defined in its own place.
</p>
<p>
Note also that, while our example uses static XML files for these
definitions, nothing prevents you from generating them dynamically
using pipelines and the <em>cocoon:/</em> protocol. If your application
provides a central data dictionary, for example, it would be possible
to generate at least simple versions of the required definition files
automatically.
</p>
<h2>Sitemap</h2>
<p>
Let's look first at the pipeline definition for the
<em>edit/singleTask</em> request:
<cinclude:include element="xml-code" src="cocoon:/xml-element/bean-editor/sitemap.xmap/edit"/>
</p>
<p>
What this does is to call the <em>handleForm()</em> function of the
<em>Form.js</em> Flowscript library, telling it which of
our own Flowscript function to call to edit the form, and indicating
the locations of the <em>Form Model</em> (form-definition) and
<em>Form Binding</em> documents.
</p>
<p>
Later, the Flowscript function shown below will call this pipeline:
<cinclude:include element="xml-code" src="cocoon:/xml-element/bean-editor/sitemap.xmap/showForm"/>
</p>
<p>
Using the FormsTransformer to generate the appropriate HTML
elements for our form's <em>widgets</em>.
</p>
<h2>Flowscript</h2>
<p>
Here's our Flowscript form editing function, called by
the <em>handleForm</em> library function to edit our form:
<pre class="code">
0027 // Edit a single TaskBean object using Cocoon Forms
0028 function singleTaskEditor(form) {
0029 id = cocoon.request.getParameter("taskId");
0030 bean = db.getTaskBeanById(id);
0032 form.load(bean);
0033 form.showForm("internal/show-form/singleTask");
0034 form.save(bean);
0035 displayTaskBean(id,bean);
0036 }
</pre>
</p>
<p>
Notice how simple and readable the code is - the magic happens
behind the Cocoon Forms scenes, based on the Forms definitions
shown below.
</p>
<h2>Form Model</h2>
<p>Here's the definition of our Form Model.</p>
<cinclude:include element="xml-code" src="cocoon:/xml-element/bean-editor/cocoon-app/forms/singleTaskFormModel.xml/form"/>
<p>
As you can see, the Forms subsystem uses <em>widgets</em>
with <em>labels</em> and <em>datatypes</em> to define a Model.
</p>
<p>
If you omit the <em>repeater</em> element above, this is a fairly simple
data model which represents our form's data. The repeater is used to model
the 1-N relationship between our TaskBean and TaskCommentBean objects.
</p>
<p>
Strongly typed fields are an important features of Cocoon Forms,
and provide many standard validation features which make our
life easier.
</p>
<p>
This model is independent from the way the form
is going to look in HTML (or WML, or XUL, or whatever), and
also independent of the internal structure of our Java beans.
</p>
<p>
Here we use constants for the widget labels (field names),
but the i18n transformer could be added to our pipeline to
easily generate views and forms in multiple languages.
</p>
<h2>Form Binding</h2>
<cinclude:include element="xml-code" src="cocoon:/xml-element/bean-editor/cocoon-app/forms/singleTaskFormBinding.xml/form"/>
<p>
Here's the <em>binding</em> definition, which allows the Forms
subsystem to automatically move data from our Form's internal model
to our Java beans.
</p>
<p>
This looks simple enough: for example, we tell the Forms
subsystem that the form's <em>taskId</em> field is mapped
in readonly mode to the bean's <em>id</em> field.
</p>
<p>
The data mapping is triggered by the Flowscript <em>form.load</em> and
<em>form.save</em> calls shown above.
</p>
<p>
For the <em>taskId</em> form field, the <em>readonly</em> flag
makes the binding unidirectional.
The value of the form field will not be copied to the bean
when <em>form.save</em> is called.
</p>
<h2>Form Template</h2>
<p>
Here's the template used by the FormsTransformer, which is activated
by the above sitemap excerpt.
</p>
<cinclude:include element="xml-code" src="cocoon:/xml-element/bean-editor/cocoon-app/forms/singleTaskFormTemplate.xml/page"/>
<p>
Based on the Form Model definition, The FormsTransformer replaces
the <ft:widget> elements by the appropriate HTML input elements.
</p>
<h2>That's it!</h2>
<p>
Well, this time it certainly gets more complicated. But stand back and look
at the code in the <em>bean-editor/cocoon-app</em> directory
of this tour's files.
</p>
<p>
You will hopefully notice that we've written little "code", actually
almost only definitions but very little actual code. Yet, the editing application is
robust, easy to use, and very adaptable to different presentations or output
devices.
</p>
<p>
Another important feature of the Cocoon Forms subsystem is its extensibility:
a clean design makes it fairly easy to add custom Java classes for custom formatting,
validation and bindings.
</p>
</content>
</page>
© 2015 - 2025 Weber Informatics LLC | Privacy Policy