XPE Forms is an advanced server-side forms engine. As with all XPE services, it is implemented as a RESTfull XML service allowing the service to be accessible from any client that support XML and HTTP.

Basic Concepts

There are a number of basic concepts to be aware of in order to utilise the advanced functionality of the XPE Forms Service. These will be explained here at a high conceptual level. Some examples will be provided here were appropriate. More detail and more specific examples will be given in the manual entries available below the XPE forms manual menu entry.

Instance Data

XPE Forms utilises the concept of an instance data XML fragment in order to fill the form fields and to submit the final form data to a submission pipeline for processing. This concept is very familiar to the W3C XForms instance data concept. This instance data is just an XML fragment initially containing the data required to fill the form fields with initial values. When the form is submitted to a business pipeline (action pipeline) this fragment is filled from the form fields and posted to the pipeline.

For example the instance data for a login type form may look like:

Validation

XPE Forms provides three levels of validation. The first two levels cover field level validation. The first level of validation allows a schema file to be applied by the XPE Forms engine to the instance data to enforce schema level validation. This validation is enforced when a standard submission is attempted. The currently supported schema languages are:

• a W3C XSD Schema;
• a Relax-NG Schema;

The second field level validation can be defined at the form field level by specifying a type on the actual form field definition:

The third level of validation is the business level validation provided by a unique XPE Forms concept called Consistency validation. This validation can be triggered on specific form events such as after a certain nominated field has its value changed. When such an event occurs, XPE Forms will post the form and instance data to a nominated consistency pipeline which may perform any processing on the instance data it sees fit before responding with a new form (and instance data). This is most handy when changes to certain fields require the regeneration of other fields that cannot be performed on the client (browser). For example a form may have two fields such as country code and state code. The country code is a dropdown list initially containing all the possible country codes available for selection. The State Code field contains all the valid State codes applicable to a given Country Code. When the user changes the Country Code selection from IT (Italy) to AU (Australia), the form has become inconsistent since the State Code droptown still contains the valid States (or regions) applicable to Italy. Here the Consistency Service Pipeline can be invoked to bring the form back to a valid and consistent state by regenerating the XML Instance data or form by populating the State field dropdown with the valid states applicable to Australia. The same service can also be used when the form is ready to be submitted to ensure that more complex data interrelationships and business rules are not violated by the form data. From this it can be seen that this validation performs two functions:

• Ensures form data consistency;
• Ensures business rules conformance;

Basic Operation

To use XPE forms a client application formats an XML fragment containing both XHTML elements and XPE Form elements and then POSTs the fragment to the XPE Forms service.

The XPE Forms service then:

• accepts the XML fragment;
• creates an internal representation of the form;
• validates the structure and contents of the form;
• fills the form elements with the data supplied (instance element);
• redirects the client to a URI representing the form;
• when the client issues the get to the redirection URI XPE Form renders the form;

Once the form is rendered in a browser, the user begins to interacts with the form filling in fields in the usual way. One or more form widgets may be specified as either:

• submission widgets (usually a button);
• consistency widgets;

When a consistency widget is changed, the XPE Forms engine will trigger a submission to the specified consistency pipeline. At this point the XPE Engine will not validate the form against any specified schema. After the consistency pipeline executes, a new instance of the entire form will be displayed with any new data filled in. At this point the user continues to interact with the form.

When a submission widget is changed, the XPE Form engine will trigger a submission to the specified action pipeline, but only after the forms instance data passes all schema level validation. Depending on the result of the submission, the XPE Forms engine may do one of two things:

• If the submission was successful, then a redirect to the onSuccess pipeline is issued and all interaction with the form is finished.
• If the submission failed, then an error message is displayed and the user may continue to interact with the form.

Ajax-based Pop-up XPE Form

With the Ajax technology, an XPE Form can be implemened as a pop-up form in a page. This allows for more efficient interaction with the end user. To use the pop-up form, the following steps should be followed:

1. Add the ajax:popupXForm in the page template where the form to be displayed and configure the xlet accordingly.
2. Create an additonal page with a service template which should only have one xlet, the Core:XForm Reader. Make sure you configure the form type to "Json".
3. Write your XPE Form in the XForm Reader page.
4. Add the following markups to the element of the content papge where the ajax:popupXForm is: onclick="XPE.bus.occurred('open',{channel:'contents',uri:'/xpe/portal/serviceJson/{page uuid}'});return false"

Ajax response handling

XPE form returns xpeform_success event if a form submission is successful. When working with XPE CMS, the response also contains the objectIds returned by the CMS. For example,