FORM

With the statement FORM, the model developer can create QUESTION and ANSWER screens (forms) that are shown when the ITP Model is run with ITP/OnLine Server. The answers provided by the user can be used in the model document.

The statement FORM is similar to the statement INTERACT. The difference is that FORM is intended to be used with ITP/OnLine Server where INTERACT is intended to be used in ITP Models that will be run by ITP/Workstation. This means that some features, like BEGINGROUP – ENDGROUP that are only described here, will have no effect in ITP/Workstation. Other features only described here will generate an error when running the ITP Model with ITP/Workstation.

The way the questions in a form and constructs like BEGINGROUP…ENDGROUP are shown to the user is determined by the ITP/OnLine Server application. This application can be adapted to one's own wishes. The application can for example be adapted to reflect the corporate style. Refer to the ITP/OnLine Server Help for more information on adapting the look and feel of the forms.

This help text describes the different keywords of the FORM statement.

Adding a FORM

Add the following instruction to the ITP Model to start a form:

FORM "Form title"
    GLOBAL_STATE

The title of the form is of type TEXT. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the title text to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>". Also note that using incorrect HTML tags may result in damaged layout.

A FORM contains at least one QUESTION or Text Block.

Handling 'unseen' questions

You can use the keyword GLOBAL_STATE to suppress validation and assignment of questions in groups that are not shown, due to the conditions SHOW/SHOWNOT on that group. If this keyword is not present, the setting IgnoreUnseenGroups in the ITP/Server Environment determines whether or not these questions are validated.

Dynamic FORM

Since ITP/MDK Repository 3.2.0 and ITP version 3.2.5 forms can be created with a WYSIWYG Form Editor. These forms are retrieved from the ITP/MDK Repository database at the moment the model is run. That is why these forms are called dynamic forms as opposed to normal forms that are created with the keyword FORM. Refer to Dynamic FORM for more information on this topic.

Adding identification to a FORM

A Form can have an optional identification. The keyword ID allows for assigning identification to a Form, and must occur directly after the keyword FORM. The use of Form IDs also makes the use of Question IDs mandatory.

FORM "Form title"
ID ("string that determines the ID of the Form")

Refer to the ITP/Server Manual chapter Integrating, section Form and Question IDs for more information on IDs.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

Adding a QUESTION to a FORM

Within the FORM statement QUESTIONs can be added. A maximum of 65000 questions and/or Text Blocks is allowed in each FORM.

QUESTION "Question text"
ANSWER variable

The QUESTION text is of type TEXT. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the question text to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>". Also note that using incorrect HTML tags may result in damaged layout.

The answer filled out by the end user is stored in a variable, an ARRAY or an element of an ARRAY. This variable or ARRAY has to be declared in the model document before it can be used in a FORM.

A detailed description of the syntax and options of the QUESTION statement is provided below.

QUESTION

Between the QUESTION and ANSWER keyword the model developer can use several optional elements.

QUESTION "Question text"

  ID ("string that determines the ID of the question")

  LEN (length of the answer)

  DFT ("answer filled out by default")

  DATE

  TIME

  VIEW ("Name of the Text Block View")

  AUTOINSERT

  EDITABLE_TEXTBLOCK

  VALUES (list with possible answers)

  MULTISELECT

  ORDER

  RADIOBUTTONS

  HELPTEXT ("Text shown by ITP/OnLine as help text")

  ERRORCONDITION TRUE|FALSE

  MESSAGE ("This text is shown if ERRORCONDITION yields TRUE")

  HIDECONDITION TRUE|FALSE

  READONLY TRUE|FALSE

  FILE

ANSWER variable, ARRAY or ARRAY element

Between QUESTION…ANSWER the model developer can use the following keywords:

ID ("string, determining the ID")

The keyword ID allows for assigning identification to a question. The identification is used by the keywords SHOW and SHOWNOT to determine the question that shows or hides the group, and in other situations where individual questions need to be identified. The use of the keyword ID is mandatory when form ID is used.

LEN (length of the answer)

The keyword LEN allows the model developer to set a maximum length for an answer. If the answer the end user has to provide is of type TEXT, then the argument to LEN is a number between 1 and 65535 for ITP/OnLine Server (between 1 and 255 for ITP/Workstation). The value determines the total amount of positions for the answer. In case the answer is of type NUMBER, the argument to LEN consists of two numbers, the first being the maximum number of digits in the answer, the second being the number of decimals. These two numbers are separated by a space. For example, LEN(7 3) indicates a number with three decimal places and four integral digits. Note that even if the end user does not enter any decimal digits, they are always considered to be present, for example, when LEN(7 3) is specified, the answer "1234" is considered to consist of 7 digits (including the three decimal places). The total number of digits should be between 1 and 15.

For answers of type TEXT, the default maximum length is LEN (125). For answers of type NUMBER, the default maximum length is LEN (15 3).

LEN is ignored if the keyword DATE or TIME is used.

DFT (default answer)

The keyword DFT allows for providing a default answer to a question. This default answer needs to be of the same TYPE as the variable, ARRAY or ARRAY element in which the answer to the question is stored. The default answer provided is displayed when the form is loaded. The default answer must be a valid answer to the question, and must therefore appear in the list with possible answers when the keyword VALUES is used.

DFT should be an ARRAY if the keyword VALUES or VIEW has been used to provide possible answers (or Text Blocks) and the keyword MULTISELECT has been used to indicate that the end user can select more than one answer (or Text Block) from the list. For a EDITABLE_TEXTBLOCK question, the DFT should be either a reference to a ITP/MDK Repository Text Block, or a Text Block reference that was returned by an earlier EDITABLE_TEXTBLOCK question or by a call to the function import_text_block.

DATE

When the keyword DATE is specified, the end user is asked to select a date. The values that are passed to DFT, VALUES and ANSWER are treated as date values. This means that they are of type NUMBER, and that they contain eight digits which are interpreted using ITP's default date format YYYYMMDD. The keyword DATE also changes the way the question is displayed. In the ITP/OnLine example implementation, the end user can select a date from a pop-up calendar.

TIME  

When the keyword TIME is specified, the end user is asked to select a time. The values that are passed to DFT, VALUES and ANSWER are treated as time values. This means that they are of type NUMBER, and that they contain four digits which are interpreted using ITP's default time format HHMM.

VIEW ("Name of the text block view")

Use the keyword VIEW to indicate that the end user should select a Text Block from a Text Block View in the ITP/MDK Repository. The answer to the question will be a TEXT value containing a reference to the text block that the end user selected. Combining the VIEW keyword with the MULTISELECT keyword allows the end user to select more than one Text Block.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

Refer to Text Blocks for more information on using Text Blocks.

AUTOINSERT

Use the keyword AUTOINSERT in combination with the VIEW keyword to automatically insert the Text Blocks, to be selected by the end user, in the result document. If the end user selects multiple Text Blocks, these are inserted separated by paragraph breaks. This behavior can be influenced by the AutoInsertSeparator and AutoInsertTerminator pragma functions. Refer to pragma for more information.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

EDITABLE_TEXTBLOCK

Use the keyword EDITABLE_TEXTBLOCK to indicate that the end user is asked to edit text content with layout. Using an EDITABLE_TEXTBLOCK question, end users can be asked to edit existing text blocks, or to enter entirely new text content with layout.

TEXT newtext_reference

FORM "Enter text"
  QUESTION "Enter new text content"
    EDITABLE_TEXTBLOCK
    ANSWER newtext_reference

(* You can use an EDITABLE_TEXTBLOCK to insert the edited text into the result document *)
TEXTBLOCK
VAR newtext_reference

When the keyword EDITABLE_TEXTBLOCK is specified, the value that is passed to DFT should be a reference to a Text Block in the ITP/MDK Repository. It is also allowed to specify the answer to an earlier EDITABLE_TEXTBLOCK question within the same model run. In addition, it is possible to specify a value returned by the function import_text_block.

TEXT edited_textblock1
TEXT edited_textblock2

FORM "Change text"
(* On this Form the question: "Edit the text content", allows you to edit the content of textblock1. The edited textblock is accessible through the variable editted_textblock1. The content of textblock1 stored in the ITP/MDK Repository is not changed. *)

  QUESTION "Edit the text content"
    EDITABLE_TEXTBLOCK
    DFT "textblock1"
  ANSWER edited_textblock1

FORM "Check earlier entered text"
(* A edited Text Block can be used as a default for another TEXTBLOCK question *)

  QUESTION "Check the text"
    EDITABLE_TEXTBLOCK
    DFT edited_textblock1
  ANSWER edited_textblock2

(* You can used an EDITABLE_TEXTBLOCK to insert the edited text into the result document. *)
TEXTBLOCK
VAR edited_textblock1

TEXTBLOCK
VAR edited_textblock2

The answer to an Editable_TEXTBLOCK question is a value of type TEXT. This value contains a reference to the Text Block content entered by the end user in an unspecified format that is recognized by a selected set of commands. To insert the user-provided content into the document the reference can be used with the model language statement TEXTBLOCK. It can also be used as the DFT value of a subsequent EDITABLE_TEXTBLOCK form question. The answer is only usable during the same ITP Model run; it cannot be stored. For information on how to store the user-entered content of EDITABLE_TEXTBLOCK questions, refer to the function import_text_block.

Refer to Text Blocks for more information on using Text Blocks.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/OnLine or ITP/OnLine Server.

VALUES (list with possible answers)

The keyword VALUES can be used to create a list with possible answers. The end user can select one of these values from a list to answer the question. Combining the keyword VALUES with the keyword MULTISELECT allows the end user to select more than one answer from the list.

A semicolon (";") is used to separate items in the list. The items can be of type TEXT or type NUMBER, depending on the type variable the answer is stored in.

TEXT answer_day
FORM "Select the answer"
QUESTION "Select a day"
VALUES ("Monday"; "Tuesday"; "Wednesday"; "Thursday"; "Friday"; "Saturday"; "Sunday")
ANSWER answer_day

It is also possible to pass an ARRAY with possible answers.

MULTISELECT

This keyword is only used in combination with the keyword VALUES, or VIEW. Adding this keyword allows the end user to select more than one answer or Text Block from a VALUES list or more than one Text Block from a VIEW. To store multiple answers, an ARRAY has to be declared to save the answer to.

MULTISELECT cannot be used in combination with RADIOBUTTONS.

ORDER

The keyword ORDER can only be used in combination with MULTISELECT.

When the keyword ORDER is defined, the end user is not only allowed to select more than one answer or Text Block from the VALUES list or the VIEW, but can also put this selection in the desired order.

RADIOBUTTONS

This keyword is only used in combination with the keyword VALUES. It shows the possible answers in a radio button list.

RADIOBUTTONS cannot be used in combination with MULTISELECT.

HELPTEXT ("This text will be shown as the helptext")

Additional (help) text. HELPTEXT can be used to add help text to a question. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the help text to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>" Also note that using incorrect HTML tags may result in damaged layout.

The current ITP/OnLine Server sample implementation shows a question mark when HELPTEXT is defined. When the mouse moves over this question mark, the help text shows up. The current ITP/OnLine Server sample implementation will not show the question mark when the HELPTEXT has been defined within a BEGINTABLE…ENDTABLE construct.

ERRORCONDITION TRUE|FALSE

ERRORCONDITION allows the model developer to check the answer the end user provides and to show a message. ERRORCONDITION is followed by a value type BOOL. This value is calculated when the end user leaves the form using the button OK, or ENTER. If the value is TRUE, the message specified using the keyword MESSAGE is shown, and the end user has to change the answer to the question before proceeding with the form.

MESSAGE ("The message that is shown when ERRORCONDITION is TRUE")

When ERRORCONDITION is TRUE, the MESSAGE text will be shown to the end user. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the message text to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>" Also note that using incorrect HTML tags may result in damaged lay out.

HIDECONDITION TRUE|FALSE

HIDECONDITION is followed by a value type BOOL. This value determines if a question is visible or not. The value of the BOOL is calculated when the form is loaded. If the value yields TRUE the question will not be shown. In that case, the DFT value will be stored in the variable or ARRAY element in which the answer is stored. If no DFT answer has been provided the variable or ARRAY element will be assigned an empty value (in case of a TEXT), zero (in case of a NUMBER) or FALSE (in case of a BOOL).

By default a question is shown.

READONLY TRUE|FALSE

READONLY is followed by a value type BOOL. This value determines if a question is read-only or not. The value of the BOOL is calculated when the form is loaded.

By default a question is editable.

FILE

This keyword allows the end user to select a file with a file selection window. The variable or ARRAY element in which the answer to the question is stored must be type TEXT.

Adding a TEXTBLOCK to a FORM

Besides questions, a FORM can contain one or more sections of static text content. This can be used for messages or additional help text.

TEXTBLOCK "Static text content"

The type of the text content is TEXT. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the static text content to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>". Also note that using incorrect HTML tags may result in damaged layout.

Example

TEXT answer1
FORM "Example form"
  TEXTBLOCK "Please fill out the following question"
  QUESTION "This is the question"
  ANSWER answer1

Note

Static text content is specified using the keyword TEXTBLOCK, but this feature is not connected to the Text Blocks feature provided by the ITP/MDK Repository. The keyword TEXTBLOCK predates the Text Blocks feature, and keeps its name for compatibility reasons. For more information on using the Text Blocks feature, refer to Text Blocks, and refer to the VIEW and EDITABLE_TEXTBLOCK features described below.

Available Field Sets

When a default Text Block has been set, the user can enter Fields from a list with available Field Sets during a model run. These are the same Field Sets that are available when the Text Block is edited in the ITP/MDK Repository.
When no default Text Block has been set, no Field Sets are available. If you wish to have Field Sets available for an empty Text Block, create an empty Text Block in the ITP/MDK Repository and use this as default.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

VALUES (list with possible answers)

The keyword VALUES can be used to create a list with possible answers. The end user can select one of these values from a list to answer the question. Combining the VALUES keyword with the MULTISELECT keyword allows the end user to select more than one answer from the list.

A semicolon (";") is used to separate items in the list. The items can be type TEXT of type NUMBER, depending on the type variable the answer is stored in.

TEXT answer_day
FORM "Select the answer"
QUESTION "Select a day"
VALUES ("Monday"; "Tuesday"; "Wednesday"; "Thursday"; "Friday"; "Saturday"; "Sunday")
ANSWER answer_day

It's also possible to pass an ARRAY with possible answers.

MULTISELECT

This keyword is only used in combination with the VALUES or the VIEW keyword. Adding this keyword allows the end user to select more than one answer or Text Block from a VALUES list or more than one Text Block from a VIEW. To store multiple answers, an ARRAY has to be declared to save the answer to.

MULTISELECT cannot be used in combination with RADIOBUTTONS.

ORDER

The keyword ORDER can only be used in combination with MULTISELECT.

When the keyword ORDER is defined, the end user is not only allowed to select more than one answer or Text Block from the VALUES list or the VIEW, but can also put this selection in the desired order.

RADIOBUTTONS

This keyword is only used in combination with the keyword VALUES. It shows the possible answers in a radio button list.

RADIOBUTTONS cannot be used in combination with MULTISELECT.

HELPTEXT ("This text will be shown as the helptext")

Additional (help) text. HELPTEXT can be used to add help text to a question. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the help text to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>" Also note that using incorrect HTML tags may result in damaged layout.

The current ITP/OnLine Server sample implementation shows a question mark when HELPTEXT is defined. When the mouse moves over this question mark, the help text shows up. The current ITP/OnLine Server sample implementation will not show the question mark when the HELPTEXT has been defined within a BEGINTABLE…ENDTABLE construct.

ERRORCONDITION TRUE|FALSE

ERRORCONDITION allows the model developer to check the answer the end user provides and to show a message. ERRORCONDITION is followed by a value type BOOL. This value is calculated when the end user leaves the form using the OK button or the ENTER key. If the value is TRUE, the message specified using the MESSAGE keyword is shown, and the end user has to change the answer to the question before proceeding with the form.

MESSAGE ("The message that is shown when ERRORCONDITION is TRUE")

When ERRORCONDITION is TRUE, the MESSAGE text will be shown to the end user. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the message text to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>" Also note that using incorrect HTML tags may result in damaged lay out.

HIDECONDITION TRUE|FALSE

HIDECONDITION is followed by a value type BOOL. This value determines if a question is visible or not. The value of the BOOL is calculated when the form is loaded. If the value yields TRUE the question will not be shown. In that case, the DFT value will be stored in the variable or ARRAY element in which the answer is stored. If no DFT answer has been provided the variable or ARRAY element will be assigned an empty value (in case of a TEXT), zero (in case of a NUMBER) or FALSE (in case of a BOOL).

By default a question is shown.

READONLY TRUE|FALSE

READONLY is followed by a value type BOOL. This value determines if a question is read-only or not. The value of the BOOL is calculated when the form is loaded.

By default a question is editable.

FILE

The keyword FILE allows the end user to select a file with a file selection window. The variable or ARRAY element in which the answer to the question is stored must be type TEXT.

Grouping FORM content

QUESTIONs and TEXTBLOCKs that belong together can be grouped in groups.

BEGINGROUP "Group title"

  ...

ENDGROUP

The group title is of type TEXT. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the text to be put in bold or to insert a linefeed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>". Also note that using incorrect HTML tags may result in damaged layout.

The content of the group is defined by QUESTIONs and TEXTBLOCKs that are contained between the BEGINGROUP and ENDGROUP instruction. In addition to QUESTIONs and TEXTBLOCKs, groups can contain other groups, and also tables (which are described in the following section). The ITP/OnLine example implementation supports nested groups up to 2 levels.

A detailed description of the syntax and options of the BEGINGROUP...ENDGROUP instruction is provided later on this page.

Example

TEXT answer1
TEXT answer2
TEXT answer3

FORM "This is an example"
  TEXTBLOCK "Answer the following questions"
  

  BEGINGROUP "Group 1"
    QUESTION "This is the first question"
    ANSWER answer1
    QUESTION "This is the second question"
    ANSWER answer2
  ENDGROUP

  QUESTION "This is the third question"
  ANSWER answer3

This example shows a form containing a group with title "Group 1", containing two questions. In addition, the form contains a TEXTBLOCK that is not contained within the group, and a third question that is not included in the group.

Grouping FORM content in a TABLE

The BEGINTABLE…ENDTABLE instruction can be used to show QUESTIONs and TEXTBLOCKs next to each other instead of underneath each other, in a tabular layout.

BEGINTABLE "Table title"

  ...

ENDTABLE

The table is started with the keyword BEGINTABLE, followed by the table title. The table title is of type TEXT. This text may contain HTML instructions that are passed to ITP/OnLine Server. This allows for parts of the table title text to be put in bold or to insert a line feed. Note that the slash character ("/") is the ITP escape character. Therefore a HTML closing tag looks for example like "<//b>". Also note that using incorrect HTML tags may result in damaged layout.

The content of the table is specified by placing one or more BEGINROW…ENDROW instructions between the keywords BEGINTABLE and ENDTABLE:

BEGINROW 

  ...
ENDROW

Each BEGINROW…ENDROW instruction defines a single row in the table. The content of a row is specified by placing QUESTIONs, TEXTBLOCKs, and groups between the keywords BEGINROW and ENDROW. The title text of QUESTIONs is ignored by the table construct. As an alternative, TEXTBLOCKs can be used to define headers for the table columns or rows.

The model developer is responsible for including the same number of elements (QUESTIONs, TEXTBLOCKs and groups) within each BEGINROW…ENDROW instruction.

Example

TEXT answer1
TEXT answer2
TEXT answer3
TEXT answer4
FORM "This is an example of a form"
  BEGINTABLE "An example of a table"
    BEGINROW
       TEXTBLOCK "Question 1"
       TEXTBLOCK "Question 2"
    ENDROW
    BEGINROW
       QUESTION ""
       ANSWER answer1
       QUESTION ""
       ANSWER answer2 
    ENDROW
    BEGINROW
       QUESTION ""
       ANSWER answer3
       QUESTION ""
       ANSWER answer4 
    ENDROW
  ENDTABLE

The example will result in a table with three rows and two columns. The first row only contains text and provides for the header of the table.

BEGINGROUP…ENDGROUP

This section provides detailed documentation of the construct BEGINGROUP...ENDGROUP that was introduced earlier. There are several optional elements that can be included between the BEGINGROUP and the ENDGROUP keywords:

BEGINGROUP "Group title"
  EXPANDABLE
  EXPANDED TRUE|FALSE
  HIDECONDITION TRUE|FALSE
  SHOW condition
  SHOWNOT condition
  QUESTION "The text of the question"
  ANSWER variable, ARRAY or ARRAY element
  TEXTBLOCK "Static text content"

  BEGINGROUP "Nested group title" ... ENDGROUP

  BEGINTABLE "Nested table title" ... ENDTABLE
ENDGROUP

The following keywords can be used following the keyword BEGINGROUP.

EXPANDABLE

EXPANDABLE makes it possible to show or hide a group. The ITP/OnLine Server example implementation will add a + sign in front of the group with which the group can be expanded or collapsed.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

Note

EXPANDABLE cannot be used in combination with SHOW or SHOWNOT within a single group.

EXPANDED TRUE|FALSE

The keyword EXPANDED is followed by a value type BOOL. This value decides whether a group is expanded or collapsed. The value is calculated once, when the ITP/OnLine Server questions screen is loaded. By default, a group is expanded.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

HIDECONDITION TRUE|FALSE

The keyword HIDECONDITION is followed by a value type BOOL. This value decides whether a group is visible for the end user or not. The value is calculated once, when the ITP/OnLine Server questions screen is loaded. If the value yields TRUE the group will not be shown. In that case, all questions in the group will be assigned the DFT value. If no DFT answer has been provided for a question the variable or ARRAY element will be assigned an empty value (in case of a TEXT), zero (in case of a NUMBER) or FALSE (in case of a BOOL).
By default, a group is visible.

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

The keyword SHOW can be used to show a group dynamically, depending on the answer given to a question that precedes the group. Conversely, the keyword SHOWNOT can be used to hide a group dynamically. The question needs to have an ID which the keywords SHOW or SHOWNOT can refer to. When using the keyword SHOW, the group is shown when the value of the question which has ID "id of the question" satisfies the condition. This will immediately affect the form in which the end user fills out the questions. When the group is currently visible, and the end user changes the answer back to something which does not satisfy the condition, the group will be hidden. When using the keyword SHOWNOT, the behavior is exactly reversed; the group is hidden when the question's answer satisfies the condition, and shown when it does not.

SHOW ID("id of the question")
SHOW ID("id of the question") = value
SHOW ID("id of the question") </<=/>=/> value
SHOW ID("id of the question") CONTAINS value
SHOW ID("id of the question") IN value

SHOWNOT ID("id of the question")
SHOWNOT ID("id of the question") = value
SHOWNOT ID("id of the question") </<=/>=/> value
SHOWNOT ID("id of the question") CONTAINS value
SHOWNOT ID("id of the question") IN value

SHOW and SHOWNOT cannot be used together in the same group.

The following expressions are currently supported:

• ID("id")
  Requires that the question with ID("id") is a BOOL question. The group will be shown if the answer to the question is TRUE.
• ID("id") = value
  Requires that the question with ID("id") is either a TEXT or NUMBER question. The group will be shown if the answer to the question is equal to the value.
• ID("id") </<=/>=/> value
  Requires that the question with ID("id") is a NUMBER question. The group will be shown if the answer to the question is respectively smaller (<), smaller or equal (<=), greater or equal (>=), or greater (>) than the specified value.
• ID("id") CONTAINS value
  Requires that the question with ID("id") is a MULTISELECT TEXT question. The group will be shown if the answer to the question contains the value of one of the selected items.
• ID("id") IN value
  Requires that the question with ID("id") is a TEXT question and the value must be an ARRAY TEXT variable. The group will be shown if the answer to the question is present in the array.

The same expressions are supported for the keyword SHOWNOT, but the groups are hidden instead of shown when the condition is met.

The keywords DATE and TIME are supported on NUMBER answers when performing a test.

The result of an expression can be negated using the NOT operation.

SHOW NOT ID("id of the question") = "test"

Multiple expressions can be combined using the logical AND and OR operations. The result of an expression can be negated using the NOT operation. Expressions should be enclosed in brackets to disambiguate the use of the AND and OR, because these can also occur as part of the value component.

Example

SHOW ( (ID("id question 1") = 4) AND NOT (ID("id question 2") = "test") ) OR (ID("id question 1") = 42)

Note

ITP Models using this feature can be created with ITP/Workstation, but to run a model containing this feature, you will need ITP/Server or ITP/OnLine Server.

Note

The ID cannot reference questions which specify the keywords EDITABLE_TEXTBLOCK or VIEW. Furthermore, SHOW and SHOWNOT cannot be used in a group which is also marked EXPANDABLE.

Note

It is currently not allowed to use a CONTAINS test on an ordered MULTISELECT question, i.e., a question that has both the keywords MULTISELECT and ORDER.

Adding a button to a form

From ITP version 3.2.9 it is possible to add a self-defined button to a form using the BUTTON statement. With the ON BUTTON statement the model developer can act on the button if it is clicked, for example to pass a value to the ITP/Server script using the function itpserver_parameter.

BUTTON "Name of the button"
ID ("id of the button")
ON BUTTON ID("id of the button") 
DO
  BOOL dummy := itpserver_parameter("key"; "value")
OD

The model part between the ON BUTTON ID("id of the button") DO and the OD is executed when the button is clicked. In this example a value is passed to the ITP/Server script.

Note the following conditions:

• Buttons are declared at the FORM level. Buttons cannot be used within nested form statements (groups, tables).
• Button IDs are case sensitive.
• In ITP/OnLine, user-defined buttons are always presented after the ITP-defined buttons (OK, Back, Cancel).

Closing a FORM

A FORM can be closed by two buttons, OK and CANCEL. It is possible to specify actions which should be taken when the FORM is closed using the OK button or when the FORM is closed using the CANCEL button.

Note

The CANCEL button will only be shown in an ITP/OnLine FORM if an ON EXIT DO..OD part has been defined.

Closing the FORM with the OK button

When an end user has completed the FORM and presses the Enter key or the OK button the answers present on the FORM will be stored in corresponding ANSWER variables or array elements.

If an ON ENTER is specified the actions between its DO and OD will be executed after the OK button is pressed.

ON ENTER
DO
 Part of the model that will be executed when the FORM is closed using the OK button
OD

When no ON ENTER line is specified, ITP will continue executing the model code that follows the FORM statement.

Ending filling out the FORM with the CANCEL button

When the FORM has an ON EXIT DO…OD construct, the sample ITP/OnLine Server implementation will show a Cancel button. When an end user closes the FORM by pressing this Cancel button, the answers present on the FORM will not be stored. This means that the values stored in the variables will still be the values that were stored in them prior to execution of the FORM statement. The actions specified between the DO and OD of the ON EXIT DO…OD will be executed.

ON EXIT
DO
 Part of the model that will be executed when the FORM is closed using the Cancel button
OD

When no ON EXIT line is specified, ITP will continue executing the model code that follows the FORM statement.

Default answers and validation

All Forms created in an ITP Model or as (Q)FORM in the ITP/Model Development Kit are subject to validity checks. Value lists and lengths are enforced whenever possible.

The validation uses the following generic guidelines:

• Any default values that violate constraints are presented to the end user and this end user has to provide a valid answer. It is left to the application, either ITP/OnLine Server or an integrating application, to present these values as initial values to the end user.
• Any question that presents a list of choices to the end user must have valid defaults from that list. ITP/Server will automatically update the defaults as described below.
• Any questions, which are hidden or read-only cannot be changed by the end user. These are not validated because the user cannot correct any errors.

Length attributes are only enforced on user-entered content. Answers from a choice list are excluded from validation.

Dates and times are only validated on user-entered content. Invalid answers which are selected from a choice list, such as selecting the 29th february in a non leap-year, are still accepted.

Questions which are unconditionally hidden or, which are in a group that is unconditionally hidden are not validated.
Questions in a group that are conditionally hidden based on other questions are validated. If the answer is invalid the question is shown to the end user for correction. You can disable this validation with the keyword GROUP_STATE on the statement FORM, or through the global setting IgnoreUnseenGroups in the ITP/Server Environment.

All choice lists must have a valid default, even if the questions are read-only or hidden. If the default in a single-select list is invalid, ITP/Server will select the first entry from the list. If the default in a multi-select list is invalid, ITP/Server will strip all invalid items from the list. This change provides consistent behavior for read-only questions that are visible to the end user but cannot be changed.

Note

You can configure ITP/Server at the level Environments to disable answer validation.