Custom Screens (HTML)
INCLUDE Function and Toolbox Instructions

When the ability to use HTML in a question's labels (long label, short label etc.) is not enough, you can fully customize the display of one or more questions (and their choices) by  "including" an HTML file in a Text type screen - in the text edit window of its Screen Options. This functionality is enabled through a mini-toolbox of commands which can be inserted in the HTML code to refer to questions and their attributes.

Note: A custom HTML screen is by nature static, hence certain dynamic features cannot be supported, such as: skips, rotations etc.

To add a custom screen using HTML:

  1. Add a Text type screen in the Screens tab. The screen may include several questions or even just only one if necessary (see Creating a Text type  screen)

  2. Click on the Screen Options button.

  3. In the Text edit window, type the INCLUDE command referencing the HTML file containing the code defining the custom screen.

Example: [INCLUDE QL.HTM]

Note: The complete path to the HTM file on the server can be specified. This is only necessary, however, if the file is not in the same location as the questionnaire.  

To create an INCLUDE file

You can create an INCLUDE file of any question or screen while it is being displayed in the Preview window i.e. when Testing the questionnaire, or accessing the screen in the Screens tab . The File>Save As command will save the screen's HTML (together with its INCLUDE instructions) under the file name that you specify. Later, you can use any HTML editor to customize the HTML.

Warning: When customizing the HTML, the INPUT TYPE containing the QUESTLIST command must not be removed since it is essential for capturing the data. It is most important to test the questionnaire in 'live' mode to ensure that all the data is being written to the database.

Example: <INPUT TYPE=HIDDEN NAME=QUESTLIST VALUE= "Q1;Q2;Q3">

Note: HTML (INCLUDE) files must be Published (uploaded) to the questionnaire in the Command Center. This is normally done using the Questionnaire Manager.

INCLUDE Function

The INCLUDE function can also be used to add other elements in the project such as a Progress Bar, a Header and/or a Footer.

QuestionText Function

Note: Quotation marks are required if the value of the parameter contains a comma or parenthesis.

Important note: To specify the recall of another question in the INCLUDE page the question referenced must be enclosed in square brackets [].

Syntax:

_$QuestionText  (QUESTION= “ALIAS[+ n]“, SECTION=”LLABEL| SLABEL|MSG|CHOICE:CODE[+n]”, LANG= “Language”)

The sub-functions below are shortcuts to _$QuestionText :

Examples:

Heading Reference

_$QuestionText(QUESTION= “NAME”, SECTION=”LLABEL”)

Sub-heading Reference

_$QuestionText(QUESTION=”NAME”, SECTION=”SLABEL”)

Message Reference

_$QuestionText(QUESTION=”NAME”, SECTION=”MSG”)

Choice Reference

_$QuestionText(QUESTION=”NAME”, SECTION=”CHOICE :01”)

Reference related to a Question

_$QuestionText(QUESTION=“NAME+2”, SECTION=”LLABEL”)

Reference related to a Choice

_$QuestionText(QUESTION=”NAME” ,SECTION=”CHOICE:01+1”)

Reference forcing a Language

_$QuestionText(QUESTION=”NAME”, SECTION=”LLABEL”, LANG=”en“)

Parameter

Description

QUESTION=

Specifies the question from which the text will be extracted. The current question will be used if this parameter is omitted. To obtain a relative reference, you merely need to increment (+) the reference by the desired value. Thus, if Q1 is the 3rd question and we reference Q1+1, then we will reference the 4th question.

SECTION=

Specifies a location within the question being referenced. The Heading text will be returned if this parameter is omitted.

  •  LLABEL : This instruction extracts text from the Long Label.

  •  SLABEL : This instruction extracts text from the Short Label.

  •  MSG : This instruction extracts text from the Message.

  •  CHOICE:n[+n] : This instruction extracts choice labels. To obtain a relative reference, you merely need to increment (+) the reference by the desired value. Thus, if RE is the 3rd choice and we reference RE+1, then we will reference the 4th choice.

LANG=

This parameter displays referenced text in a specific language. The default interview language will be used if this parameter is omitted.

ProjectHeader Function

This function repeats a project's Header.

Syntax: _$ProjectHeader()

ProjectFooter Function

This function repeats a project's Footer.

Syntax: _$ProjectFooter()

ProgressBar Function

This function is used to recall a project's Progress Bar (as long as it's visible).

Syntax: _$ProgressBar(ORIENTATION=H|HORIZONTAL|V|VERTICAL)

Examples:

Parameter

Description

ORIENTATION=

Sets the project's Progress Bar orientation. A vertical bar usually lies within the left or right section of a page whereas a horizontal bar is displayed at the top or bottom.

ChoicesList Function

This function is used to display a question's multiple choices in <SELECT> HTML form.

Syntax: _$ChoicesList(QUESTION=”NAME”, LANG=”en“)

Examples:

Parameter

Description

QUESTION=

This parameter specifies the question from which multiple choices are extracted. The current question will be used if this parameter is omitted. To obtain a relative reference, you merely need to increment (+) the reference by the desired value. Thus, if Q1 is the 3rd question and we reference Q1+1, then we will reference the 4th question.

LANG=

This parameter is used to display referenced choices in a specific language. The survey's default language will be used if this parameter is omitted.

Toolbox Instructions for HTML

Element

Explanation

Questions to be included

The QUESTLIST command defines which questions are to be included in the screen. It requires a list of question aliases separated by semicolons.

Example: <INPUT TYPE=HIDDEN NAME=QUESTLIST VALUE= "Q1;Q2;Q3">

Single Response Questions

Radio button

Each radio button (each choice) uses this instruction which requires identification of the code and alias of the question:

<INPUT TYPE=RADIO NAME=alias VALUE=code %alias:code%>

The coding, %alias:code% ensures that the respondent's answer remains on the screen.

Example: <INPUT TYPE=RADIO NAME=Q1 VALUE=1 %Q1:1%>

Drop-down box

For each choice in the drop-down (SELECT) box use this instruction which requires the alias, the code of the question, and the label to the code:

<SELECT NAME=alias><OPTION VALUE=code %alias:code%>label</SELECT>

Example: <SELECT NAME=Q1><OPTION VALUE=1 %Q1:1%>Choice 1
</SELECT>

Text field

For each question requiring a text field:

<INPUT NAME=alias VALUE=%Q1%>

Example: <INPUT NAME=Q1 VALUE=%Q1%>

Open-ended response

For each open-ended choice, immediately after the INPUT command for the choice:

<TEXTAREA ROWS="n. rows" COLS="n. cols" NAME="alias:O">%alias:O%</TEXTAREA>

Example:

<TEXTAREA rows="5" cols="70" name="Q19:O">%Q19:O%</TEXTAREA>

Multiple Response Questions

Check box

Each check box (each choice) uses this instruction which requires the code and alias of the question:

<INPUT TYPE=CHECKBOX NAME=alias:code VALUE=code %alias:code%>

Example: <INPUT TYPE=CHECKBOX NAME=Q1:1 VALUE=1 %Q1:1%>

Drop-down box

For each choice in the drop-down (SELECT) box use this instruction which requires the code and the alias of the question, and the label to the code:

<SELECT NAME=alias MULTIPLE><OPTION VALUE=code %alias:code%>label</SELECT>

Example: <SELECT NAME=Q1 MULTIPLE><OPTION VALUE=1 %Q1:1%>Choice 1
</SELECT>

Note: To display a question's validation errors, you must include the %alias:ERROR% variable where you wish the errors to appear.