apache > cocoon

- Home

# Union widget

## Concept

Uses one out of a set of widgets based on the value of a certain other widget.

## Definition

    <fd:union id="..." case="..." state="...">
      <fd:widgets>
        [...]
      </fd:widgets>
      <fd:on-create>
        [...]
      </fd:on-create>
      <fd:attributes>
        <fd:attribute name="..." value="..."/>
      </fd:attributes>
    </fd:union>

The `case` attribute specifies the ID of a widget that will be used to select which one of the widgets will be active (the value of the case widget should correspond to the ID of one of those widgets). This case widget will most often be a field with a selection list.

If you want to switch between sets of widgets, you can group them into group widgets.

## Template

Insertion of a union widget in a template is done using `ft:union` and `ft:case` elements:

    <ft:union id="...">
      <ft:case id="...">
        [...]
      </ft:case>
      [... more ft:case elements ...]
    </ft:union>

## Example

Definition:

    <fd:field id="testcase">
      <fd:datatype base="string"/>
      <fd:selection-list>
        <fd:item value="case1"><fd:label>Case 1</fd:label></fd:item>
        <fd:item value="case2"><fd:label>Case 2</fd:label></fd:item>
      </fd:selection-list>
    </fd:field>

    <fd:union id="testunion" case="testcase">
      <fd:widgets>
        <fd:group id="case1">
          <fd:field id="field1">
            <fd:datatype base="string"/>
          </fd:field>
          <fd:field id="field2">
            <fd:datatype base="string"/>
          </fd:field>
        </fd:group>
        <fd:group id="case2">
          <fd:field id="field1">
            <fd:datatype base="long"/>
          </fd:field>
          <fd:field id="field2">
            <fd:datatype base="long"/>
          </fd:field>
        </fd:group>
      </fd:widgets>
    </fd:union>

Template:

    <ft:widget id="testcase">
      <fi:styling list-type="dropdown" submit-on-change="true"/>
    </ft:widget>

    <ft:union id="testunion">
      <ft:case id="case1">
        <ft:group id="case1">
          <ft:widget id="field1"/>
          <ft:widget id="field2"/>
        </ft:group>
      </ft:case>
      <ft:case id="case2">
        <ft:group id="case2">
          <ft:widget id="field1"/>
          <ft:widget id="field2"/>
        </ft:group>
      </ft:case>
    </ft:union>

Note
Note the use of `submit-on-change` on the case widget to let the union widget automatically switch when the case is changed.
Note
Don't forget the group tags inside the case tags!
If you do, an update of the form will result in a
org.apache.cocoon.forms.FormsRuntimeException: Union 'testunion' has no child named 'field1'

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).