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:

| Type | Description | | ==== | =========== | | likert | Answer a question on a scale of 5 points, from “completely disagree” (1) to “completely agree” (5). | | short answer | An open question with a single-lined text field. You have the option of specifying a validation like email, date, numeric. | | long answer | An open question with a big text field. | | matching | Question type which allows you to match given answers to each other. | | 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. | | 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. | | 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. | | narrative | Question type for specifying inline questions in a narrative fashion. | | category | Choose a single resource from a given category as the answer to this question. | | country | Select a country from a drop-down list. | | hidden | A hidden input value. Can be used to register that a specific page of questions has been submitted. | | upload | Upload a file. Can be used on the last survey page, you have to add your own survey handler to handle the uploaded file. | | header | 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

  Survey/form module for creating questionnaires and collecting/reporting submitted answers.

Accepted Events

This module handles the following notifier callbacks:

• observe_acl_is_allowed: Check access to the survey answers using z_acl:rsc_editable.

• observe_admin_edit_blocks: Append the possible blocks for a survey's edit page using m_rsc:is_a.

• observe_admin_rscform: Redo the page jumps into correct page break blocks using survey_admin:admin_rscform.

• observe_export_resource_data: Fetch all ids making up the export, handles collections and search queries using z_acl:rsc_editable.

• observe_export_resource_filename: Fetch the filename for the export using m_survey:is_allowed_results_download.

• observe_export_resource_header: Fetch the header for the survey download using m_survey:is_allowed_results_download.

• observe_rsc_merge: Rename the answers of the loser to the winner using m_survey:rsc_merge.

• observe_survey_get_handlers: Add module-provided survey handlers to the available handler list.

• observe_survey_is_submit: Check if the given block is a survey question with submit button using m_survey:rsc_merge.

• observe_survey_submit: Process survey submissions for module handlers and return undefined for non-matching handlers.

• observe_tick_24h: Every day prune old saved intermediate survey results using m_survey_saved:prune_saved.

Delegate callbacks:

• event/2 with postback messages: survey_back, survey_remove_result, survey_remove_result_confirm, survey_start.

• event/2 with submit messages: survey_next.