This article provides a comprehensive guide on using the Custom Question Type Editor in EFS. It covers the process of creating, prototyping, and administrating custom question types, including the overview page, creating new question types, and configuring various settings.
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.
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
| Category | Questions Type’s Base Data Model |
|---|---|
| Single response | 111 |
| Multiple response | 121 |
| Standard matrix | 311 |
| Text field | 143 |
| Special | 911 |
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 from.
- 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.
- 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 a new question type. Here you can customize the template, the stylesheet, the Javascript, the exact settings, and the resources.
The following actions are available in addition to the further editing of the question types.
| Action | Meaning |
|---|---|
| Preview | Have a look at the preview of your newly created question type. |
| Rights | Open the menu Rights admin to specify which user groups should have read and/or write access to the question type.Please note that you can only assign rights to users within your own teams.You can also define, if the question type supports an installation-wide rollout or team based access. |
| Copy | Copy a question type, which is then also listed in the overview and can be edited. |
| Download | Download a question type in a ZIP file and save it on your computer. |
| Delete | Delete a question type. |
| Unlock/Lock | Red: Question type cannot be edited.Green: Question type can be edited. |
Users can only edit question types when they posess the rights. Please ensure that the question type is not currently being edited by another user by referring to the Currently Edited column.
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.
You can already select the question type in a survey and use it as it is right now. Your modifications will be immediately visible in the survey. Refrain from editing question types used in live surveys. Instead, copy the question type and work on the copy
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.
Save any changes, before you navigate through the menu.
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.
If you need to see how special features are implemented you may have a look at the templates of the responsive layout, accessible in Survey menu → Layout → Pro editor.
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 elements (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:
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 question types.
Java Script
In the JavaScript menu, you define the logic of your question type.
If you do not need any JavaScript behaviour you can remove the example code and leave the file empty.
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 question 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 languages 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.
You can have as many options and options groups as you want. For example you could separate your options into an options group for functional options and one for layout related options.
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.
Please refer to the info-text of each feature to get a description of what the feature does.
Configuration
Here you can change the name of the question type.
This applies only to the displayed name. It does not change the initially created internal name, as you would have to update the template, CSS and JavaScript files to match the updated name.
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).
Resources
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 resource 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.
- Go to the Settings area, expand Question type options and click on “Add option” inside an Options group.
- Select “Resource” from the menu and enter values for the options name, label and help text.
- Select “test.jpg” from the select box to assign it as the 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 resource 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:
FAQ
What permissions do I need to use the Custom Question Type Editor?
You need the questiontype_editor write permission to access and use the Custom Question Type Editor.
Can I import question types from other EFS installations?
Yes, you can import archived custom question types (ZIP files) from other EFS installations using the Import function on the overview page.
How do I make my custom question type available in newer Layout versions?
Test your question type and select all supported Layout versions in the “Layout subrelease support” configuration section.