This entire section is new
Example 4 in the Examples Place, "health", illustrates many of these functions in detail.
The functions and how they can be used:
|* Defined by you|
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:
Note that, unlike the Calculate style, thse functions require that question names be enclosed in quotes.
Returns true if the user answered the question named 'questionname' or selected any of its choices.
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.
Only applies to checkbox questions. Returns the number of boxes in question named 'questionname' that the user checked.
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.
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.
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.
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.
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.
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.
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