RealObjects Nimbudocs Editor 2.5.3885_Beta5

Guide: Form Editor


Introduction

The Form Editor is a powerful extension for Nimbudocs Editor which enables the document designer to include form fields in their documents. These form fields can be enriched with JavaScript to include business logic and custom validation. This guide explains the different conditions for supported form fields and how to use custom JavaScript.

To enable the form validation, the editor option formValidation has to be set.

Included Form Fields

The following form fields are included:

Text Field
This is a generic field for entering text.
Date Field
This field is a pre-configured text field and only accepts valid date strings. An empty string (i.e. no user input) is invalid by default. Additionally, a date picker will pop up upon entering the field.
Checkbox
A field that has only two states: checked and unchecked.

Conditions

You can specify JavaScript expressions for the following two conditions for every form field to determine its state.

Deactivation Condition

This condition determines whether the form element is deactivated or not. Deactivated form fields are not validated and cannot be filled out by the user.

If the JavaScript expression for this condition evaluates to a truthy value (e.g. a boolean true or a string), the field is deactivated. In all other cases, including when the expression is empty, the field is activated.

Validation Condition

This condition determines whether the input of the form field is valid or not. Invalid fields are highlighted.

If the JavaScript expression for this condition evaluates to a truthy value, the field is invalid. If no expression if specified, the form field is valid by default.

If the form field is invalid, an appropriate message is stored in the invalid attribute of the form field and can be displayed to the user via CSS. If the return value of the JavaScript expression is a string, the invalid attribute will contain exactly that string, otherwise it will simply contain "invalid".

Date fields have certain built-in validation checks which check if the input is a date string and if the input is not empty.

Form Field Reference Objects

Each form field has a unique name. You can reference other form fields from within an expression using a globally defined object with that same name. The objects evaluate to the respective form field's current input data, which is a string for text and date fields (or an empty string for such fields without input) or a boolean value for checkboxes (true for checked, false for unchecked).

To reference the form field you are currently editing, you can either use its name or the this keyword.

This is especially useful for quickly defining dependency trees for the deactivation condition of certain form elements.

Since the form field reference objects evaluate to string or boolean, common JavaScript properties and methods for these data types are also available, including length and match for strings.

Specifying a Deactivation Condition

Assuming you have two form fields: A checkbox with the name "Checkbox1" and a text field with the name "TextField1". A common use-case is that you want the text field to only be enabled if the checkbox is checked first.

To achieve this, you could define the following expression for the text field's deactivation condition:

if (Checkbox1 === false) { // if the checkbox is not checked
    return true;         // the field is deactivated
}

Or shorter:

return !Checkbox1;

"Checkbox1" is a checkbox field, thus the object "Checkbox1" evaluates to true if the checkbox is checked and to false otherwise.

Specifying a Validation Condition

Another pretty common use-case is to check if the user made a certain input, e.g. a specific string. The following example shows how to define an expression for a text field's validation condition that causes the field input to only be valid if the user inputs the word "dog". If the user enters other animal names, a custom error message is shown depending on the animal.

if (this == "cat") {
    return "Only dogs allowed."; // Custom invalid message for input "cat"
} else if (this == "elephant") {
    return "Elephants are too big."; // Custom invalid message for input "elephant"
} else if (this == "dog") {
    return false; // The field is only valid for input "dog"
}

return "Woof woof."; // Invalid message for any other input

Element Attributes

Every form field is represented in the document by a certain HTML element. Form field elements have several attributes that can be selected via CSS to create custom styles for the form fields, depending on their states.

roname
The unique name of the form field. The value of this attribute is identical to the top-level JavaScript object referencing the field used in expressions for the fields' conditions.
roform
This attribute determines the type and thus the behavior of the form field. Possible values are: text for a text field, date for a date field, checkbox for a checkbox.
roinvalid
If this attribute is present, the form field's input is not valid (according to a pre-defined or custom Validation Condition). The value of the attribute is a string describing why the input is invalid. It is the return value of the field's expression for its Validation Condition.

Helper Functions

Global helper functions are available within the context of the JavaScript expressions which provide convenient access to commonly used functionality:

count(formfield...) → {Number}
This function takes an arbitrary number of form elements as argument and returns the amount of form fields that have been filled out.

Check Exactly Two of Three Boxes

if (count(Checkbox1, Checkbox2, Checkbox3) != 2) {
    return "Please check two boxes."
}
isInt(formfield) → {Boolean}
Returns true if and only if the input of the given form field is an integer.
isPosInt(formfield) → {Boolean}
Returns true if and only if the input of the given form field is a positive integer.