mod_survey

Adds the concept of survey resources: user-definable forms which can be created in the admin interface and filled out by the website’s visitors.

Survey question types

The following question types are defined in the survey.

likert
Answer a question on a scale of 5 points, from “completely disagree” (1) to “completely agree” (5).
long answer
An open question with a big text field.
matching
Question type which allows you to match given answers to each other.
narrative
Question type for specifying inline questions in a narrative fashion.
page break
Breaks the survey into multiple pages.
short answer
An open question with a single-lined text field. You have the option of specifying a validation like email, date, numeric.
thurstone
A multiple choice field. Like multiple choice, but more powerful. The choices are translatable, and you have the possibility to select either a single answer, multiple answers or submit the form directly when choosing an answer.
true or false
Answers a true or false question. You have the option to specify custom texts for both the options.
yes or no
Like true or false, answers a true or false question. You have the option to specify custom texts for both the options.
multiple choice
A simple multiple choice field that has the added option that the multiple choice can be a numeric value, in which case an overview of the total value will be shown in the printable list and beneath the survey pie chart. This is useful for creating forms which require you to enter an amount or quantity, e.g. for a reservation system. Multiple choice fields cannot currently be translated, use the “thurstone” question type in that case.
category
Choose a single resource from a given category as the answer to this question.
subhead
Renders a sub-heading between questions.
prompt
Renders an extra prompt block.
text block
Renders a text block between questions.

Intercepting survey submissions

When a survey is submitted, the survey module sends out a #survey_submit{} notification.

This notification has the following fields:

  • id - The id of survey being submitted
  • handler - A handler name (see below)
  • answers - The answers that were filled in
  • missing - answers that were missing
  • answers_raw - Unprocessed answers, e.g. the raw submission

To intercept a survey submission you would observe this survey_submit notification, and return ok:

observe_survey_submit(#survey_submit{ id = SurveyId }, Context) ->
    ?DEBUG(SurveyId),
    ok.

Creating a custom survey handler

The survey edit page has a dropdown for so-called “survey handlers”. A survey handler is a property that is set on the resource that indicates the handler that needs to be taken. Handlers are collected using the #survey_get_handlers{} fold notification.

For instance, the following defines a handler called “email_me”:

observe_survey_get_handlers(#survey_get_handlers{}, All, Context) ->
  [
   {<<"email_me">>, ?__(<<"E-mail me when survey is submitted">>, Context)}
   | All
  ].

Each handler will show up in the dropdown list and the editor can pick which handler he wants. The value chosen is passed along in the handler property of the survey submission, and as such can be used to intercept the survey submission:

observe_survey_submit(#survey_submit{ handler = <<"email_me">>, id = SurveyId }, Context) ->
    %% Do something here for surveys which have 'email_me' selected as handler
    ok;
observe_survey_submit(#survey_submit{}, _Context) ->
    %% Let other surveys use the default submision mechanism
    undefined.

Configurations keys

In the survey result editor it is possible to link an answer to a newly created person.

The category and content group for this person can be configured via the following two keys:

  • mod_survey.person_category, default to person
  • mod_survey.person_content_group, defaults to default_content_group

Edit on GitHub

Models

m_survey

Not yet documented.

Dispatch rules

survey

Dispatch rules Name Path Resource Args survey_results_download [“survey”,”results”,”download”,id]…

Filters

survey_any_correct_answer

Determine if any answer of a question was correct. Used for showing results of thurstone test questions.

survey_any_wrong_answer

Determine if any answer of a question was wrong. Used for showing results of thurstone test questions.

survey_as_pages

Split the page blocks into pages, prepare them for easy display in the survey question editor.

survey_is_stop

Check if there is a ‘stop’ question in list of (survey) blocks

survey_result_column_values

Used by the survey module to add extra column values to the result editor.

survey_test_max_points

Counts the total of all points that can be received for all test questions. Non test questions are not counted.

Scomp

poll

Show a given survey (with the id parameter) as a “poll”. This presents a simpler interface, in which the user is…

Referred by

survey_as_pages

Split the page blocks into pages, prepare them for easy display in the survey question editor.

survey_is_stop

Check if there is a ‘stop’ question in list of (survey) blocks

All dispatch rules

All the dispatch rules from all modules. For a background on dispatch rules, see The URL dispatch system.

survey_test_max_points

Counts the total of all points that can be received for all test questions. Non test questions are not counted.