<commit_before>
.. include:: meta-mod_survey.rst

Adds the concept of `survey` :term:`resources <resource>`:
user-definable forms which can be created in the admin interface and
filled out by the website's visitors.
             
.. todo:: Add more documentation<commit_msg>doc: Add documentation on custom survey handlers<commit_after>.. highlight:: erlang
.. include:: meta-mod_survey.rst

Adds the concept of `survey` :term:`resources <resource>`:
user-definable forms which can be created in the admin interface and
filled out by the website's visitors.



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"}
     | 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.



.. todo:: Add more documentation
{'fraction_non_alphanumeric': 0.10656436487638533, 'fraction_numerical': 0.0, 'mean_word_length': 3.6475247524752477, 'pattern_counts': {'":': 1, '<': 9, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3688050', 'n_tokens_mistral': 637, 'n_tokens_neox': 613, 'n_words': 276}