cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] New: WhiteBoardCocoonForms
Date Fri, 04 Mar 2005 17:40:18 GMT
   Date: 2005-03-04T09:40:18
   Editor: TimLarson
   Wiki: Cocoon Wiki
   Page: WhiteBoardCocoonForms
   URL: http://wiki.apache.org/cocoon/WhiteBoardCocoonForms

   no comment

New Page:

= Description =

This is an area for experimental Cocoon Forms features.
It is intended to allow for discussion of actual code instead
of just abstract ideas, without incurring the overhead of
supporting the features before their designs have been finalized.

This is an experimental development area, so changes may
be made without notice, and no assurances are made that
everything will be in a working state at any given moment.

That being said, the area is for collaboration and so
should usually be in a mostly working state to allow for
evaluation and incremental improvement.

= Current experimental features =

The documentation which follows describes what is currently
implemented by the code.  If you modify the code, please
change this documentation as well.

All aspects of these features (syntax, implementation, etc.)
are subject to discussion and change.

== Macro library support ==
 *Define - Creates a reusable macro definition.
 *Expand - Creates an instance of a macro definition.
 *Macros - Defines a reusable macro library.
 *Import - Brings a macro library into scope.

The syntax and examples below are written assuming use of
macros in a form definition.  Identical macro support is
also present for the form binding and the form template,
using the respective name spaces.

=== Define ===
Creates a reusable macro definition.
{{{
Syntax:

  <fd:macro define="...">
    <!-- Widget definitions -->
  </fd:macro>

Example:

  <fd:macro define="product">
    <fd:field id="name">
      <fd:label>Name</fd:label>
      <fd:datatype base="string"/>
    </fd:field>
    <fd:field id="price">
      <fd:label>Price</fd:label>
      <fd:datatype base="decimal"/>
    </fd:field>
  </fd:macro>
}}}

=== Expand ===
Creates an instance of a macro definition.
{{{
Syntax:

  <fd:macro expand="..."/>

Example:

  <fd:macro expand="product"/>

Effective result:

  <fd:field id="name">
    <fd:label>Name</fd:label>
    <fd:datatype base="string"/>
  </fd:field>
  <fd:field id="price">
    <fd:label>Price</fd:label>
    <fd:datatype base="decimal"/>
  </fd:field>
}}}

=== Macros ===
Defines a reusable macro library.

{{{
Syntax:

  <fd:macros>
    <!-- Macro definitions -->
  </fd:macros>

Note:

  The "fd:macros" element must be the root of the document.

Example:

  <fd:macros>
    <fd:macro define="product">
      <fd:field id="name">
        <fd:label>Name</fd:label>
        <fd:datatype base="string"/>
      </fd:field>
      <fd:field id="price">
        <fd:label>Price</fd:label>
        <fd:datatype base="decimal"/>
      </fd:field>
    </fd:macro>
  </fd:macros>
}}}

=== Import ===
Brings a macro library into scope.
{{{
Syntax:

  <fd:import prefix="..." uri="..."/>

Example:

  <fd:import prefix="my-macros" uri="cocoon:/custom-fd-macros.xml"/>
  <fd:macro expand="my-macros:product"/>

Effective result:

  <fd:field id="name">
    <fd:label>Name</fd:label>
    <fd:datatype base="string"/>
  </fd:field>
  <fd:field id="price">
    <fd:label>Price</fd:label>
    <fd:datatype base="decimal"/>
  </fd:field>
}}}

The "prefix" is a user-defined string used when expanding
or extending macros to specify from which import to get
the base macros.

The "uri" identifies the source for the macro library.
Any protocol understood by Cocoon may be used.

=== Additional Notes ===

Import forms a flat namespace in the form model, but a tree
shaped namespace in the binding.  This is on purpose, so that
both designs can be evaluated.  Which would be the preferred
design to settle on, and why?

What should we call the root element of a macro library
(currently "macros", but perhaps there is a better name)? 

There is preliminary support for parameterized macros in the
form template code.

Mime
View raw message