Scripting in Forms

In Interactive Forms you can use internal script and JavaScript in a handler, precondition, prefill field as well as in certain form elements. This makes it possible to add powerful logic to your forms in order to react to and manipulate information entered in the form by the website visitor.

In This Topic

Using JavaScript in Interactive Forms

You can execute JavaScript in the following parts of a form:

• Prefilling Free Expression
• Precondition Free Expression
• Handler

Using JavaScript in conjunction with the unique internal identifiers in Interactive Forms you can get and set values for fields as well as pass data between the GX WebManager session and the form scope session. In order to achieve this, identifiers that uniquely identify all parts of a form are used. To achieve this, the identifiers for a step and form element are joined in a hierarchical fashion separated by a period (.) in order to uniquely identify all form elements and form parts. For example, if the unique identifier for a step is

wmstep_2

and the unique identifier for a text form element that is on step 2 is

last_name

then the format for uniquely identifying the form element is

wmstep_2.last_name

There is also a set of special identifiers for parts of a form that are not form elements. These are:

The above identifiers are built in the same way as for form elements. For example:

• wmstep1.messages — Retrieves any messages generated during step 1.
• wmfragment_1.errors — Retrieves any error in form element wmfragment_1 that was generated by the website visitor after attempting to navigate to the following step in a form (or submit the completed form).

Preconditions and Prefilling Free Expressions

When using JavaScript in a precondition or prefilling field of type Free Expression, enter the expression directly without the surrounding $ signs. Below are some examples of JavaScript expressions to use in preconditions and prefilling fields:

Precondition Free Expression Examples

The form element with identifier wmfragment2 is empty:

wmfragment2.value != ""

The form element with the identifier wmstep1.wmfragment1 is equal to "yes" and the form element with the unique identifier wmstep1.wmfragment2 is equal to "car":

wmstep1.wmfragment1.value == "yes" && wmstep1.wmfragment2.value == "car"

The length of the string in the form element with the identifier wmstep2.wmfragment3 is greater than "3":

wmstep2.wmfragment3.values.length > 3

Prefilling Free Expression Examples

The form element is prefilled with the value of the form element wmfragment1:

wmfragment1.value

The form element is prefilled with the value of the form element wmfragment1 concatenated with the value of form element wmfragment2:

wmfragment1.value + wmfragment.value2

Using JavaScript in Text Fields

JavaScript can also be used in some of the form element fields or handler or router parameters. To set the JavaScript off in a text field, it must begin and end with a dollar sign ($) in a practice referred to as interpolation. Using JavaScript in text fields allows you to retrieve a value from the form scope and reuse elsewhere. In the following examples, a value is retrieved from the form scope and used in a text field. The value from the "First Name" form element is used in a personal greeting:

Hello $wmstep1.firstname.value$.

The value from the "Last Name" form element is used in a personal greeting using the correct salutation as derived from the "Gender" form element:

Dear $ (wmstep1.gender.value == "m" ? "Mr.": "Ms.") + " " + wmstep1.lastname.value$

Valid Fields/Parameters for Using JavaScript

JavaScript can only be used in the following fields/parameters in Interactive Forms:

• WYSIWYG text in a paragraph form element
• Handler and router parameters of type STRING or TEXT_AREA
• Handler and router parameters of type Fragment value
• Handler and router parameters of type TEXT
• Condition parameters

Autocomplete

When entering a free expression in a field, Interactive Forms helps you complete your script using autocomplete. Based on the partial string that you type in, Interactive Forms will display a list of all objects that match the string. You can then select the object from the drop-down list and continue building your free expression.

Accessing Files in the Upload Form Element

You can use JavaScript expressions to access uploaded files in the form scope. For example, assume there is a step with identifier step_1 and a file Upload form element with identifier fileinputfragment. In XperienCentral versions R32 and lower, you can use the following expressions to access an uploaded file in the form scope:

$step_1.fileinputfragment.value$ -> returns the original filename (without path)
$step_1.fileinputfragment.filename$ -> returns the full current filename (including path)
$step_1.fileinputfragment.size$ -> returns the size (in bytes) of the file
$step_1.fileinputfragment.contentType$ -> returns the content type (MIME type) of the file

In XperienCentral versions R33 and higher, a file Upload form element can contain multiple uploaded files, therefore you should use the following expressions:

$step_1.fileinputfragment.values[0].file$ -> returns the uploaded file (of type java.io.File)
$step_1.fileinputfragment.values[0].file.absolutePath$ -> returns the full current filename (including path)
$step_1.fileinputfragment.values[0].originalFilename$ -> returns the original filename (without path)
$step_1.fileinputfragment.values[0].size$ -> returns the size (in bytes) of the file
$step_1.fileinputfragment.values[0].contentType$ -> returns the content type (MIME type) of the file

If the Upload element contains multiple files, use an expression similar to the following to retrieve all the files:

$
var files = step_1.files1.values;
var result = "";
for (var i=0;i<files.length;i++) {
   result += files[i].originalFilename + "\n";
}
result$

Deprecated Methods in XperienCentral R33 and Higher

In XperienCentral versions R33 and higher, the following form methods have been deprecated.

FormScope

The following method has been deprecated:

void setUploadFragmentValue(String fragment, UploadedFile file);

use the following method instead:

void setUploadFragmentValues(String fragment, List<UploadedFile> files);

FormValuesMap

The following method has been deprecated:

public UploadedFile getUploadedFile(String key)

use the following method instead:

public List<UploadedFile> getUploadedFiles(String key)

UploadFragmentScope

All methods have been deprecated. Use the following method instead:

List<Object> files = scope.getValues();
if (files != null) {
   for (Object fileObj : files) {
      if (fileObj instanceof UploadedFile) {
         UploadedFile file = (UploadedFile) fileObj;
      
         // Now read the attributes
         File file = file.getFile();
         long size = file.getSize();
         String contentType = file.getContentType();
         ...
      }
   }
}   

Back to top

Renaming Identifiers

Form fragments (form elements and steps) are assigned an identifier which you can use in your scripts to perform various tasks. You can rename an identifier and in most cases your scripts will still work. The following are the implications of renaming identifiers in Interactive Forms:

• If you update an identifier in a planned version of a form or form section, the references to the identifier will only be modified in that specific version of the form or form section.
• If you update an identifier in a public version of a form, the references to the identifier will only be modified in that version of the form.
• If you update an identifier in a public version of a form section, the references to the identifier will be modified in all versions of the form section. All form fragments with the same identifier and all references to the identifier will also be updated.

GX Software highly recommends that all form fragment identifiers be unique.



Back to top