apache > cocoon

- Home

# Action widget

## Concept

Used to trigger an action event on the server side. Usually presented as a button the user can press (though this is not required). When an action widget was activated, validation will not be performed. This is because usually it would be strange to have other fields validated when the user's intention wasn't really to submit the form. If you want validation to happen, use the submit widget. After pressing an action button, the form will normally always be redisplayed, unless the event handling code explicitely disables this (by using the method `endFormProcessing` method on the `Form` object).

## Definition

    <fd:action id="..." command="..." state="...">
      <fd:label>...</fd:label>
      <fd:help>...</fd:help>
      <fd:hint>...</fd:hint>
      <fd:on-action>
        [...]
      </fd:on-action>
      <fd:on-create>
        [..]
      </fd:on-create>
      <fd:attributes>
        <fd:attribute name="..." value="..."/>
      </fd:attributes>
    </fd:action>

The command attribute specifies a name that will be part of the event generated by this widget. This can sometimes be useful. For example, on the Repeater action and Row action it indicates what to do. Previously this attribute was called action-command (now deprecated).

For more information on how event handlers are defined, see Event Handling. The interface to be implemented for Java event listeners is `org.apache.cocoon.forms.event.ActionListener`. The WidgetEvent subclass is `org.apache.cocoon.forms.event.ActionEvent`.

## Template

An action widget is inserted in a template using the ft:widget tag:

    <ft:widget id="..."/>

## Styling (default HTML XSL)

By default an action widget is shown as a button.

To render the action widget as an image:

    <ft:widget id="...">
      <fi:styling type="image" src="foo.gif">
    </ft:widget>

To render the action widget as a link:

    <ft:widget id="...">
      <fi:styling type="link">
    </ft:widget>

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).