Apache » Cocoon »

Cocoon Forms 1.0 homepage

Cocoon Forms 1.0

Submit widget

Concept

The submit widget, usually rendered as a button, is used by the user to submit the form. The submit widget is a special kind of action widget, thus also has the same functionality as an action widget, however the submit widget does trigger validation and its purpose is to end the form.

You don't need to use a submit widget to submit a form. For example, in your HTML template you can simply put:

<input type="submit"/>

to be able to submit the form. Using a submit widget enables some extra functionality. You can control whether validation should be performed. You can put multiple submit widgets on a form and add different event handlers to them.

While a submit widget has the explicit purpose to submit a form, a form can also be submitted by other widgets. One example is the already mentioned action widget. It is however also possible to automatically submit a form when a widget changes its value, so that server-side event value-changed event listeners can be triggerd. This can be specified using <fi:styling submit-on-change="true"/> in the form template (see XSLT for more information on the fi:styling directive).

To know which widget caused the form to be submitted, use the method getSubmitWidget of the Form object.

Definition

<fd:submit id="..." command="..." validate="true|false" 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:submit>

The optional attribute validate, which is true by default, can be used to disable validation. The difference between an action widget and a submit widget with validate="false" is that a submit widget with validate="false" will end form processing, thus the form will not be redisplayed. Ultimately, it is of course the controller who decides this, but the forms hint towards the controller is that it shouldn't be redisplayed, and this is exactly what the flowscript integration library does.

Template & styling

See the action 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).