Actions are special functions that allow calculation, branching and specialized processing. You can create your own, since they are Extensible. The most commonly used Action is Script, described here. See also Other actions.
To use an Action, create a question with the Standard style and choose the Action type. In the Action script field, enter the name of the Action, a space, and any parameters it uses. Many Actions require additional information to be entered in the Script details field, which automatically increases in size if necessary.
Using Script, a questionnaire form can score and calculate, validate data, go to or skip around questionnaire pages, hide questions, and submit or end the questionnaire.
Many of these functions are illustrated in the Question Library and in the Examples place. To use the Question Libary, simply pick it from the menu and select one of the questions presented in the drop down menu.
Security Note: If using User Security, the administrator must grant the the right to use Script in the questionnaire's Location.
To use a Script, create a question of type Action, and enter in the Action script field:
Enter the script in the Script details field. For example:
Select a question style
|Select a question type
Action, such as Script
|Script details Enter
In the example below, two questions are created: "drinking" as a radio button with values 0,1,2,3, and "risk" as a hidden field on a second page. The value of risk is 0 or 1, depending on how a visitor answers the drinking question. An Action question, calculate_risk, on the first page, calculates the value of risk. The Visual Editor shows this:
The question "risk" is defined as a hidden question, and tallying must be turned on to analyze it, as described in Scoring.
The Action field must contain the word Script. Additional parameters
are of the form name=value. If more than one parameter is used, separate
it from the others with a comma. The following additional parameters can
If present, means perform the script before the page is shown to the participant.
If present, means perform the script after the participant presses the next or submit button.
If neither is present, and the Action is the first question on a page, when=before will be assumed;
similarly, if the Action is the last question on a page, when=after will be assumed. If the question
is neither the first nor the last, one of these parameters must be present.
If present, means calculate values with N decimal digits (eg., decimals=2). If absent, values are truncated to the nearest integer. Example: decimals=2
If present, when data used in calculations contains invalid characters or numbers, this value will be substituted instead. Example, invalid=0.
If present, calculated values will show grouping separators such as 1,000,000. For example, the value 1,234.56 will be shown as follows:
If present, means format numbers using this locale. If not present, the platform's locale is used. For example,
locale=en_US will format numbers as 1,234.56, and locale=de_DE will format numbers as 1.234,56.
If present, this parameter tells Script how to treat
the fields in a calculation. Normally, this parameter is absent, and Script
considers all fields as numeric, except when the question name includes the
word "date", or the
actual data is not numeric. When using type=, Script treats all questions
involved as the type indicated. This parameter is best used with very short
scripts. The possible values are:
type=float, type=date, type=string and type=integer.
If present, this parameter suppresses execution of the Script during normal questionnaire processing. The Script will be executed (before or after) only when the questionnaire is reviewed or updated using Data Review API commands.
error=XXXXXIf present, this parameter determines what to do when an expression evaluation fails. This is most often caused by a syntax error, by misspelling the name of a function or variable. Although many of these potential errors are caught before a questionnaire is published, it is possible for these errors to remain undiscovered until actual data is entered. If that is the case, using this parameter can be very helpful.
Scripts use standard Java syntax:
The "variables" in the scripts are question names from the questionnaire. Unlike Java, variables must NOT be declared. If you declare a variable explicitly, it becomes a temporary variable instead of a question in the questionnaire:
When using question names in expressions, do not put them in quotes. When using question names as parameters to built-in functions such as gotoquestion, put them in quotes. The examples below show explicitly when to use quotes and when not to use them.
To direct flow to a page based on the value of a question,
such as a radio button, and to skip around the other pages, use a Script Action with when=before on each of the pages, and use an if statement to not
avoid showing the page if it is not relevant. For example,
if a question "income_level" has values 1,2,3, add a script like
this to each page that contains income_level:
You can also go to a question on any following page by using:
To present different pages based on the multiple selections made by the
user in a in a multiple selection (checkbox) question, use a Script Action with when=before on each of the pages, and use an if statement with
the multisin function. For example, if a question "favorite_colors" has values
"red","green" and "blue", add a script like this to each page:
This tests favorite_colors for the value red; the ! means "not", so if the color
red is not selected, this page will not be shown.
Add similar code on each page to prevent the page from being shown when it is not appropriate.
The Branching questionnaire in the Examples place illustrates these techniques in action.
Script can handle date arithmetic. Make sure that question names include the word "date", as in "event_date", "date_last_entered". Dates are stored in the database as strings, in US English format MM/DD/YYYY, such as 06/28/2005.
To calculate the difference between two dates, use the datedifference function,
which counts the number of years, months, or days between two dates. For example:
To create a date relative to another date, use dateadjust, which calculates
a new date a given number of days, months, or years away from the given date.
These functions are used with multiple selection (checkbox) questions.
Use showmessage to display a message to the user on the next page shown. For example,
These functions provide branching and other operations that alter the flow through the questionnaire form.
Methods are provided for direct access to the HttpRequest, HttpResponse and HttpSession objects. Be careful when using these methods in a JSR 168 portal environment, as they are likely to not work in a portal. To redirect, use methods such as reset and submit instead. The methods are, with examples:
When using custom Java classes, if a class name does not being with a capital letter, it may be necessary to provide a fully qualified name of a class. Examples:
Java environment variables can be read using:
They can be assigned to hidden fields, which can then be used with question piping anywhere it is allowed.
Some of the Cogix provided examples may use a variable named cogix_vwf_validator_instance. This is used to acess advanced internal capabilities and should only be used as shown in Cogix examples. it is recommended to use getRequest() or the built-in method such as reset and submit described above instead.
Next: Other Actions