Post-back fields are fields that require the client to post the form to the server after being edited. This permits the server to perform server-side validation on the field, provide immediate user feed-back and change the form according to user input.

Post-back fields are declared as normal fields in a form, except they also have the xdd:postBack flag present in the declaration, as is shown in the following example:

Note: A system maintaining multiple dynamic forms open at the same time needs to maintain control of available open forms. This can be done using a hidden session variable, as is shown in the example above. How this is done however, is implementation specific.

A server post-back is performed by sending an IQ set stanza with a formPostBack child element containing the current state of the form. The type of the form must be submit. The client should also provide the current user language in a xml:lang attribute, if available.

It is important to note that this server post-back is part of editing the form, and must not be treated by the server as a final submission of the data form.

As a response to a successful form post-back, the server returns a formPostBackResponse element with a result code of OK containing a new data form, as is shown in the following example:

In this example, the server adds a new parameter to the form, containing options that depend on the value of the first parameter.

Note: Server post-back should be made after the user is done editing a post-back field, but before actually navigating to the next field. It should not be done while the user is editing the field. For check boxes or list boxes, it is easy for the application to decide when the field has been edited, since the application can react to the controls click event. But for text edit boxes, you cannot perform a server post-back only just because the text property of the control has changed. You need to wait until the user leaves the control or something similar. However, as new fields can be added to the form, the client should wait for the response before deciding which control is the next control to go to.

Read-only fields should be laid out on the form just as a similar but editable field would, except editing should be disabled. Together with post-back fields, this option allows the form to enable/disable fields depending on user input. Read-only fields are declared as normal fields in a form, except they also have the xdd:readOnly flag present in the declaration, as is shown in the following example:

Note: Using this flag is different from the field type fixed defined in Data Forms. Fields of type fixed can also be used to display read-only content. However, this is done as static text, and not as a disabled control, specific for the type of content corresponding to the data in question. Using the readOnly flag instead, gives greater flexibility when it comes to presentation, as well as permitting the form server to enable and disable controls during the lifetime of the form.

There are many cases where you want to flag a control as having an undefined value or an uncertain value, instead of simply a missing value. This permits the form client to display the control in a specific way (for instance greyed), and omit the field when submitting the form back to the server, to avoid errors.

This technique can be used for instance, when editing the properties of multiple objects at the same time. Attributes that are equal among the objects can be reported as normal fields, while attributes that have different values among the objects, can be reported as having a value that is not the same everywhere. The client can then show the corresponding control greyed and omitting it in submissions of the form. If the user edits the control however, the form client can remove the flag and render the control normally. Submitting the now well-defined field value will set the corresponding attribute in all objects to the same new value. Omitting undefined values makes sure that the corresponding attributes are left as-is.

Fields with undefined or uncertain values are declared as normal fields in a form, except they also have the xdd:notSame flag present in the declaration, as is shown in the following example:

In the above example communication properties of a set of objects are edited. The form contains two fields, one address field, which will contain unique values for each individual object and therefore be flagged with the xdd:notSame flag, and a second baud rate field. This second field will probably contain the same value, if devices are connected to the same bus. Therefore, the field value is not flagged with the xdd:notSame flag.

Note: If the xdd:notSame flag is available in a field, the field must not be flagged as being required. They must also be omitted in any form submissions unless they have been edited first. Furthermore, any field submitted in a post-back as described in this document, must not be returned in the post-back response having the xdd:notSame flag.

Notice also that there's a difference between a missing value, i.e. a field without a value element defined, and a field with a value defined, but with the xdd:notSame flag present. In the latter example, the value might represent the value of one of the objects in a set of objects being edited.

A field can be flagged with an error message using the xdd:error element. Together with the post-back feature this allows for more advanced server-side validation of field values, as is shown in the following example.

In the above example, the user can enter a script expression into a text box using a server-specific scripting language. There's no way for the client to validate the script expression. However, by flagging the field with xdd:postBack the client posts the form back to the server when the user is finished writing the expression, and the server can validate it. In the example, the user has made an error, and the server returns the field, with an xdd:error flag, containing an error message that can be displayed to the user in an appropriate way.

Note: If a field is flagged with an error, and the user starts editing it, the client should remove the error flag of the field. The field can be flagged again with a new error flag during the next post-back.

The Data Forms XEP provides a mechanism to cancel forms, by submitting the form using type='cancel'. The Data Forms XEP stipulates that fields should not be included when using the form type cancel. However dynamic forms, i.e. forms containing post-back fields, will need the fields, since any dynamic form session will be identified using hidden fields in the form. So, to cancel a dynamic form, the xdd:cancel element with the entire submitted form should be sent to the form server using an IQ set stanza, as is shown in the following example:

After receiving the cancel request the form server returns a cancel response having a result code of OK if the form was found (and therefore cancelled), or NotFound if the form was not found. The following example shows an OK response:

Note: If cancelling a dynamic form using the approach described in this document, there's no need to also submit a cancel form as defined in the Data Forms XEP. The form server automatically makes sure the form is cancelled in all instances on the form server.

It might happen that the form server does not find the dynamic form posted by the form client during a post back. Reasons for this can be that the form does not include a post-back field, or that a form session timeout has occurred and the form server has discarded the dynamic form to avoid memory leaks. Regardless of the reason, the form server responds using a NotFound result in the response, when the client posts a form that is not found back.

Note: Form post-back must only be performed on forms containing post-back fields. The form server is not required to maintain dynamic form sessions for forms that lack post-back fields.

If another error occurs during post-back, the form server can inform the client about this, using the OtherError result code, and include an error element to describe the error, as is shown in the following example:

For a form server to maintain the status of the dynamic form, it will probably need to publish state or session information using hidden fields in the dynamic form. It's important that form clients be aware that such hidden fields are available and must always return them in all submissions of the form to the server.

A form client that supports dynamic forms and opens a dynamic form, i.e. containing parameters requiring post-back, must call the specific cancel method described in this document to cancel the form if not submitted. This to let the form server to release any dynamic form session resources it maintains.

Note: When submitting a dynamic form the normal way, any dynamic form session resources are also automatically released.

The form server must be aware that some form clients do not support dynamic forms. This in turn implies that form clients may not call the correct cancel method to cancel a dynamic form. To protect the form server from memory leaks, it must include a session timeout, and release any dynamic form session resources if no activity has been made during the corresponding time period. If the client would perform a post-back after the timeout period, a NotFound error message must be returned, to show the corresponding dynamic form session no longer exists, and therefore could not be found.

For normal operations, a dynamic form session timeout of 15 minutes is sufficient.