Skip to content

Latest commit

 

History

History
99 lines (76 loc) · 4.87 KB

gettingstarted.md

File metadata and controls

99 lines (76 loc) · 4.87 KB
layout title
default
Getting started

Getting started

The concept

Structure

TheFragebogen follows the paper metaphor, i.e., a paper-based questionnaire is actually a sequence of paper sheets, which each consists of one or more items. An item consists, in fact, of a question and a scale. Sheets are represented in TheFragebogen by so-called Screens and items by so-called QuestionnaireItems. In TheFragebogen, a questionnaires consists of one or more Screens while only one Screen is shown at a time. A Screen encapsulates a specific functionality, such as presenting of items, waiting for some time, or exporting the stored data. For presenting QuestionnaireItems or HTML content (UIElementHTML), TheFragebogen provides ScreenUIElements.

The lifecycle of a questionnaire is handled by the ScreenController, which organizes the presentation of all Screens and also data export.

TheFragebogen is completely implemented using object-oriented programming (OOP).

Technical details

TheFragebogen enables to implement questionnaires as single-page applications. This is a specific implementation approach of a web page that modifies it's content using JavaScript. This allows to implement a questionnaire without requiring a web server or any other network infrastructure, as all necessary data can be included in this application. Nevertheless, all functionality that can be used to implement web pages can be used. For more information on available functionalities see Mozilla's Developer Network.

Code

This is a minimal implementation.

//This array stores all screens that will be shown.
var screens = [];

//First we create an HTML UI-Element with "Hello World"
var htmlWelcome = new UIElementHTML(undefined, "Welcome to the TheFragebogen!<br/>Please press 'Next'.");

//now we add a radio box with just one option 'yes'
var readyRadioBox = new QuestionnaireItemDefinedOne(undefined, "Are you ready?", true, ["Yes"]);

//to display the welcome message and the radio box
//we add both to a screen UI-Element
var screen1 = new ScreenUIElements(htmlWelcome, readyRadioBox);
//and add that screen to our screens list
screens.push(screen1);

//finally we create a ScreenController and add the screens list
var screenController = new ScreenController(screens);

function start() {
    document.body.innerHTML += "Everything loaded.";
    screenController.init(document.body);
    screenController.start();
}

The data export

During execution a questionnaire by a web browser the collected data is stored only within the web browser.
IMPORTANT: The collected data is not stored by default (i.e., closing the tab/window clears the data.)

For data export, the following options are available:

  • Download the data to local device from the web browser: ScreenWaitDataDownload.
  • Upload the data to a web server: ScreenWaitDataUpload.
  • Show the data to the user: ScreenDataPreview.

The data is exported as a file (comma seperated value (CSV)).

The data consists of five columns.

For each row (usually a row represents one QuestionnaireItem):

  • Column 1 contains the index of the Screen.
  • Column 2 contains the type of this data item (i.e., the class of the object this data item was collected by).
  • Column 3 contains the question (might be empty or a generic identifier).
  • Column 4 contains the potential answers (might be undefined).
  • Column 5 contains the answer(s) (might contain an array; depends on the answers to be exported).

NOTE: TheFragebogen also supports tracking changes of the answer of QuestionnaireItems. In this case, column 5 contains an array<array<timestamp, answer>>.

Next steps

  1. Take a look...
    1. ... at the demos.
    2. ... at TheFragebogen's README.
    3. ... at the JSDoc documenation.
  2. Setup your development tools
    1. Choose your HTML editor.
    2. Get familiar with web browser development tools (i.e., Firefox Developer Console or Chrome Devtools).
  3. Start by modifying the developer template.
  4. When done your implementation test it on different web browsers.
  5. Think about using version-control software (e.g., GIT).