Package com.orchestranetworks.ui.form

# Class UIForm

java.lang.Object
com.orchestranetworks.ui.form.UIForm

public abstract class UIForm extends Object
This abstract class is the entry point for implementing a custom record form.

Note: Since 5.9.0, a more advanced user interface can be implemented to replace the default model-driven record form. For more information, see `UserServiceRecordFormFactory`.

### Definition in the data model

A specific record view may be associated with the default view of a table. The component must be declared under the element `<osd:table>`. For example:

>      <xs:annotation>
>        <xs:appinfo>
>          <osd:table>
>            <primaryKeys>/id</primaryKeys>
>            <recordForm osd:class="com.foo.MyUIForm"/>
>          <osd:table>
>        <xs:appinfo>
>      </xs:annotation>

where `com.foo.MyUIForm` is the fully qualified name of a class implementing this interface. The declaration may also use parameters:

>      <recordForm class="com.foo.MyUIForm">
>             <param1>...</param1>
>             <param2>...</param2>
>      </recordForm>

where `param1` and `param2` are JavaBean properties of the `com.foo.MyUIForm` class.

For more information, see the JavaBean specification.

### Life cycle

When a session of EBX® generates HTTP responses involving the record view:

1. The class specified is instantiated through its default constructor and the setter properties of the JavaBean are called (in the example above, `setParam1(...)` and `setParam2(...)`).
2. The method `defineHeader(UIFormHeader, UIFormContext)` is invoked.
3. The method `defineBody(UIFormBody, UIFormContext)` is invoked.
4. Finally, the method `defineBottomBar(UIFormBottomBar, UIFormContext)` is invoked.

Once all these definition methods have been invoked, the specified contents are then written in the following order:

1. the header
2. the body (invoking the method `UIFormPane.writePane(UIFormPaneWriter, UIFormContext)`)
3. the bottom bar

### Multi-threading

The EBX® user interface ensures that an instance of this class is executed by no more than one thread at any given time.

Since:
  5.3.0
See Also:
  - Integration introduction
  - `UserServiceRecordFormFactory`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UIForm()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `defineBody(UIFormBody aBody, UIFormContext aContext)`
  Specifies the body of the form.
  `void`
  `defineBottomBar(UIFormBottomBar aBottomBar, UIFormContext aContext)`
  Specifies the bottom bar of the form.
  `void`
  `defineHeader(UIFormHeader aHeader, UIFormContext aContext)`
  Specifies the header of the form.
  `boolean`
  `shallValidateForm(UIFormContext aContext)`
  Returns `true` if the user input associated with this form will be validated; returns `false` if the local user input related to the current form is ignored beyond the execution of this method.
  `void`
  `validateForm(UIFormRequestContext aContext)`
  This method offers the opportunity to perform custom validation on user input.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### UIForm

    public UIForm()

- ## Method Details

  - ### defineHeader

    public void defineHeader(UIFormHeader aHeader, UIFormContext aContext)
    Specifies the header of the form. Default implementation does nothing, that is, default header will be displayed.

    For details on when the EBX® user interface invokes this method, see Life cycle.

  - ### defineBody

    public void defineBody(UIFormBody aBody, UIFormContext aContext)
    Specifies the body of the form. Default implementation does nothing, that is, the default body will be displayed.

    For details on when the EBX® user interface invokes this method, see Life cycle.

    See Also:
      - `UIFormPane.writePane(UIFormPaneWriter, UIFormContext)`

  - ### defineBottomBar

    public void defineBottomBar(UIFormBottomBar aBottomBar, UIFormContext aContext)
    Specifies the bottom bar of the form. Default implementation does nothing, that is, the default bottom bar will be displayed.

    For details on when the EBX® user interface invokes this method, see Life cycle.

  - ### validateForm

    public void validateForm(UIFormRequestContext aContext)
    This method offers the opportunity to perform custom validation on user input. It typically does so by retrieving the HTTP parameter values from the incoming request and checking them, so as to supply the validation context with new, converted values. It can also add error messages.

    This method is called only if the method `shallValidateForm()` has returned `true` and after all other components have been validated (built-in and UI bean alike).

    Default implementation does nothing.

    Since:
      5.5.0
    See Also:
      - `shallValidateForm(UIFormContext)`

  - ### shallValidateForm

    public boolean shallValidateForm(UIFormContext aContext)
    Returns `true` if the user input associated with this form will be validated; returns `false` if the local user input related to the current form is ignored beyond the execution of this method.

    More precisely, user input validation is performed in five steps:

    1. All input components are validated either from a UI bean or automatically generated components.
    2. The constraints defined by data model nodes are executed, potentially adding their own error messages.
    3. This `shallValidateForm` method is invoked and decides whether the remaining steps below are to be invoked (it can also perform some validation itself).
    4. If this method returns `true`: the method `validateForm()` is invoked. For example, it can perform user interface-specific checks.
    5. Finally, if no errors block submission, the updates performed on the context are committed to the current dataspace. If there are errors, the page is redisplayed with error messages.

    Default implementation always returns `true`.

    Since:
      5.5.0
    See Also:
      - `validateForm(UIFormRequestContext)`