LimeSurvey 2.0 how to create a new question type

From LimeSurvey Manual
Jump to: navigation, search
(:exclaim:) The information on this page is out of date (2013-03-05)

Contents


General

Question types are plug-ins. That means without too much effort you can add and delete question types from LimeSurvey 2. At the time of this writing there is only one question type implemented so far, a normal text input which stands as an example for all question types.

Naming Convention

Every question type you create has to have a unique short name. That name is used in a lot of places to be able to load the needed files for a question type. This short name has to start with the letters 'qt'. For example for the text question type we chose the name 'qttext'. In the further documentation you must replace all occurrences of 'qttext' with the short name for your question type.

General File Structure

A question type consists of the following directorys in files (we use the qttext question type as example). All directories are inside /limesurvey2/app/


/webroot/js/questiontypes

     qttext.js

/webroot/css/questiontypes

     qttext.css

/plugins/qttext

     qttext_app_controller.php

     qttext_app_model.php

/plugins/qttext/controllers

     qttext_designs_controller.php

     qttext_runtimes_controller.php

/plugins/qttext/models

     qttext_design.php

     qttext_runtime.php

/plugins/qttext/views/qttext_design

     create.ctp

/plugins/qttext/views/elements

     design.ctp

/webroot/img/

     qttext.png


Look complicated? It is not!

Here is an explanation of each needed file:

Question-specific CSS & Javascript

/webroot/js/questiontypes/qttext.js

This file is needed for all specific javascript you need in the question builder for this question type and which is not already provided by the LimeSurvey builder itself. Do not put any javascript directly into the views (which will be explained later).

In this file one function must exist:

function qttext_attachevents(questionid)

This function is called after this question type was loaded by the main javascript builder engine. It is used to attach all needed events to this question type. It has to accept either a question id (to attach events to a just added question) or the keyword 'all' - 'all' means (you guessed it) that the events are attached to all the questions of this type. (for example this is needed when a complete survey page is loaded).

All other functions in this file should be prepended with the question type shortname too. (for example: function qttext_sizechang(sender)) to prevent name collisions.

If you look into qttext.js then you will notice only one further javascript function (qttext_sizechang) which is there to change the size of the text question input field. All other javascript functions (Mandatory, Fillin-Helper) are part of the main builder js engine and so they don't need to be put here.

/webroot/css/questiontypes/qttext.css

This file contains all CSS that is specific to the question type when used in the survey builder. The file has not to exist and will be only loaded if it does.

Formal Plugin Files

Formal Question Plugin files

/plugins/qttext/qttext_app_controller.php

This file has to exist mainly for CakePHP's sake. For the Text question type it does only contain one line:

class QttextAppController extends AppController {}

Besides that it does does not do much yet. Maybe I am ignorant of CakePHPs mechanism but I have found no further use for it (yet).

/plugins/qttext/qttext_app_model.php

This file has to exist mainly for CakePHP's sake. For the Text question type it does only contain one line:

class QttextAppModel extends AppModel {}

Besides that it does does not do much yet. Maybe I am ignorant of CakePHPs mechanism but I have found no further use for it (yet).

Controller

/plugins/qttext/controllers/qttext_designs_controller.php

Okay, now it is getting more interesting. This controller file contains a couple needed functions. Notice that the standard layout in this file is 'ajax'. That means essentially that an empty layout will be used when rendering the HTML in the resulting views. So far this controller file has the following important functions:

beforeFilter()

This function only switches off debug mode for sure. Believe me if I say that you don't want debug output in your AJAX data.

create()

This function is called when a new question is added to the survey builder. It sets the default values for the question type/the view that is rendered later. This function is called by an AJAX call when this particular question type is dropped onto a page in the survey builder.

/plugins/qttext/controllers/qttext_runtimes_controller.php

This file is not functional yet but it was originally intended to be reponsible for settings the default values for a question in runtime view. This might change.

Models

/plugins/qttext/models/qttext_design.php

This file describes the question type for design mode.

General Variables

var $name = 'QttextDesign';  // This is a cake standard variable fot this model - required

var $useTable = false;       // This model does not really use a table - it is an abstract model

var $qtversion = 1;          // This might come in hand later to version question types if necessary - this variable always should have this name

function getQuestionTypeName()

This function has to exist and returns the localized name for the question type.

function getQuestionTypeDescription() {

This function has to exist and returns the localized name for the question type.

function getQuestionAttributes()

This function contains all attributes that need to be saved when this question is saved to the question table.

This is very important for your question types to get your custom attributes saved by the builder engine.

Views

/plugins/qttext/views/qttext_design/create.ctp

This is the basic view when the question type is created. It's only used on creation time.

There  is not much content because the view uses an element.

var newquestionid=<?php echo $questionid;?>;

var newquestiontype="qttext";

Both javascript variables above have to exist so the new question type can be properly registered and all events attached in the javascript builder. Admittedly the way of how the variables are pushed to javascript looks a little strange, but it works fine across all browsers.

/plugins/qttext/views/elements/design.ctp

This file is the main file for the new question type. It is an element so it can be called by the question type plugin on creation of a question but also when the survey builder loads a question page this element is loaded directly_.

A few rules for this view:

  • All elements that are NOT input elements and need to be saved when the save button is clicked must have he class 'saveme' added. That way the survey builder knows it is an element to be saved.
  • You can see that all important elements are appended with the question_id so that when you save the survey the buidler knows which question is saved.

Standard elements for which the settings are saved: (X is the possible question ID)

  • question_edit_X: Standard question text
  • question_help_X: Standard question fill-in helper text
  • question_defaultvalue_X: Standard value for a question
  • cbMandatory_X: State of the mandatory checkbox
  • cbFillHelp_X: State of the Fill-In helper checkbox

/webroot/img/qttext.png

This PNG file is the image that be shown on the button in the question builder palette. It's a 25x25 bitmap and should represent your question type.

Last Step

The last step to do is make your new question type known to LimeSurvey 2. Add a new entry with your question type to the table question_types. Always try to enhance existing question types - if you build a completely new question type contact the development team so you get a unique ID assigned.

Update

- Question type structure is coded to become more modular, especially the view part of the question design.

- Question Type Structure

 
+ Models

   + qt<name>_design.php

   + qt<name>_runtime.php

 + Controllers

   + qt<name>_designs_controller.php

   + qt<name>_runtimes_controller.php

 + Views

   + elements

       + design.ctp //Render the necessary elements for the question's display in Builder

       + runtime.ctp //Render the question in Survey Engine

       + questionanswer.ctp //Render the question's answer part

       + questionfooter.ctp //Render the question's footer. Link to questionfooterleft and questionfooterright

       + questionfooterleft.ctp //Render the question's footer left part

       + questionfooterright.ctp //Render the question's footer right part

       + questionhelp.ctp //Render the question's help

       + questionid.ctp //Render the question's ID

       + questionmenu.ctp //Render the question's menu

       + questiontext.ctp //Render the question's text

   + qt<name>_design

       + create.ctp //Render when the question is created in builder. Link to elements/design.ctp

 + qt<name>_app_controller.php //Main Controller extends Question Types Controller

 + qt<name>_app_model.php //Main model extends Question Types Model

 There is 1 CakePHP script to automate the creation of new

 question types.To run the script

   
+ in Linux/Mac :

       + navigate to cake/console

       + run command: cake questiontype

       + type in the question type's name: only characters and numbers ( no space )

   + in Windows : //To be filled