cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Updated: Form Libraries
Date Mon, 05 Sep 2005 01:54:51 GMT
A document has been updated:

http://cocoon.zones.apache.org/daisy/documentation/685.html

Document ID: 685
Branch: main
Language: default
Name: Form Libraries (previously Form libraries)
Document Type: Document (unchanged)
Updated on: 9/5/05 1:54:47 AM
Updated by: Max Pfingsthorn

A new version has been created, state: draft

Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name:  (unchanged)
Size: 5249 bytes (previous version: 100 bytes)
Content diff:
    <html>
    <body>
    
--- <p>Here comes the documentation of the brand new form libraries!</p>
+++ <h1>Form Libraries</h1>
    
+++ <p class="note">This feature is only available from the repository for the
+++ Google Summer of Code (GSoC) by
+++ <a href="https://svn.apache.org/repos/asf/cocoon/gsoc/mpfingsthorn/forms/">Max
+++ Pfingsthorn</a> as long as it is not integrated into the current Forms block.
+++ </p>
+++ 
+++ <p>It is now possible to define libraries of form definitions and bindings.
+++ Specific support for templates was intentially left out because of the
+++ frequently changing and unstructured nature of it. Other tools, such as the JX
+++ Template Generator's import feature or a combination of the Include Transformer
+++ and XSLT will do a better job dealing with any template formatting needs.</p>
+++ 
+++ <p>One important feature of the library subsystem is inheritance. Form widgets
+++ and bindings can inherit their contents and parameters from others. All such
+++ parent bindings/widgets will be referenced by IDs like so:</p>
+++ 
+++ <pre>&lt;fd:field id="myFieldID" extends="myOtherFieldID"/&gt;
+++ </pre>
+++ 
+++ <p>The attribute "extends" specifies the widget or binding to inherit from. The
+++ following is a simple example which shows how this works conceptually:</p>
+++ 
+++ <pre>&lt;fd:field id="parentField"&gt;
+++   &lt;fd:label&gt;Parent Field&lt;/fd:label&gt;
+++   &lt;fd:datatype base="string"/&gt;
+++ &lt;/fd:field&gt;
+++ 
+++ &lt;fd:field id="childField" extends="parentField"&gt;
+++   &lt;fd:selection-list&gt;
+++     &lt;fd:item value="1"/&gt;
+++     &lt;fd:item value="2"&gt;
+++       &lt;fd:label&gt;two&lt;/fd:label&gt;
+++     &lt;/fd:item&gt;
+++     &lt;fd:item value="3"/&gt;
+++   &lt;/fd:selection-list&gt;
+++ &lt;/fd:field&gt;
+++ </pre>
+++ 
+++ <p>The above snippet will result in the following situation:</p>
+++ 
+++ <pre>&lt;fd:field id="parentField"&gt;
+++   &lt;fd:label&gt;Parent Field&lt;/fd:label&gt;
+++   &lt;fd:datatype base="string"/&gt;
+++ &lt;/fd:field&gt;
+++ 
+++ &lt;fd:field id="childField"&gt;
+++   &lt;fd:label&gt;Parent Field&lt;/fd:label&gt;
+++   &lt;fd:datatype base="string"/&gt;
+++   &lt;fd:selection-list&gt;
+++     &lt;fd:item value="1"/&gt;
+++     &lt;fd:item value="2"&gt;
+++       &lt;fd:label&gt;two&lt;/fd:label&gt;
+++     &lt;/fd:item&gt;
+++     &lt;fd:item value="3"/&gt;
+++   &lt;/fd:selection-list&gt;
+++ &lt;/fd:field&gt;</pre>
+++ 
+++ <p class="note">Note that "extends" does not have to reference widgets in a
+++ library, widgets in the same context are also usable (e.g. widgets in the same
+++ group or two top-level widgets can inherit from another).</p>
+++ 
+++ <h2>Form Library Inclusion</h2>
+++ 
+++ <p>A sample library <tt>sample.xml</tt> might look like this:</p>
+++ 
+++ <pre>&lt;fd:library&gt;
+++   &lt;fd:widgets&gt;
+++ 
+++     &lt;fd:group id="account"&gt;
+++       &lt;fd:widgets&gt;
+++         &lt;fd:field id="owner"&gt;
+++           &lt;fd:label&gt;Account Holder&lt;/fd:label&gt;
+++           &lt;fd:datatype base="string"/&gt;
+++         &lt;/fd:field&gt;
+++         &lt;fd:field id="balance"&gt;
+++           &lt;fd:label&gt;Current Balance&lt;/fd:label&gt;
+++           &lt;fd:datatype base="float"/&gt;
+++         &lt;/fd:field&gt;
+++       &lt;/fd:widgets&gt;
+++     &lt;/fd:group&gt;
+++ 
+++   &lt;/fd:widgets&gt;
+++ &lt;/fd:library&gt;
+++ </pre>
+++ 
+++ <p>This library can be easily be imported into another library or form model by
+++ using the <tt>&lt;fd:import/&gt;</tt> statement.</p>
+++ 
+++ <pre>&lt;fd:form&gt;
+++   &lt;fd:widgets&gt;
+++ 
+++     &lt;fd:import prefix="lib" uri="sample.xml"/&gt;    
+++ 
+++     &lt;fd:group id="accountWithNumber" extends="lib:account"&gt;
+++       &lt;fd:widgets&gt;
+++         &lt;fd:field id="accountNo"&gt;
+++           &lt;fd:label&gt;Account Number&lt;/fd:label&gt;
+++           &lt;fd:datatype base="integer"/&gt;
+++         &lt;/fd:field&gt;
+++       &lt;/fd:widgets&gt;
+++     &lt;/fd:group&gt;
+++ 
+++     &lt;fd:group id="accountWithDifferentId" extends="lib:account"/&gt;
+++ 
+++     &lt;fd:expand id="lib:account"/&gt;
+++ 
+++   &lt;/fd:widgets&gt;
+++ &lt;/fd:form&gt;
+++ </pre>
+++ 
+++ <p>You can see how the value of "extends" now has a prefix which identifies the
+++ library to use while resolving the name. The seperator is ":" and such prefixes
+++ can also be deep, meaning reference a path in the inclusion tree if many
+++ libraries also import other libraries. In a situation where library "common" is
+++ imported by libary "lib", then widgets in the "common" library are also
+++ accessible with the prefix "lib:common:" from a form importing only "lib".</p>
+++ 
+++ <p>The above example shows the four usecases implemented in the current library
+++ system:</p>
+++ 
+++ <ol>
+++ <li>Library import: Imports a specific library into the scope of a form or
+++ another library under a certain key.</li>
+++ <li>Full widget inheritance with overriding and extending information (in the
+++ example, the "id" is overridden and a selection-list is added).</li>
+++ <li>The simple case of inheritance where only the "id" should change, say
+++ because of name clashes. While usually, the "fd:widgets" element is required in
+++ a "fd:group", it is not if you inherit the widgets from an already existing
+++ group, so changing the "id" is really simple.</li>
+++ <li>Simply using a widget defined in a library in the current library or form.
+++ This is achieved by the use of "fd:expand". Any occurance of "fd:expand" will be
+++ replaced by the referenced widget.</li>
+++ </ol>
+++ 
+++ <p class="note">The described statements "fd:import" and "fd:expand" are also
+++ available for bindings with exactly the same syntax and semantics, only within
+++ the binding namespace: "fb:import" and "fb:expand".</p>
+++ 
    </body>
    </html>


Fields
======
no changes

Links
=====
no changes

Custom Fields
=============
no changes

Collections
===========
no changes

Mime
View raw message