[Cocoon Wiki] New: CocoonFormsScratchpad

[do...@cocoon.apache.org]

   Date: 2004-11-17T13:24:52
   Editor: TimLarson <ti...@keow.org>
   Wiki: Cocoon Wiki
   Page: CocoonFormsScratchpad
   URL: http://wiki.apache.org/cocoon/CocoonFormsScratchpad

   no comment

New Page:

'''Plans for discussion, revision, and implementation'''

Please note that even though these are just proposals,
the descriptions are written as though the features
already existed, to make it easier to convert the
descriptions into official documentation when and if
consensus is reached and a suitable implementation is
completed.

==  Macros and Types -- define/expand/inherit ==

A macro is a definition (or blueprint) consisting of a
list of one or more definitions for widgets, bindings,
or templates.  Expanding a macro does not create a macro
container, but instead creates instances of the definitions
it contains and inlines them into the surrounding environment.

Note that while groups are used for clarity in the examples
below, they are not required.  A macro may be expanded anywhere,
such as within the root form object or inside a repeater row.

For example, typing this macro definition, group
definition, and macro expansion request:
{{{
<fd:macro define="mymacro">
  <fd:field id="myfield">
    ...
  </fd:field>
  <fd:field id="yourfield">
    ...
  </fd:field>
</fd:macro>

<fd:group id="mygroup">
  <fd:macro expand="mymacro"/>
</fd:group>
}}}
is equivalent to typing this:
{{{
<fd:group id="mygroup">
  <fd:field id="myfield">
    ...
  </fd:field>
  <fd:field id="yourfield">
    ...
  </fd:field>
</fd:group>
}}}
...except that you now also have defined a reusable macro
named "mymacro", which you could expand in several places
in your form instead of retyping the list of definitions
in each place where those definitions are required.

----

You can also define a general macro, and create variants
based upon it.  Think of this as creating a blueprint
which contains most of your details, and then making
photocopies of this blueprint to fill in different
finishing touches to customize each copy.  In terms of
forms, this would consist of adding or deleting the
widget, binding, or template definitions in the copies
of the main macro.

For example:
{{{
<fd:macro define="mymacro">
  <fd:field id="myfield">
    ...
  </fd:field>
  <fd:field id="yourfield">
    ...
  </fd:field>
</fd:macro>

<fd:macro define="yourmacro" inherit="mymacro">
  <fd:add>
    <fd:field id="anotherfield">
      ...
    </fd:field>
  </fd:add>
</fd:macro>

<fd:group id="mygroup">
  <fd:macro expand="mymacro"/>
</fd:group>

<fd:group id="yourgroup">
  <fd:macro expand="yourmacro"/>
</fd:group>
}}}
is equivalent to:
{{{
<fd:group id="mygroup">
  <fd:field id="myfield">
    ...
  </fd:field>
  <fd:field id="yourfield">
    ...
  </fd:field>
</fd:group>

<fd:group id="yourgroup">
  <fd:field id="myfield">
    ...
  </fd:field>
  <fd:field id="yourfield">
    ...
  </fd:field>
  <fd:field id="anotherfield">
    ...
  </fd:field>
</fd:group>
}}}

If your customizations are only used in one place, then
you may specify the changes within the expansion request.

For example:
{{{
<fd:macro define="mymacro">
  <fd:field id="myfield">
    ...
  </fd:field>
  <fd:field id="yourfield">
    ...
  </fd:field>
</fd:macro>

<fd:group id="yourgroup">
  <fd:macro expand="yourmacro">
    <fd:del>
      <fd:field id="myfield"/>
    </fd:del>
  </fd:macro>
</fd:group>
}}}
is equivalent to:
{{{
<fd:group id="yourgroup">
  <fd:field id="yourfield">
    ...
  </fd:field>
</fd:group>
}}}

----

You can also modify definitions while expanding or
inheriting from a macro.

For example:
{{{
<fd:macro define="mymacro">
  <fd:field id="myfield">
    ...
  </fd:field>
</fd:macro>

<fd:macro expand="yourmacro">
  <fd:rename from="myfield" to="yourfield"/>
</fd:macro>
}}}
is equivalent to:
{{{
<fd:field id="yourfield">
  ...
</fd:field>
}}}

This is useful for tasks such as assigning non-conflicting
id's, adding validation rules, and setting datatypes.

The specific syntax for these various types of
modifications is still to be determined.

----

Collections of macros may be stored anywhere
accessible via a uri (including such uri's as
cocoon://somepath), to be imported as shared
macro repositories.  Macros are brought into
scope via an import statement and referenced
via a local prefix.

Given this file at "cocoon:/mysharedmacros.xml":
{{{
  <fd:macro-set>
    <fd:macro define="yourmacro">
      <fd:booleanfield id="mybool">
        ...
      </fd:booleanfield>
    </fd:macro>
    <fd:macro define="someothermacro">
      ...
    </fd:macro>
    ...
  </fd:macro-set>
}}}
this sample:
{{{
  <fd:import prefix="mymacros" uri="cocoon:/mysharedmacros.xml"/>
  <fd:macro expand="mymacros:yourmacro"/>
}}}
is equivalent to:
{{{
  <fd:booleanfield id="mybool">
    ...
  </fd:booleanfield>
}}}

A source containing a macro-set is also permitted to
itself import macros from other sources via this same
mechanism.  However, these nested imports are not
automatically made available to files which import
the macro-set.

You can individually re-export the macros manually:
{{{
  <fd:macro-set>
    <fd:import prefix="yourmacros" uri="someothermacros.xml"/>
    <fd:macro define="somemacro" inherit="yourmacros:somemacro"/>
  </fd:macro-set>
}}}