WOCAT » QCAT

h1. Questionnaire Structure

h2. Terminology

* *Questionnaire Data* (how the data of a questionnaire is saved in the DB and submitted to the API)

* *Questionnaire Configuration* (how the questionnaire is built, which questions are available in which categories etc.)

* *Questiongroup*: A group of questions belonging together. Example: Image, Caption, Location, Name of photographer. Questiongroups can be repeated, for example if multiple Images are available.

h2. Questionnaire Data

* The entire data of a questionnaire is stored in a single JSON field in the database.

* The format is as flat as possible: It contains questiongroups and questions (no categories or other Questionnaire Configuration data)

* Sample 1: "Questionnaire Data, shortened and with comments (in Python syntax)":https://git.cde.unibe.ch/snippets/2

* Sample 2: "Questionnaire Data, complete in JSON":https://git.cde.unibe.ch/snippets/3

h2. Questionnaire Configuration

* The configuration of a questionnaire consists of multiple levels:

  * *@sections@* (actually not used anymore and excluded from extracted configuration - see sample below)

    * *@categories@* (Example: 1. General information)

      * *@subcategories@* (Example: 1.1 Name of the SLM Technology (hereafter referred to as the Technology))

        * *@questiongroups@* (Example: Name and Locally used name) - not always directly visible in the form

            "questiongroups_repeating": Specifies if and how many times the questiongroup can be repeated.

          * *@questions@* (Example: Name)

            "questions_type": See [[Questionnaire_Structure#Available-question-types|documentation below]] for further information

            "questions_choices": The valid choices for this question, if available (e.g. radio or checkboxes)

* The structure of the Questionnaire Configuration can be extracted using a management command (under development). This might eventually become an API endpoint at one point?

* Sample: "Questionnaire Configuration of Technologies form, edition 2015":https://git.cde.unibe.ch/snippets/1

h2. API Endpoint to create Questionnaires

* Accepts data in the *Questionnaire Data* format.

* Validates the data, creates links to other models (e.g. users) and saves a new questionnaire.

* **_Needs to be created._**

h2. Available question types

* *@bool@*

  * Form: Renders as a radio.

  * Questionaire Data: Stores an integer (1: True/Yes, 2: False/No)

  * Example:  1.3 - The compiler and key resource person(s) accept the conditions regarding the use of data documented through WOCAT (@qg_accept_conditions.accept_conditions@)

* *@char@* (similar to @text@)

  * Form: Renders as a text input field.

  * Questionnaire Data: Stores an object with "locale" (e.g. @{"name": {"en": "Name"}}@).

  * Example: 1.1 - Name (@qg_name.name@)

* *@checkbox@*

  * Form: Renders as a checkbox field (multiple answers possible)

  * Questionnaire Data: Stores the predefined value keywords as a list.

  * Example: 3.1 - Main purpose(s) of the Technology (land user's perspective) (@tech_qg_6.tech_main_purpose@)

* *@date@*

  * Form: Renders a text field with a datepicker.

  * Questionnaire Data: Stores the value as text in format MM/DD/YYYY.

  * Example: 1.3 - When were the data compiled (in the field)? (@qg_accept_conditions.date_documentation@)

* *@file@* (similar to @image@)

  * Form: Renders a file upload field.

  * Questionnaire Data: Stores the UUID (as text) that is returned by the upload view after successful file upload.

  * Example: 4.1 - Technical drawing (@tech_qg_185.tech_drawing@)

* *@float@*

  * Form: Renders a number input field.

  * Questionnaire Data: Stores the value as float (with 2 decimals)

  * Example: 4.5 - Quantity (@tech_qg_36.tech_input_est_quantity@)

* *@hidden@*

  * Form: Renders a hidden field (no user input expected)

  * Questionnaire Data: -

  * Example: -

* *@image@* (similar to @file@)

  * Form: Renders a file upload field.

  * Questionnaire Data: Stores the UUID (as text) that is returned by the upload view after successful file upload.

  * Example: 2.3 - Image (@qg_photos.image@)

* *@image_checkbox@*

  * Form: Renders a checkbox field with images as labels

  * Questionnaire Data: Stores the predefined value keywords as a list.

  * Example: 3.2 - Select land use type (@tech_qg_9.tech_landuse@)

* *@int@*

  * Form: Renders as number input field.

  * Questionnaire Data: Stores the value as integer

  * Example: 2.6 - Indicate year of implementation (@tech_qg_160.tech_implementation_year@)

* *@link_id@*

  * Form: Renders as searchable (AJAX) select field to search a questionnaire in the DB

  * Questionnaire Data: Stores the ID of the other questionnaire as integer.

  * Example: 1.5 - Reference to Questionnaire(s) on SLM Approaches (@tech_qg__approaches.link_id@)

* *@map@*

  * Form: Renders an interactive map to set points.

  * Questionnaire Data: Stores a GeoJSON as text (FeatureCollection with one or multiple Point features)

  * Example: 2.5 - Add geo-referenced information on the map below (@qg_location_map.location_map@)

* *@measure@*

  * Form: Renders a radio input field that looks like a range / measure selector

  * Questionnaire Data: Stores the predefined value (usually an integer)

  * Example: 5.9 - health (@tech_qg_226.tech_access_health@)

* *@radio@*

  * Form: Renders a radio.

  * Questionnaire Data: Stores the predefined value as text.

  * Example: 1.2 - Specify the key resource person (@tech_qg_184.user_resourceperson_type@)

* *@select@*

  * Form: Renders a dropdown (select) field.

  * Questionnaire Data: Stores the predefined value as text.

  * Example: 4.4 - Type of measure (@tech_qg_165.tech_est_type@)

* *@select_model@*

  * Form: Renders as searchable (AJAX) select field to search a DB entry of a certain model

  * Questionnaire Data: Stores the ID of the DB entry as integer

  * Example:

* *@select_type@*

  * Form: Renders a searchable dropdown (select) field.

  * Questionnaire Data: Stores the predefined value as text.

  * Example: 1.1 - Country (@qg_location.country@)

* *@text@*

  * Form: Renders a text area.

  * Questionnaire Data: Stores an object with "locale" (e.g. @{"name": {"en": "Name"}}@).

  * Example: 2.1 - Definition of the Technology (@tech_qg_1.tech_definition@)

* *@user_id@*

  * Form: Renders as searchable (AJAX) select field to search a user through the WOCAT API.

  * Questionnaire Data: Stores the ID of the user (as text).

  * Example: 1.2 - User ID (@tech_qg_184.user_id@)