Documentation for `XOWorkflow Survey` Package

<master>
<property name="doc(title)">XOWorkflow Survey Package Documentation</property>
<property name="context">Fully programmable surveys</property>
<property name="head">
</property>
<comment>
</comment>

<h1>Documentation for <code>XOWorkflow Survey</code> Package</h1>
<dl>
  <dt>Author</dt>
  <dd>Markus Moser</dd>
  <dt>Last modified</dt>
  <dd>02/2023</dd>
</dl>
<h2 class="pagebreak">Developers Documentation</h2>
This package provides a framework for authoring, conducting and evaluating fully programmable online surveys.

<h3>What do I need to start creating survey questions and surveys?</h3>
Question content is written in HTML markup within a HTML form. Input elements can be defined in HTML or xowiki formfield notation. Basic knowledge of HTML is a requirement. Experience with TCL or XoWiki Workflow is very beneficial.

Survey logic is fully programmable and can be customized and adapted in many ways for any scenario. Sample questions are available.

<h3>Creating my first survey</h3>
New surveys can be created on the landing page of the application via the menubar ("New" -> "Survey").
Each survey item serves logically as a folder containing questions and survey logic.

A newly created survey will automatically create 3 sample questions and two pages (welcome page and thank you page). An item named en:wf-iterate will be created which allows to customize survey logic.

New questions can be created via the menubar after navigating to a survey folder  ("New" -> "Question").
Questions <b>must</b> contain a <b>FORM</b> tag. Without the <form> tag, input elements will not be displayed correctly.
Input elements inside questions must be assigned unique names. Using identical names for input elements will not break the survey, but will certainly make the results less useful.

<h3>Multilanguage Surveys</h3>
Depending on the locales supported by your system, questions can be defined in multiple languages. When creating or editing a new question, a language prefix for the question can be defined. Different language versions of the same question with the same question name and different language prefixes can coexist in the same survey.

<h3>Programming survey logic</h3>
<pre><code><a href='/api-doc/proc-view?source_p=1&proc=SurveyIterateContext+instproc+default_definition'> SurveyIterateContext ad_instproc default_definition</a></code></pre> defines the default workflow for conducting a survey, which can be customized at any point.

To override or extend the default logic behavior, your own logic can be placed inside the en:wf-iterate item which defines the behavior of a specific survey.

First, the order of questions must be defined.
<pre><code>set pages [list en:f0 en:f1 en:f2]</code></pre>
For a multilanguage survey, one could write:
<pre><code>set lng [expr {[::xo::cc set locale] eq "de_DE" ? "de" : "en"}]
set pages {${lng}:f1A ${lng}:f1 ${lng}:f2}</code></pre>

It is possible to define filters within <code>eval_filters</code>, which by default will iterate through the question list. In the next example we will jump to a specific question if the user has selected 12 or 13 for input field 1a. The variable position defines at which position in the survey our filter will apply:
<pre><code>:proc eval_filters {position} {
    set lng [expr {[::xo::cc set locale] eq "de_DE" ? "de" : "en"}]
    set pages [subst [my property pages]]
    if {$position eq ""} {set position 0}
    if {$position eq [lsearch $pages ${lng}:f1A]} {
      if { [my property 1a] eq "12"} {
          set position [lsearch $pages ${lng}:f2_VW]
        } elseif { [my property 1a] eq "13"} {
          set position [lsearch $pages ${lng}:f2_WP]
        } else {
          set position [lsearch $pages ${lng}:f3]
        }</code></pre>

</div>

<h3>Anonymous surveys</h3>
These surveys can be filled by anybody who opens the URL, even multiple times. Thus it is not necessary to be logged in on the system to take this survey. Note that enabling fully anonymous surveys <b>requires giving Read permission</b> to "The Public" on the package permissions page ( [survey instance]/admin/permissions ).

<h3>Sharing the survey with your participants</h3>
Each survey has a URL in the list of surveys which can be shared with your participants. Anonymous surveys can be accessed without login by anybody who knows the URL and can also be filled out multiple times. Surveys for specific participants and logged in users will be associated with a specific user_id. If the user closes the survey and decides to continue at a later point, it is possible to continue at the point where the survey was closed. Note that non-anonymous surveys can only be taken once by each user.

<h3>Passing an external token to a survey</h3>
Sometimes it might be convenient to generate invitation links for your users with specific tokens which are unique for each user. The following line can be added to en:wf-iterate and shows how a token can be passed on to the survey and appear as value in the survey results. 
<pre><code>Property 0token -default {} -allow_query_parameter true</pre></code>
Now you can send out links to your survey with 0token as URL parameter eg survey?p.0token=150116

<h3>What is the idea behind the popup text for a survey?</h3>
The survey text is intended to be displayed on a landing page such as the dotlrn index page if the user has an open survey that is currently not completed. Currently, this needs to be done manually.
To display the popup it is necessary to add something to the landing page of your choice such as:
<pre><code>    if {[::xo::dc 0or1row -prepare integer check_for_open_survey {
        select name as survey_name,
               hkey->'survey_text' as survey_text
          from xowiki_form_instance_item_index
          where item_id = (
          select min(survey_id)
          from tlf_survey s,
          cr_items i
          where user_id = :user_id
          and survey_completed_p = 'f'
          and i.item_id = s.survey_id
          and i.publish_status = 'ready'
          and s.context_id is null)
    }]} {
        append survey_text "... href='/surveys/${survey_name}' Take this survey"</pre></code>