Language features and tools

Simplified item declaration
IdCode is a declarative language, characterized by a natural syntax, with minimal use of explicit delimiters and identifiers.

This means that you don’t need to place any identifying tags to declare a question or its answers. You simply write the code and text.
IdCode recognizes the code and text of the question and answer choices based on the context and the presence of an empty line. Let’s take a closer look:

• When declaring a page you must write /page followed by the desired code, for example, /page P1. You may optionally add text in the line below the code that will be displayed as the page header.
• To declare a question, you must leave one empty line and then write the code. Being inside a page, IdCode recognizes the code as a question declaration. In the line below you can add the text of the page.
• To declare the list of answer choices, you must leave one empty line and then write the code and text for each answer choice. Being within a question, IdCode recognizes the codes as answer choices for the question.
• To declare another question, you must leave an empty line and continue as described above.

Other questionnaire items, such as groups and sections, must be declared with start and end identifiers, as we will see in the dedicated paragraphs of this guide.

Colors
Each object declared in IdCode is identified with colors for easier consultation and allowing the user to verify in real-time that the code or the text is correctly interpreted.
For example, the question code is purple. If while typing this code appears in black, it may mean that the previous line is not empty or that the page has not been previously declared.
Properties, options, and constraints are also characterized by specific colors. All question, answer, or header texts are always represented in black.

In the screenshots of this article, you can see the different colors used by IdCode to identify objects, parameters, display conditions, and more.

Codes
The codes for the questions, answers, and any other items on the questionnaire:

• Can contain standard characters, numbers, period, and underscores
• Can contain lowercase or uppercase letters
• Must be unique (no two objects can have the same code)

 
It is important to note that:

• The uniqueness of the codes in the answer choices refers only to the options of the same question. A question cannot contain multiple answer choices with the same code.
• Both lower and upper case letters are accepted in the codes, however, IdCode is not case sensitive. This means that to call the question Qb14 in a display condition or a skip you can write QB14, qb14, or qB14 indistinctly.

 
Inheritance and automatic optimization
Most properties can be added indistinctly to the answer choices or the question.
Answer choices with no property inherit the property specified in the question.

Adding the same property to all answer choices in a question is therefore equivalent to adding the property only on the question.

One of the peculiarities of IdCode is that it re-processes the properties and parameters of the script in its most concise form. If, for example, the property ->M (multiple choice answer) is added in all the answer options of a question, IdCode optimizes the script by placing the property only on the question. This processing occurs automatically each time the IdCode window is closed and reopened.

Intellisense
Intellisense is a tool that facilitates the writing of logical conditions and text piping in IdCode. As you type, you can open Intellisense to retrieve the exact code of a question, the name of a function, or a contact field.

To launch Intellisense, simply press Ctrl + spacebar anywhere in IdCode.
Depending on the context, a list of suggestions is shown.
To narrow down the results, you can type in part of the text of a question, part of a function, or part of the name of a contact field.
If you select one of the suggestions, Intellisense will complete the typing with the question code, function, or field name.

To select one of the suggestions, you can use the keyboard (arrow keys and enter to confirm) or click it with the mouse.

For example, if you don’t remember the code of a question you want to add to a display condition, simply:

1. Open Intellisense.
2. Type a portion of the question text to narrow down the results.
3. Select the suggested question from the list.

For more information, please consult the related article.

Tools
At the top of the IdCode window are the search, find and replace buttons, and full screen view tools.

For more information, please consult the related article.

Preliminary notes

In IdSurvey, the questionnaire is divided into pages. Each page can contain one or more questions.
In the interview process, the system analyzes any instructions on the page after clicking on its Next button and then reviews the next page.

The pages are processed in sequential order, i.e. they are shown in the interview phase one after the other, following any display conditions that may exclude one or more pages.
Usually, the order of the pages in IdCode represents the flow of the questionnaire, however, the order of execution can be altered if you use skips or random.

The IdCode of a questionnaire can be intended as the set of all pages in the questionnaire.

From the IdSurvey interface, you can access the IdCode of the entire questionnaire from the tools menu by clicking the “IdCode – Questionnaire Script” item.

Alternatively, you can access the IdCode of the selected page by clicking the IdC icon in the page bar.
For easier management of the code, we recommended working on the IdCode of the single page and to use the general one only if strictly necessary.

In all the examples of this guide, the IdCode of a page of the questionnaire is shown.

It is important to note that the general IdCode overwrites the entire questionnaire when the “Save” button of the code window is pressed. Otherwise, the changes made in the individual pages, both from the IdCode and from the graphical interface, must be confirmed by pressing the “Save page” button in the interface menu.

Simple question

1. Page declaration and code

   To declare a page write /page followed by the desired code.
2. Question code
   To declare a new question just write the code. The code of the question has to be preceded by an empty line to be recognized.
3. Question text
   In the following line you can add the text of the question. You can also add text formatted in html.
4. Response options (consisting of code and option text)
   To declare the list of answer choices, you must specify a code and text for each of the choices. The list of answer choices must be preceded by an empty line, preceded in turn by the question text or, if absent, the question code to be recognized.
5. Answer’s properties
   Next to each questionnaire object, property can be set. In this example, the open-ended property to the “Other/Specify” option has been specified.
6. Display condition
   Next to each questionnaire item a display condition can be set. In this case, question Q2 will be shown only if the option with code 2 has been selected at question Q1.

Matrix question

To write a matrix question, you must specify the rows and answer choices after typing the code and any text. It is essential not to leave any empty lines between the declarations of rows, columns, options, and any exceptions.

1. To declare the rows, just type /rows and specify the codes and texts of each row below. For proper operation, row codes must always be preceded by a period.
2. To declare answer options, you have to type /cols followed by the list of options.
3. Exceptions
   Usually, the matrix question consists of the same answer choices, parameters, and properties repeated for each row. In IdSurvey you are allowed to specify properties and parameters to an option of a specific row.
To add an exception, you must type /cells followed by the coordinates of the option (row code comma option code) and the desired property and/or parameter. 

In the following example, the question is set as an open-ended answer matrix. In the answer choice of the third row, an exception is set with the parameter as open numeric and constraint from 1900 to 2010.

   

3D Matrix question

3D matrix questions offer an extremely flexible solution for designing complex questions. Each cell (row/column crossing) of the matrix can be considered as an independent question.

The 3D grid can be leveraged to collect different attributes to a set of statements.

For example, if you want to know the rating from 1 to 5 for price, packaging and taste attributes for a series of yogurts, you can set up a 3D matrix with one product for each row, 3 columns for the three attributes, each composed with single-choice options from 1 to 5.

The 3D matrix also allows you to specify different answer types between columns. To the previous example, we can add another column with a numerical open-ended answer to ask how many packages the respondent might purchase for each of the products.

Another example of using the 3D matrix is a question asking for the turnover for each quarter for the last 3 years. The question can be configured by entering the quarters as columns and the years as rows. This allows you to set up a numerical open-ended answer for each cell.

The 3D matrix also allows you to specify exceptions for individual cells, allowing you to configure complex questions for a variety of needs.

To build a 3D matrix question, you must declare the answer choice template, rows and columns after typing the code, and any text. It is essential not to leave any empty lines between the declarations of the templates, rows, columns, and options.

1. To declare an answer option template, you must type /celltemplate followed by an integer and then type the list of options consisting of codes and any text. Unless otherwise specified, all cells will use this cell template.
2. To declare rows, simply type /rows and specify the codes and texts of each row of the application below. For proper operation, row codes must always be preceded by a period.
3. To declare columns, you need to type /cols and specify the codes and texts for each column in the question below. For proper operation, 3D matrix column codes should always be preceded by a period.
4. Create more answer choice templates to apply to specific columns, rows, or cells.
The 3D matrix question can be composed of multiple row, column, or cell types, i.e. with different answer choices. You can specify an unlimited number of answer choice templates to apply to all cells in a row, all cells in a column, or just a single cell.
   1. To add a new type of cell you have to declare a new cell template typing /celltemplate followed by an identification number.
   2. Add the codes and texts of the answer options of the template.
   3. Apply the template to a row or column or to a specific cell.
      1. To apply a template to a row or a column you have to add /celltemplate identification number after the code and any text of the row or column.
         
      2. To apply a template to a specific cell you need to type /cells followed by its coordinates (row code comma column code) and then type /celltemplate identification number.
         
         In this example, the 3D matrix question asks respondents to enter either revenue data from two different industries for two different years. A third row has been provided where the annual total is to be reported automatically. The two cells that report totals are described in two different cell templates, each with an open-ended response, parameter /D (default) and with the algebraic sum of the values entered in the Products and Services rows. In cell template 2, the revenue and services in the 2019 column are summed; in cell template 3, those in the 2020 column are summed.
Finally, templates were assigned to the desired cells, indicating that the cell in the third row of the first column should use cell template 2, while the cell in the third row of the second column should use template 3.

Display conditions

To add a display condition to any questionnaire item, you must type /F “if( condition )” to the right of the object itself.
IdSurvey supports complex and nested conditions and provides special functions for specific uses.

To know the syntax of the conditions consult the dedicated article.

Skip

In the interview, the questions are asked page by page in sequential order. However, it is possible to define skips that will lead to another page or specific question if a particular answer is selected, ignoring the normal flow of the interview.

To add a skip you need to add the /skip parameter “type( CodeItemOfAttainment )” to the answer option.

IdSurvey supports skips to any questionnaire object, such as questions, sections, groups, or pages, as in this example.

There are multiple types of skips: simple skip, skip with sequence, and random skip.You can also add a condition so that the skip is executed if the answer is selected and the condition is true.
Consult the dedicated article to know its characteristics and syntax.

Random

It is possible to activate random in any object of the questionnaire that contains other items. For example, activating random in a question will randomly display its answer choices or activating random in a section will randomly display its pages.

In matrix or 3D matrix questions, you can activate random separately for rows and columns.

Thanks to groups, blocks, and clone random, IdSurvey allows you to create complex sorting schemes for the most diverse needs.

You can find more details in the dedicated article.

To enable random in an item you must type /R 1 to the right of the code.

1. Type /R 1 to the right of the code and attributes.

All answer choices included in the question will be automatically assigned to the “zero” group (/RG 0). The zero group is the default one and is not declared in IdCode.
If you intend to keep the “Other” answer choice for last, you must specify a different random group.

2. Type /RG 1 to the right of the code and attributes.

Nota:
Unless otherwise specified, the random group of elements is /RG 0. All items in group 0 will be randomized one with the other. 
If /RG 1 is specified in one or more answer choices, all options in the same group will be randomized one with the other but after those in group 0.
This feature can then be used to “fix” the position of an answer choice, as in this example.

Group of questions

You can create groups of questions within pages. Question groups can be useful to apply the same display condition to several questions or to randomize the questions contained in it.

To create a group within a page, you must declare the beginning and the end of the group before and after the questions included in it.

1. To declare the beginning of the group type /group followed by the identification code.
2. To declare the end of the group type /endgroup.

Sections

Sections are pages of the questionnaire grouped together. Sections can be useful to apply the same display condition to several pages, to randomize the pages contained in it or to create a loop of a part of the questionnaire.

To create a section you need to use the IdCode of the entire questionnaire. To open it, go to the tools gear menu and select “IdCode – Questionnaire script”.

To create a section you must declare the beginning before any page and the end after the last page that must be included in the section.

1. To declare the beginning of a section you must type /section followed by an identification code.
2. To declare the end of a section you must type /endsection.

Alert message

Alerts allow consistency checks to be placed on any page of the questionnaire.
 


An alert consists of a box with custom text that prevents the respondent from moving to the next page if the answers do not meet the desired criteria.
 


You have to set a display condition for each Custom Alert.
If the condition is true, the alert will be displayed (as with display conditions applied to answers, questions, or pages).

The /soft parameter allows you to display the alert message without preventing the respondent from confirming and continuing to the next page.

1. To declare a new alert you must type /alert
2. To allow the respondent to continue without making corrections, add the parameter /soft 1 in the same line.
3. In the same line you must specify the display conditio.
4. In the bottom line you can enter the desired text.

Descriptive text

You can insert descriptive text anywhere in the questionnaire. Like all other questionnaire text, you can insert images, formatted text, links, and more in HTML format. 

To set up HTML content, it is highly recommended to use the editor available in the GUI.

To enter a descriptive text, you must type /text followed by a code and then type the desired text in the following line.

1. Declare the text block by typing /text followed by the identifier.
2. In the bottom line type the desired text.

You can apply display conditions to descriptive text like all other objects in the questionnaire.

Languages management

IdSurvey allows you to create multilingual surveys using a single questionnaire. To translate the questionnaire, you have to use the “Language Management” tool.

More details can be found in the dedicated article.

The translations loaded with “Language Management” are also visible in IdCode within a tag “<lang>” placed in each text of the questionnaire.

It is possible to make minor corrections and modifications to the translations also from IdCode.

1. Locate the “<lang>” tag of the desired text.
2. Click on the expand icon to show the contents of the tag until the text to be corrected opens.
3. Edit the text

Text piping

In any text, you can retrieve the text of an answer to a previous question, contact data, or interviewer data.

To retrieve the text of a previous answer, write the code in square brackets, for example [Q3].
To retrieve a contact field, write the field name in curly brackets, e.g. {Name}.

Text piping can also be used within display conditions and other IdCode functions.
To know all the details of text piping, refer to the dedicated article.

Dynamic text

IdSurvey allows you to add dynamic text to any questionnaire text.
With dynamic text, you can control the text to be shown based on one or more conditions. This feature is useful for handling singulars and plurals, masculine and feminine, or for adding notes to telephone operators that should not be displayed in CAWI interviews from the same survey.

In addition, the dynamic text allows you to add algebraic expressions so that the result is shown in the text of a question.

To insert dynamic text into the text of a question, answer, or any other questionnaire item, you must:

1. Open the tag typing <dtx> 
2. Write the condition or expression
3. Close the tag writing </dtx>

To learn about the syntax of dynamic text conditions or algebraic expressions, see the relevant articles.

Headers

You can add page headers and group headers.
To do so, simply type text on the line following the page or group declaration.

1. Page header
2. Group header

Flowscript

FlowScript is a language embedded in IdCode that allows you to execute commands with conditions of any complexity, including the else and while statements.

You can add a FlowScript to any page in the questionnaire.
The scripts are executed when the page is saved, i.e. when the respondent clicks the “Next” button.

To give just a few examples, you can use FlowScript to valorize a contact field based on multiple previous answers or for more complex needs such as creating loops of questionnaire sections.

To learn more about FlowScript, consult the detailed guide or look for articles with examples of practical applications.

To add a FlowScript in a page you need to write it inside the <flowscript> tag.

1. Open the <flowscript> tag in the line below the page code or the page header, if present.
2. Type the script.
3. Close the tag by typing </flowscript>.

The script in this example values the Age field with the group corresponding to the age indicated in question Q60.

ClientScript

Client script allows the input of custom Javascript and CSS into questionnaire pages. Javascript allows you to change the behavior of a question, modify its structure, and much more. CSS, on the other hand, allows you to change the styles of the page elements.

ClientScript is processed exclusively by the browser and does not directly influence either the data or the flow of the questionnaire processed by the server.

Javascript and CSS are not discussed in this knowledgebase as they are standard languages and common to any web page. However, there are articles with examples of the most common applications.

To add a Clientscript in a page you have to write it inside the relative tag.

1. Open the <clientscript> tag in the line below the page code or, if present, the page header.
2. Type the script, including the standard <script> or <style> tags.
3. Close the tag by typing </clientscript>.

HTML texts

All texts in the questionnaire (questions, answer choices, headings, etc.) support the HTML standard. You can format the text, insert links, tables, images, or audio-video content.

Although it is possible to insert HTML content from IdCode, it is highly recommended to use the WYSIWYG editors in the graphical interface (What You See Is What You Get), as they allow you to compose and edit the content showing directly the final result, without any need to use HTML code.

Properties List

Properties describe the type of answer or question. If no properties are specified in the question or answer choices, IdSurvey assigns the single-choice option.

Properties must be declared after the answer text or after the answer choice code if text is missing. Question properties or properties that are to be inherited by all answer choices must be declared following the question code.

To declare a property you have to type the symbols -> (minus and major) followed by the initials of the desired property, e.g. ->T to declare an open answer choice.

As described in the section “Inheritance and Automatic Optimization”, a property can also be specified in the top item so that it is inherited by all answer choices in it. For example, by specifying property ->M (multiple-choice option) after the question code, all answer choices contained in it (and in which no other properties have been specified) will be shown as multiple-choice options.

Some properties can be declared only after the question code, such as ->DD (Drag & Drop question). This rule should be applied to all those properties that necessarily affect all the answer options of the question.

Restrictions list

Restrictions allow you to customize the type of value accepted in the open answer.
To specify an open-ended answer with a restriction, you must type ->T /V “restriction“.

Parameters list

Parameters allow the configuration of different functionalities of the questionnaire items.
The following list describes the functionality for each parameter, its syntax, and the items where you can apply it.

To learn more about the functionality of each parameter you can find articles that cover the topic in depth.

To apply a parameter to a page, a section, a group, or a question you have to type it after the code of the object and the eventual property. 
To apply it to an answer option, type it after the property and the text of the answer, if any, or after the code.

Multiple parameters can be added for each object. For example, in an answer option, you can define a display condition and a skip as in the example below.

Configuration options

As mentioned in the properties list, some answer types require configuration parameters.
For example, for a drop-down assisted answer you will need to specify the list of options or associate a text file. Or, for a rating answer, you’ll need to define the type and number of icons (stars, smilies, or likes) and any labels.

To define options, you need to type /O “options” after the property. For example, to set a drop-down answer that takes the list options from a text file, you need to type ->A /O “F,list.txt”.

If you set a property to an answer choice but its configuration options are not specified, IdCode will add a default configuration.

Although it is possible to specify configuration options from IdCode, the syntax may be difficult to manage. Therefore, we highly recommend defining configuration options from the GUI.