Introduction

Templates for dotData questionnaires are a form of regular HTML intermixed with certain tags that tell the template where to insert the questions.

This section describes the structure, requirements and possibilities of the templating system.

Encoding

Templates should always be utf-8 encoded, both the encoding of the file itself when you upload it (check your text editor!) and the encoding of the HTML within:

<!doctype html>
<html>
<head>
        <meta charset="utf-8" />
        <meta name="robots" content="noindex">
        <meta http-equiv="expires" content="tue, 01 jan 1980 1:00:00 GMT" />
        <meta http-equiv="pragma" content="no-cache" />
        <title>[# __title__ #]</title>
</head>
<body>
        <form action="/dotdata/submit?sessionID=[# __sessionid__ #]" method="post" name="datainput">
                [# __content__ #]
        </form>
</body>
</html>

The form element is required and it needs to have the name ‘datainput’. The __content__ element inserts the actual instructions or question(s) into your html output.

Available tags

The templating engine can contain elaborate logic but for simple setups, a few commonly used variables are made available as a shortcut:

__backallowed__

This variable indicates if the screen can contain a ‘back’ button. This is not the case in three scenario’s:

  1. for the first page of the questionnaire

  2. for the first page of a ‘section’ (this is a setting in your items setup)

  3. when in the questionnaire settings the ‘back’ button is set to ‘off’

<input type="button" style="display: [# iif(__backallowed__, '', 'none') #]" value="Back" onclick="SubmitWhenPageOK('back')">
__content__

This tag includes the actual question or item specific content that is generated by dotData.

<div id="questioncontent">
[# __content__ #]
</div>
__htmldir__

Should you need to support languages like arabic or hebrew, that go right-to-left, you can include the tag below into your template. It will add DIR=RTL to the html definition section of your template for the appropriate languages only.

<!doctype html>
<html[# __htmldir__ #]>
__languageid__

In case you want language-specific logic in your questionnaire, this variable contains the ID of the used language for the current respondent. This is a numeric value corresponding the language code used in the URL that the respondent used to access their questionnaire. When the respondent is a panel member, __languageid__ will reflect their language. When there is no ‘l=’ parameter in the URL and the respondent is not a panel member, the __languageid__ variable will be the default language id for the questionnaire.

__lastpage__

This variable will become true when there is no further page. With this variable you can direct the difference between the text ‘Next’ and ‘End’ in a button.

<div id="questioncontent">
[# iif(__lastpage__, 'End', 'Next') #]
</div>
__progress__

The current progress indicator of the respondent in percentage.

See also Progress bar

__sessionid__

This variable contains the sessionid of the current respondent. You will probably not need to access this id for any other logic than described in the example above.

__showprogress__

This variable is True when the user set the progress bar to ‘visible’ in the settings of the questionnaire.

See also Progress bar

__title__

The title you give to your questionnaire on the setup page. Usage of this tag is not mandatory. The value defaults to the empty string. You can choose to hardcode the title into the template instead if it’s invariable, for instance you can use your company name.

__worstcasescreencount__

This variable contains the calculated max number of screens the respondent will have to go through. This is not the same as the number of items or questions in your questionnaire. This number contains corrections for repetitions, questions that are on one page, questions that are set to be invisible unconditionally (such as punch items or test items) and logical items.

This variable can be used to calculate a progress bar

See also Progress bar

__screensshown__

This variable contains the number of screens the respondent saw.

This variable can be used to calculate a progress bar

See also Progress bar

__skippedscreens__

This variable contains the number of screens the respondend skipped due to conditional display of items or due to routing logic.

This variable can be used to calculate a progress bar

See also Progress bar

__templatehome__

This variable expands to a path where the template lives. When you place images, css or javascript files in a separate template repository, this variable is used to map the files regardless of the folder you put the template in.

Example:

<script type="text/javascript" src="[# __templatehome__ #]/js/theScript.js"></script>

Varying elements

At times you might want to vary elements of your templates without wanting to create a completely new element. For instance you might want a per- questionnaire title, or a per-endclient logo. To facilitate this, dotData has the ability to define dynamic elements in your templates as such:

[# CustomHTML('TheLogo') #]

This enables you to create your own dynamic elements. In the above example, it assumes you created within your questionnaire an element and you named it ‘TheLogo’.

Defining these elements is done in your project settings, under section ‘Layout template’. Elements are saved in xml format. When you click ‘builder’, you can edit the tags in a more handy format without knowledge of XML.

When an element is not defined in your project, the result will just insert an empty string, so nothing, at that location in your template.

Note

CustomHTML tags are strings that can have a limited length only. This mechanism is not meant to include huge blocks of texts or html.

Progress bar

Displaying a progess bar in a questionnaire can actually be quite cumbersome because it is not always clear with path the respondent will take through the routing of the questionnaire. Furthermore the respondent may skip significant parts of the questionnaire because of questions that are displayed conditionally.

When the ‘last page’ state is reached, the value of __progress__ will always be 100. The value of __progress__ always has a minimum of 1 even when there are so many items in your questionnaire it would round up to 0.

<script>
progress = [# __progress__ #]
...

Alternatively, if you want to manipulate the progress, you can calculate it in JavaScript:

<script>
progress = parseInt([# (min((__screensshown__ + __skippedscreens__) / __worstcasescreencount__, 1) * 100) #];
...