Actions

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.

The Script Action

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.

Example

To use a Script, create a question of type Action, and enter in the Action script field:

Script when=after

Enter the script in the Script details field. For example:

1	Select a question style Explain
2	Select a question type
	Action, such as Script Script when=before
3	Script details Use as a comment Enter HTML risk=0; if ( drink >=1 ) { risk = risk + 1; }

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:

script

The question "risk" is defined as a hidden question, and tallying must be turned on to analyze it, as described in Scoring.

Additional Script parameters

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 be used:

when=before
If present, means perform the script before the page is shown to the participant.

when=after
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.

decimals=N
If present, means calculate values with N decimal digits (eg., decimals=2). If absent, values are truncated to the nearest integer. Example: decimals=2

invalid=NNN
If present, when data used in calculations contains invalid characters or numbers, this value will be substituted instead. Example, invalid=0.

separators=yes
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:
N=0 1,234
N=2 1,234.56

locale=LL
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.

type=xxxxxx

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.

reviewing=1

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=XXXXX

If 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.
The default value for this parameter is 123E.
The error parameter is either NNNI and NNNE, where NNN is a number. NNNI will log the error to the Poll log and the system log. NNNE will also send an email to the ViewsFlash administrator. We recommend using E, as this will get someone's attention more quickly.
This parameter may contain the letter C or Q in front of it. If both letters are missing, and there's something wrong, the Action will be considered Invalid, questionnaire processing will stop, and the action specified in the Invalid Data section of the Security page will be performed. If this parameter begins with a C, as in C123E, processing will continue and the error message will be shown on the next page of the questionnaire at the top. This setting can be useful during early testing. If this parameter beings with a Q, as in Q123E, the error will be logged and processing will continue.
The default value of this parameter is 123E, which stops processing, writes the cause to the log, and notifies the ViewsFlash administrator of the cause.

Script syntax

Scripts use standard Java syntax:

each statement must end in a semicolon
curly brackets { } are used to group statements
/* */ and // are used for comments
all standard Java operators and functions can be used, including ? and : (if-then-else)
all Java conditionals can be used, including if () { } else { } , switch { } , for ( , , ), while ( ) { }, do { } while () and break
all Java library classes can be used, provided that they are used with their full package names, such as java.util.Date.

Script semantics

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:

int intermediate_calculation=0;

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.

Branching

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:

if ( income_level != 1 ) {
nextpage(); // skips to the next page
}

On the next page:

if ( income_level != 2 ) {
nextpage();
}

And on the next page:

if ( income_level != 3 ) {
nextpage();
}

You can also go to a question on any following page by using:

if ( income_level != 3 ) {
gotoquestion ("nextsection");
}

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:

if ( ! multisin ( favorite_colors,"red") ) {
nextpage();
}

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.

Dates

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:

datedifference ( date_created,"01/01/2000","days")

gives the number of days between the turn of the century and the date stored in date_created.

datedifference ( today(), last_date_modified,"months")

gives the number of months between today and the date stored in last_date_modified.

datedifference ( last_intervention_date,birthdate,"years")

gives a person's age at the time of last_intervention_date.
Note that the first date must be the most recent date; these functions do not return negative values. The third parameter must be a string in double quotes; only the first character is examined, so "months" is the same as "m". The today() function can be used to dynamically compute the date when the form is submitted. To compare against a static date, use the form "MM/DD/YYYY", in quotes, as in "06/28/2005".

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. For example:

dateadjust ( today(),7,"days")

gives the date a week from today

dateadjust ( today(),-1,"year")

gives the date one year ago

dateadjust ( first_date,3,"months")

gives a date 3 months after the date stored in first_date
Note that the third parameter must be a string in double quotes. If the second parameter refers to a question, turn it into an integer with:

dateadjust ( first_date, (int) number_of_months, "months" );

Multiple selection utility functions

These functions are used with multiple selection (checkbox) questions. For example:

multisin ( favorite_colors,"red","yellow","green" ) )

will be true if the user checked any of these choices, and false if the user doesn't check any of them.

multcount ( favorite_colors )

will count how many of the choices have been selected (checked) by the user.

Utility functions

Use showmessage to display a message to the user on the next page shown. For example,

showmessage ("The score is " + score.toString() );

will show a message like "The score is 3.0".
To get rid of the decimals, use this:

showmessage ("The score is " + ((int)score).toString() );

Use WriteLog to write a message to the questionnaire's log, visible in the questionnaire's Administration menu under View Log. For example,

WriteLog ("123I","My Message");

will write My Message to the log with a message number 123I. Message numbers with an E, such as 123E, will also be written to the Administrator's log and will send an emergency email message.
Question values can be used, such as "The value of x is " + x;

Use isin to test if a question has been answered in a particular way. For example,

isin ( score,4,5,8,9)

will be true if score is one of those values, and false otherwise

isin ( flavor, "vanilla","chocolate","strawberry")

will be true if flavor is one of those. Note that strings are in quotes.

Use answered to test if a question has been answered:

if ( answered (age) )

will return false if the question was not answered.

Use numberanswered to count how many questions were answered. This will return a value between 0 and 3:

numberanswered ( height, width, weight )

Flow control functions

These functions provide branching and other operations that alter the flow through the questionnaire form.

gotoquestion ("questionname");

Displays the page with question "questionname". If you don't use quotes, assign a value to the variable.

hidequestion ("questionname");

The question named "questionname" will not be displayed to the user completing the questionnaire form, whether on this page or a subsequent page. If you don't use quotes, assign a value to the variable. "Wildcard" names can be used to hide questions with similar names, such as "grid_*_1" or gridA_2?A?_1_*"

unhidequestion ("questionname");

The question named "questionname" will be displayed again. This reverses the effect of hidequestion. Wildcards can also be used.

showquestion ("questionname", show);

This function combines hidequestion and unhidequestion, above. When the second parameter is set to true, it acts like unhidequestion, and when set to false, it acts like hidequestion. Wildcards can also be used. Example:

showquestion ("price",true);

Instead of the value true or false, and expression can be used as well:

showquestion ( "tax", state.equals("CA") );

invalid ("questionname","message");

Displays "message" next to the question "questionname". This does not stop Scipt processing. Use a "return" statement to stop processing.
When questionname is an empty "" , the message is displayed at the top of the page.
When questionname is a series of question names separated by spaces, the message is displayed next to each question.

submit ();

Post the entire questionnaire as a completed form immediately, without displaying any further questions.

redirect ("http://redirectto");

Equivalent to the user navigating to a URL without submitting the questionnaire form. All data on that page of the questionnaire is discarded. Cannot be used in portals.

reset ("http://redirectto");

Discard any answers received so far and redirect to the given URL. Cannot be used in portals.

disallow ("http://www.yahoo.com"); // redirects to yahoo; always use a full URL, including the protocol

Discard any answers received so far, prevent the user from entering data in this form again, and redirect to the given URL. Cannot be used in portals.

nextpage() and nextpage("http://www.yahoo.com")

When updating a questionnaire in place (rather than adding a new one), will go on to the next page, unless this is the last page of the questionnaire, in which case the questionnaire will be submitted and then this will redirect the browser. When an agument is present, the browser is redirected to that URL; the argument cannot be used in portals.

save ("http://www.yahoo.com");

Saves the data entered so far, as if the Save key was pressed, and redirects the browser. Cannot be used in portals.

submit("http://www.yahoo.com");

Post the entire questionnaire as a completed form immediately, without displaying any further questions, and redirects the browser. Cannot be used in portals.

submit ()

Post the entire questionnaire as a completed form immediately, and shows the questionnaire response page. Cannot be used in portals.

Advanced uses

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:

getRequest().getRemoteUser();

getResponse().setContentType ("text/html");

getSession().getAttribute("attributename");

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:

String x = new String ("abc"); // is ok
com.myco.myclass x = new com.myco.myclass (); // fully qualified name required
CustomClass zz = new CustomClass (0); // is ok

Java environment variables can be read using:
System.getProperty("propertyname")
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