Form processing

Live example: http://ztemplates.org/samples-form/

Features

• event-driven client-side UI update
• server-side form parameter matching
• server-side form parameter validation
• server-side state update

since 0.9.9.7 it is possible to write pure client side form validations, or purely server side form validations or mixed client and server side validations.

The forms are quite new in ztemplates so there may be api changes around the corner...

AJAX form state management

The form state is composed of

• form values This is what you usually persist or use otherwise in your application
• validation state
• form metainfo like writeable, readable, required. This is what is used to build the visual form representation.

In ztemplates the complete form metainfo and validation state can be derived from the form values. Thus only the form values have to be persisted and sent from the browser to the server.

A value and it's associated metainfo and validation state is bundled into a property or a operation. The complete form state is stored in a form pojo, in its properties and operations.

Every form is managed on the client (browser) by a ZFormScript component. ZFormScript keeps and manages the form state in a JavaScript variable. The form state is provided to the client by a (form specific) form AJAX handler. The handler converts the form state to a JSON representation and sends it to the client. This is done with the help of the @ZExposeJSON annotation.

Whenever a UI-component decides that the form state has to be refreshed it triggers the AJAX form state refresh cycle:

• client:
  • a UI component receives a change event
  • in the event handler the UI component triggers the AJAX form refresh cycle
  • since 0.9.9.7 the client side validators for the changed property are executed.
  • if all client side validators succeed, the form field values are sent to the server, else the field displays the error and the cycle ends here. To avoid unnecessary server-calls, the server call can be disabled for a property by calling ZProperty.setAjaxReloadState(false).
  • since 0.9.9.7 if no server call is made, the operation client side validators are called to enable/disable the operations
• server:
  • instantiates and fills the server-side form object with the new values.
  • the triggering value is validated
  • if validation succeeds, the ChangeListeners are called
  • after all form values are adjusted on the server, the form metainformation is computed. (It contains the metainformation like readable, writable, required and so on). Here the order is not important, as the metainformation must use only values and validation state which were computed in the previous steps, but not other metainformation.
  • the form is converted to JSON by the form AJAX handler and sent back to the client.
• client:
  • the new form state is placed into a defined javascript variable.
  • ZFormScript fires a form state change event.
  • every AJAX enabled UI-component is registered as a listener to form state change events and updates the components UI.

So there is a common, UI-component-independent mechanism for form-state management and a UI-component-specific mechanism for updating the UI-component display.

More information

See the AJAX Form Tutorial for a step by step introduction.

Download the complete code of the AJAX form live example.