JavaScript functions

This entire section is new

Example 4 in the Examples Place, "health", illustrates many of these functions in detail.

The Layout question Style uses Javascript statements that enhance questionnaire layout. The Layout question style is also used to define functions which are useful for custom validation and calculations. Functions described here, and any custom functions defined using a Layout question style, can both be used in a Calculate question style. Besides calculation, these functions are useful for custom validation and to populate form elements. Using these functions is much easier than writing raw javascript to retrieve and set values of form elements.

The functions and how they can be used:

The four different ways to use these functions correspond to different stages of page loading and submission. The "When Loaded" stage happens as a page is being loaded. For example, CogixPosition statements defined in a Layout question to position elements on the page are executed in this stage. The "Calculate" stage refers to expressions used with the Calculate style, if one is used. The functions are called when a calculation takes place, which is when the page is loaded and whenever any of the elements in a Calculate expression changes. Then "When Submitted" stage happens when the user presses a button that submits the form. The CogixWhenSubmitted function, if present, is called at that point. When that is complete, the "Validate" stage occurs when a CogixValidate function, if present. This function can perform validation tests and call the CogixInvalid function to prevent the form from being submitted and display error messages.

Here are these stages presented in list form:

• The page is loaded and displays
• Javascript statements executed, such as CogixPosition
• Calculate questions are performed after the page is loaded and every time a compnent of the calculation changes. They can use built-in Javascript functions, these functions, and custom functions
• Clicking one of the buttons such as Next begins the process of submitting the page
• The CogixWhenSubmitted function is called, if one is present
• If the button pressed is Previous or Save, the form is submitted without performing the rest of these steps
• Data validations defined with each question, such as Answer Required, are performed. Any failed validations display a message and prevent the form from being submitted
• The CogixValidate function is called, if one is present. If it finds something that is not valid, it calls the CogixInvalid function, which displays a message and prevents the form from being submitted

Function descriptions

Note that, unlike the Calculate style, thse functions require that question names be enclosed in quotes.

CogixAnswered ('questionname')

Returns true if the user answered the question named 'questionname' or selected any of its choices.

CogixAnsweredThis ('questionname',value,value,value)

Returns true if the user's answer to the question named 'questionname' matches one of the values in the list. Use as many values as you need, separated by commas. If the values are not numbers, enclose them in quotes.

CogixCountChecked ('questionname')

Only applies to checkbox questions. Returns the number of boxes in question named 'questionname' that the user checked.

CogixCountCheckedThis ('questionname',value,value,value)

Only applies to checkbox questions. Returns the number of boxes in question named 'questionname' that the user checked which match the values in the list. Use as many values as you need, separated by commas. If the values are not numbers, enclose them in quotes.

CogixNumber ('questionname')

Returns the user's answer to the question as a Javascript Number, that can be used in a calculation. If the user has not answered the question, or the value is not a number, returns 0. Decimal values are allowed.

CogixIsInteger ('questionname',negativeok)

Returns true if the user's answer to the question is a valid integer, without a decimal point. Use true as the second argument to make negative numbers; use false or just leave the second argument out and negative numbers will be invalid. If the user has not answered the question, or the value is NaN or Infinity (which can happen when dividing by zero) returns false.

CogixString ('questionname')

Returns the user's answer to the question as a Javascript String. If the user has not answered the question, returns an empty string.

CogixSet ('questionname', value)

Sets the question named 'questionname' to the indicated value. This works with all question types except checkbox. For checkbox questions, call this function repeatedly. The first time use the word null as the value; this will uncheck all the boxes. Then call this box once for each value that needs to be set. It is possible to uncheck a specific box by using false as the third parameter.

CogixWhenSubmitted ()

This function, which you define, is called when the user presses any of the buttons in the form, such as Next. It can use CogixSet, for example, to set values depending on other values entered, which can be interrogated using CogixNumber, COgixString, CogixIsInteger, etc.. The variable ValidatorArrayProperties.ValidatorSuppress is set to true if the user clicked the Previous or Save button. This function does not return a value. If you don't define this function, it does nothing.

CogixValidate ()

This function, which you define, is called when the user presses the Next or Submit buttons in the form. It can perform its own validation checks, using functions such as CogixAnsered, CogixIsInteger, and others (see above). If it finds an invalid condition, it calls CogixInvalid (see below). Example 4 in the Examples place illustrates these uses. This function does not return a value; if it calls CogixInvalid, that will prevent the form from being submitted. When the user enters valid answers, this function will be called again, and it should not call CogixInvalid this time, allowing the form to be submitted. If you don't define this function, it does nothing.

CogixInvalid ('questionname','message')

This function sets the error display for question 'questionname' to 'message', in the same way that question validatinos such as Answer Required do. Calling this function is enough to prevent the form from being submitted.

CogixMessage ('message')

This function sets the error display area at the top of the form to 'message' temporarily. This is useful for a general prompt such as 'Answer all questions'. This area is cleared for displaying validation messages when the form is submitted.

The CogixPosition, CogixLayout, CogixColorRows, CogixLegend, CogixLegendAll, CogixAnsswerColumns, CogixAnswerColumnsSorted are explained in Layout.

Next: Matrix Editor