Building Custom Questionnaires

Overview

Your organization probably requires one or more questionnaires for its custom version of Onyx.  One of the questionnaires may be a contraindication questionnaire which participants would answer first in order to establish if there are any reasons the participant should not do one of the other stages.  All questionnaires (including contraindication questionnaires) are built in the same way. This section explains how to build a questionnaire.

The Process of Building a Questionnaire

To build a questionnaire:

1. You write a builder class in Java that calls the methods of the QuestionnaireBuilder class (part of the Onyx API).
2. You use run another class in the Onyx API (CreateQuestionnaire) to build your questionnaire. The result of running CreateQuestionnaire is an XML file that describes the structure and content of the questionnaire: its sections, pages, questions, categories (the set of possible answers to a question), skip patterns, validation, and so on.  One or more properties files are also produced. The number of properties files produced depends on how many locales (languages) you specify in CreateQuestionnaire.
3. Edit the properties files to localize the labels that will be displayed in the questionnaire.
4. As you  write your builder class, you can check the XML and properties files by running another class in the Onyx API (QuestionnaireRenderer).  This will produce a single HTML file that shows the structure of your questionnaire. This saves you the trouble of installing the questionnaire, running Onyx, and answering questions in order to advance through the questionnaire.
5. To include your questionnaire in Onyx, you copy the directory containing the XML and properties files for your questionnaire to the WEB-INF/config/quartz/resources/questionnaires directory.

Question Types

Onyx questionnaires can include questions in many formats. You can view screenshots of the different question formats on the OBiBa website.

Questionnaire Terminology

A category is one of the possible answers to a question that are proposed to the participant.

An answer is the category (or categories) selected by the participant.

An open-answer question is a question that the participant responds to by supplying their own answer rather than by selecting a category. The participant's answer is entered in a field.

Planning Your Questionnaire

Before you get deep into programming your questionnaire, we recommend that you and your organization design the required questionnaires as part of your customization plan.

As a minimum, for each question, you must decide the question format, the question text, and the text for the categories.

The questions should be grouped into pages (questions that will appear on the same screen). Questions can also be grouped into sections (by topic).

You can add one or more conditions to a question to control whether the question will be displayed or skipped.  The conditions can be:

• the answer to a previous question
• a measurement from an instrument
• a participant attribute
• any combination of the above

You can apply the same condition to several questions in a page or a section. Initially, you could display one question, and only display the other questions if the participant selects a particular answer for the first question. For example, if the participant answers "No" to "Are you pregnant?, then you would not display any of the questions on which this condition had been set: setCondition("PREGNANT", Y).

You must decide which type of screen the questionnaire will be displayed on:

• standard screen
• touchscreen (suitable for self-administered questionnaires)
• both

Writing Your Questionnaire Builder

You need to write a java class that builds your questionnaire.

Example builder classes

If you downloaded the source files for onyx-demo and the Maven project file as explained in Installing Required Software, you should have several examples in the src/main/java/org/obiba/onyx/example/questionnaire/util directory:

• CIPreliminaryQuestionnaireContentBuilder.java
• ConclusionQuestionnaireContentBuilder.java
• QuartzDemoQuestionnaireContentBuilder.java
• SelfAdminHealthQuestionnaireContentBuilder.java

You can copy one of these files, rename it, and use it as a starting point for your builder class.

What your builder class needs to do

As you will see in the example java files, your builder class needs to:

1.  Get an instance of QuestionnaireBuilder and call its createQuestionnaire method:

2.  Set the questionnaire display mode (for a standard screen or touchscreen):

3.  Use the methods of QuestionnaireBuilder (which is in the package org.obiba.onyx.quartz.core.engine.questionnaire.util}]) to add elements ({{Section, Page, Question...) to the questionnaire. 

• The with* methods.  Each of these methods adds a new element to the questionnaire. The new element is added to the current questionnaire element
• The in* methods.  Each of these methods retrieves a questionnaire element by its name, and sets it as the current element of that type.
• The set* methods.  Each of these methods sets a property of the current questionnaire element. For example

      All the above methods return the builder object itself so they can be concatenated. The builder object keeps track of a "current element" so you can add elements to it and set its properties.

Using the Onyx Questionnaire Cookbook

For examples of how add to various types of questions and categories to your questionnaire, see the Onyx Questionnaire Cookbook.

Building Your Questionnaire

Building your questionnaire means generating the XML and properties files that you will include in the war file for your custom version of Onyx.

What you need

If you downloaded the source files for onyx-demo and the Maven project file as explained in Installing Required Software, you should have everything you need to build your questionnaire.

To generate the XML and properties file

1.  Modify these lines in CreateQuestionnaire.java to include the name and version of your questionnaire.

2. Use this maven command to compile and run the CreateQuestionnaire programme.

mvn clean compile exec:java -Dexec.mainClass="org.obiba.onyx.example.questionnaire.util.CreateQuestionnaire"obiba.onyx.example.questionnaire.util.CreateQuestionnaire"

Localizing Your Questionnaire

Depending on how many locales (languages) you specify in your questionnaire builder programme, one or more properties files will have been generated when you run the programme. There should be a properties file per locale. 

For example, if you created your questionnaire in English and French, two properties files should have been generated:  language_en.properties and language_fr.properties.

Each properties file will contain a key for each questionnaire element in your questionnaire. You must ensure that string values are supplied for all keys in all of the properties file.

Checking Your Questionnaire

You will probably want to write your questionnaire builder programme bit by bit, and check that your questionnaire is being structured as you intend.  You can check your questionnaire as you go along by generating an HTML version of the questionnaire using the QuestionnaireRenderer class which outputs one HTML file from the XML and properties files. This saves you the trouble of installing the questionnaire, running Onyx, and answering questions in order to advance through the questionnaire.

What you need

If you downloaded the source files for onyx-demo and the Maven project file as explained in Installing Required Software, you should have everything you need to use the QuestionRenderer.

To generate the HTML

After you have compiled and run your questionnaire builder, you can generate the HTML version from the command line as follows:

1. Change to the directory where the QuestionnaireRenderer class file is located:

     $yourOnyxIHome/onyx-modules/quartz/quartz-core

2. Use this maven command to run the QuestionnaireRenderer.

     mvn -e exec:java -Dexec.classpathScope=test -Dexec.mainClass=org.obiba.onyx.quartz.core.engine.questionnaire.util.QuestionnaireRenderer -Dexec.args="inputPath htmlPath"

     where:

          questionnairesPath    is the questionnaires directory in which the directory containing the questionnaire.xml and properties files for your questionnaire are located
          htmlPath    is where you want to put the HTML file to be written

Including Your Questionnaire in Onyx

When your questionnaire is complete, you must put the questionnaire files in the appropriate place in the onyx directory structure, and you must modify the onyx configuration as explained below.

Where to put your questionnaire files

By default, questionnaires must be deployed in this directory:

    WEB-INF/config/quartz/resources/questionnaires

For example, for a questionnaire named "HealthQuestionnaire", version "1.0", localized in English and French, the questionnaire files would go here:

        WEB-INF/config/quartz/resources/questionnaires/HealthQuestionnaire/1.0/questionnaire.xml
        WEB-INF/config/quartz/resources/questionnaires/HealthQuestionnaire/1.0/language_en.properties
        WEB-INF/config/quartz/resources/questionnaires/HealthQuestionnaire/1.0/language_fr.properties

For a touchscreen questionnaire that includes image categories, you would put the images in this directory:

   WEB-INF/config/quartz/resources/questionnaires/HealthQuestionnaire/1.0/images

If several versions of the same questionnaire exist, the one with the highest version number is active. The version numbers must respect this pattern of digits separated by dots: "1.0", "1.0.1", "2.1.0", and so on.

Modifying the Onyx configuration

You must add your custom questionnaire stage to Onyx and remove any of the questionnaire stages that came with the onyx-demo that you do not want.

To edit stages.xml

To configure Onyx to include your questionnaire as a stage of the interview, you must edit the WEB-INF/config/quartz/stages.xml file and add a stage element for the questionnaire. The stage name must be the name that you used for the questionnaire in your QuestionnaireBuilder class.

If you want to define any stage dependencies, see Defining Stage Dependencies.

You should also remove any stages that you do not want in your custom version of Onyx

To localize the name of your questionnaire

You must also edit each of the properties files in the WEB-INF/config/quartz directory to localize the names of the questionnaire in each interface language.

For example:

        In the English properties file (WEB-INF/config/quartz/messages_en.properties), add a line like this:

            HealthQuestionnaire.description=Custom Health Questionnaire

        In the French properties file (WEB-INF/config/quartz/messages_fr.properties), add a line like this:

            HealthQuestionnaire.description=Questionnaire personnalisé sur la santé

Search Onyx Documentation