Confirmations

Overview

If a user submits a form it is sometimes desirable to request an additional confirmation because by submitting the form the user might inadvertently trigger an action with severe and unforeseen consequences.

Web Center supports such confirmations.For each form property, you can define conditions which are checked if the form is submitted.If a condition is met, a message is displayed and a confirmation is requested.The user can then either confirm or cancel the request.

The configuration of a confirmation consists of the name of a Javascript function and the key of the confirmation message.The task of the Javascript function is to check the condition for displaying the message.

Condition Check Functions

A confirmation is requested if a certain condition is met.The condition is checked by a Javascript function.The function is called whenever the user submits the corresponding form.It is also called once immediately after form creation.The function can then for example store the initial value of a form field for later use in subsequent calls when the form is submitted.

Each function must be registered with a unique identifier.The identifier is used to specify the check function when configuring a confirmation for a form property.

Check Function Interface

A function for checking a condition must implement the interface

checkCondition (init, id, form, state)

Function name and argument names are of course arbitrary.

The arguments are

  • init – Whether the function is called during form creation (true) or when the end user submits the form (false)

  • id – The HTML id of the form field

  • form – The HTML form element

  • state – The state returned from the initial call.

The initial call may return any value, like a boolean, a string or an object. The value is passed transparently as argument state to subsequent calls.

Each subsequent call must return true if the condition is met, and false if not.

Predefined Checks

Web Center is shipped with two predefined condition checks. The first one checks if the value of a single-valued text field has been deleted or not; it is implemented by the function “confirmationConditions.valueDeleted“:

valueDeleted: function(init,id,form,wasEmpty) {
    var f = GF(id);
    if (f && (init || !wasEmpty))
        return isEmptyString(f.value);
    return false;
}

The initial call returns whether the field is initially empty or not. The result is then passed as 4th argument (“wasEmpty“) to subsequent calls which return true if the current value is empty while the initial one was not, which means if the value was deleted.

The second predefined function checks if role parameters are specified or not; it is implemented by the function “roleParams.isEmpty”.

Note that the check functions are usually deeply intertwined with the renderers used to display the corresponding form fields. Therefore, you cannot simply use them for form fields displayed by other renderers.

Registering Checks

You must register each condition check with a unique identifier by calling “confirmationConditions.register”, passing an array with the identifier and the check function. You can register one or more checks in one call.

The predefined condition checks are registered with identifiers “onDeleteValue” and “onEmptyRoleParams”:

confirmationConditions.register(
    [ "onDeleteValue", confirmationConditions.valueDeleted ],
    [ "onEmptyRoleParams", roleParams.isEmpty ]
);

Registering a single check goes like this:

confirmationConditions.register(
    [ "onEmptyRoleParams", roleParams.isEmpty ]
);

Form Property Configuration

Configuring a confirmation for a form field is easy.Form properties support the attribute “confirmation”, whose value should be the check identifier followed by the key of the confirmation message to be displayed if the condition is met.Identifier and message key must be separated by a colon.

Sample:

To get a confirmation message whenever a user’s manager is deleted, configure the form property like this:

<form-property name="manager" type="java.lang.String"
    fieldRenderer="userSearch"
    …
    confirmation="onDeleteValue:manager.deleted"
/>

When defining the message text, use “\n” for line breaks. A backslash at the end of a line in the message file indicates that the message text extends over the next line:

manager.deleted = You've deleted the user's manager.\n\n\
                  Are you sure?