How-to: Custom Question Type Editor

You use the Custom Question Type Editor to create, prototype, and to administrate custom question types. Switch to the Question types menu item of the Libraries to start the editor.

The Overview Page

Question types you create with the editor are available in the Questionnaire editor on a cross-project basis. You can add a new question type or import one from another EFS installation. Just click on + New or select Import from the drop-down menu.

Open

The overview page offers the following actions:

• Create a new custom question type from an empty template skeleton

• Import an archived custom questiontype (zip file) into the questiontype editor

• Copy an existing custom questiontype

• Preview an existing custom questiontype

• Delete an existing custom questiontype

The + New Button

By clicking the + New-split-button above the overview list, you open the “New”-dialog. In the opened dialog you have to name your new question type. In the second step, you can choose the layout version. Finally, you have to select a category and click the save button. For the moment there are five categories to choose.

1. Enter the title of your new question type and select the appropriate category. Assign your newly created question type to one of the following categories of question types : Single response list, Multiple response list, Standard matrix, Text field or 911 special. Also in the Questionnaire Editor you can find the newly created question type in the selected category.

2. The newly created question type will be listed in the overview. To edit it, click on its title. This opens an HTML editor that allows you to create the new question type. Here you can customize the template, the stylesheet, the Javascript, the exact settings and resources.

The following actions are available in addition to the further editing of the question types.

Import

An already created question type can be imported as a ZIP file. By doing an export/ import question types are portable across installations.

Create a new question type

You may only use Latin characters and numbers for the name. An internal name will be generated from your given name. It has all whitespaces removed, so it can be used as an identifier.

The category determines the underlying data structure for the answers as well as the initial files and available configuration options.

HTML-Editor

The Preview button opens a dialog with a live preview of your question type, as it would be rendered in a survey with an unmodified responsive layout.

The Save button is disabled by default. As soon as something is edited it will be activated and a modification marker is shown in the navigation to the left.

The navigation on the left consists of five items: Template, Style Sheet, JavaScript, Settings and Resources.

Template

It is compiled with the Smarty 2 template engine and makes use of several variables supplied by EFS. The initial template contains basic functionality that enables you to develop your own template.

Every question contains one or more variables (configured in Settings). A variable represents an answer option. In the case of a matrix every dimension is an answer option (or item) and therefore has its own variable.

For every variable there needs to be a list of possible values. These are the scale ele- ments (internally called “r_cat”), which are also configured under Settings.

In the template you have a variable $items, which is an array that contains all answer options of the question. You can iterate over them with a for-each loop or a section. Every item-object has a variable $r_cats, which is an array that contains all scale elements of the question. Again you can iterate over them with a loop.

If you want to see all existing Smarty variables insert {debug} in your template. A button will appear at the top right corner of the question preview, which opens a complete list of variables available at the point the debug-plugin was called.

A simple example how to iterate over items and r_cats:

Open

To submit values to the server the form needs to have a field (depending on the question type e. g. input, checkbox, hidden or select tag) containing the name of the variable matching its name.

This will print a select box for each item including any scale options (r_cat).

Style Sheet

In the Style Sheet menu you can edit the question type’s CSS file. Some styles are predefined, but you can remove them to get the default styling of the Responsive Layout and start your styling from there.

The question type’s main container gets a CSS class with the following structure:

In our example the class name would read as follows:

You should use this class as a namespace to limit your styles to your question type and prevent interferences with the outer layout or other questiontypes.

Java Script

In the JavaScript menu you define the logic of your question type.

At the beginning of the template file there is some code that makes the question type’s settings available in the JavaScript. You can find these settings in the options object of the JavaScript plugin. For example the answer options (items) are stored in an array called items. Likewise the scale options (r_cats) are stored in an array called rcats.

You will also find the question type’s options (defined in the Settings area) inside the this.options object. I.e. if you have an option named “orientation” in the options group “optionsGroup1”, you can access it like this:

You should start your code inside the plugin’s main function, but you can use the prepareOptions function to parse and cast the given options beforehand or to modify the type if you need to.

Settings

In the Settings menu you define the question type’s options and features. It is separated into five sections. Each section is responsible for a different kind of characteristics.

Question type options

The options you define in the question type options section will show up in the ques- tion editor and allow the creator of the survey to configure instances of your question type.

All Options belong to an options group, so you have to create an options group by clicking on the “Add options group” button.

Enter a name for the options group by which it can be referenced in the template and JavaScript files. You can also set its label in your current language and in other lan- guages by clicking on the globe icon next to the label field.

Click on the “Add option” button to open a menu with possible option types.

To access the defined options in the template you can use the question_info variable. You can find your options groups in the question_info.settings.questionTypeOptions object. For the “orientation”-option it looks like this:

Answer Options

In the Answer options section you define the initially available answer options for your question type. In matrix type question types every answer option stands for a dimension. In multiple choice question types they represent the checkboxes and in single choice question types you will not have this section at all, as these have exactly one answer option.

Scale elements

In the Scale elements section you set the possible answer values (codes). In matrix type question types every element stands for a column. In single choice question types they represent the radio buttons, whereas in multiple choice question types you don’t have this section, because every checkbox has exactly two scale elements with the values “0” and “1”.

Question editor features

In this section you can enable or disable a variety of features for your question type. Which ones are available depends on the category of your question type. For example, matrix type question types have different features available than single choice question types.

Configuration

Here you can change the name of the question type.

PHP

In this section you can enable the PHP plugin and Ajax. If the Ajax option is active, the “run” method must be called via an Ajax request. Otherwise, the method will be executed after the page is submitted. Furthermore, the PHP plugin can be executed in the preview mode.

Available objects:

$pluginData - Survey_Ospe_Question_Plugin_Data
Contains methods like getPid(), getQid(), getIsInLoop()

$settings - Array
Contains the configured options of the question. Access like:

$settings["questionTypeOptions"]["optionHeader"]["activeColor"];

$questionnaireDataAccess - Survey_Questionnaire_Data_Access
Provides wide range of functions related to the questionnaire and its data

$opseDataReader - survey_ospe_data_reader
Functions related to the survey and access to user and people data

$questionInfo - Array
Contains the questions settings, such as the questiontext. Access like:

$questionInfo['q_text'] = $questionInfo['q_text'] . " Question text addition";

Layout subrelease support

All custom question types have a configuration section “Layout subrelease support”. Please test your question type and select all supported Layout versions for it here, in order to be able to use the custom question type in a newer Layout version (e.g. RL 3.1).

Ressources

In the Resources area you can manage the files that you need for your question type. These fall into two categories:

• Files that you use as default value for “Resource”-options (image, audio or video files)

• Files that you need to include in your code (i.e. JavaScript libraries)

In any case you first upload your files by clicking on the upload icon next to the “Resources”-entry in the list on the left.

In our example we uploaded two files: “test.js” and “test.jpg”. Click on the JavaScript file to open it in the main area. Here you can edit it and save it by clicking on the checkmark-icon next to its name (or by pressing Ctrl-S).

Using a ressource in an option

Now that we have uploaded some files, those can be recycled for use in the Options menu, for options of the type “resource”. We will use the image as the default value for a “Resource”-option.

1. Go to the Settings area, expand Question type options and click on “Add option” inside an Options group.

2. Select “Resource” from the menu and enter values for the options name, label and help text.

3. Select “test.jpg” from the selectbox to assign it as default value.

The respective image will be displayed as default once you are creating a new question of your question type.

To access the image in your template, type the following (without line breaks):

In the JavaScript file you can also enter the following:

Using a ressource directly

The second case is using an uploaded file directly. This means including a file that can’t be modified by the user (as opposed to the previous case, where the user could select his own resource as value for an option).

In your template you can access the file “test.jpg” like this (without linebreaks):

When loading the file “test.js” in JavaScript enter as follows: