Redbourne JavaScript Questionnaire Objects

Subject

This tutorial discusses the use of the Redbourne questionnaire classes (qaBuilder, qaRunner, qaDumper), how to use the classes to manipulate questionnaire data, present questionnaire, and retrieve the results. The following topics are covered:

• Overview of Questionnaire Objects
• Building a Questionnaire
• Executing (completing) a Questionnaire
• Displaying a questionnaire and its results
• Advanced questionnaire features

Overview

The Whitebeam System has been extended through three libraries (qaBuilder.js, qaRunner.js and qaDumper.js) to provide special JavaScript classes called qaBuilder, qaRunner and qaDumper respectively. The underlying storage mechanisms rely on File and Binary data, but this fact is almost completely hidden by the three classes. For portability, both questions and answers are stored in XML form.

Questionnaire contain a number of pages, which are presented to the user one at a time. Each page can contain one or more questions, and questions consist of HTML form components with their layout specified by a qaRunner style-sheet.

The three objects are all created by using the new JavaScript operation. This returns an instance of the requested class.

qaBuilder Object class defines methods that are used to easily create or modify a questionare.

qaRunner Object class defines methods that are used to easily display questionare pages, and to store the submited results.

qaDumper Object class defines methods that are used to output, in "pretty-printed" XML or CSV format, questionnaire and their answers.

Dependencies

Detailed Usage

Building a Questionnaire.

This is most easily done using a "createWizard" - An example of this can be found as part of the membership services application example

Alternatively, questionnaire can be built using the individual methods provided as part of the qaBuilder class. The sequence of events is generally:

• Create the object using qb = new qaBuilder();
• Initialise the questionnaire fileID = qb.initialise("Questionnaire Name"); (At this point a fileID is returned, which is the unique identifier for the questionnaire.)
• Add at least one page pageID = qb.insertPage();
• Add questions to pages questID = qb.insertQuestion(questObj); (See the definition of qaBuilder.insertQuestion for details of the questObj object.)
• Mark as complete fileID = qb.finish(); (See the definition of qaBuilder.insertQuestion for details of the questObj object.)

Each time the questionnaire is changed, an internal version number counter is incremented. The intention being that a questionnaire can be copied and modified, and answers to these questionnaire can be correctly attributed to the appropriate version of the questionnaire. The questionnaire's name provided to the initialise call is also used to identify a questionnaire. Be careful therefore to use different names for different questionnaire.

Executing (completing) a Questionnaire

A simple example of how to repeatedly execute a questionnaire and collect the answers is provided as as part of the membership services application example

Alternatively, answers can be collected using the individual methods provided as part of the qaRunner class. The sequence of events is generally:

• Create the object using qr = new qaRunner(questionFileID);
• Initialise the questionnaire answerFileID = qr.initialise(); (At this point a fileID is returned, which is the unique identifier for the answers.)
• Display the first page of questions qr.displayPage(1,"post","thispage.rhtm"); (This displayed page will automatically contain a "Next" or "Finish" button to support the next stage.)
• Check which button was pressed (Next, Previous or Finish) and act accordingly, by first saving the submitted results qr.submitPage(rb.page.formdata());, and then display the appropriate (Next or Previous) page as per the previous bullet.
• Mark as complete fileID = qr.complete();

If the questionnaire is not marked as complete, all of the submission buttons will be marked "Disabled" and cannot be pressed. This is intended an a debug and display facility.

Displaying a questionnaire and its results

The qaDumper object is designed to output Questionnaire and thier answers in a human useable form. This mostly involves the addition of whitespace to the existing internal format to make it readable.

See the object documentation, or the survey-runner example from the previous paragraph for examples of its use.

Advanced questioninaire features

The above text describes basic questionnaire building, running and displaying. Several adavnced features are available, which can be deduced by reading the object-level documentation.

Conditional questions and pages

Displaying questions (or not) based on answers to previous questions is the most notable advanced feature, and is achieved using the qaBuilder.linkQuestion() method, or the linkWizard.rhtm sample file. This feature allows a "target" page or question to be marked as dependent on a particular response being given to a question from an earlier page (NOTE: This means that page one questions cannot be made dynamic in this manner.) If a page or question does not meet the specified criteria, it is not displayed; If all questions on a page become disabled, then the page is automatically disabled.

WARNING: The above feature dynamically renumbers the questionnaire's pages. No attempt is made to remove pages or questions until at least one page of answers has been provided. This can cause a deadlock if the answers to page one can cause the whole of the rest of the questionnaire to be disabled. If this is possible, the JavaScript page should be used to catch this exception by checking the number of pages available to display after each page is submitted.

Mandatory questions

A facility exists to specify that answers to questions are mandatory. See documentation of the qaBuilder.insertQuestion() method for details of how to set a question as mandatory.

Using this feature requires that the Presentation Page running the questionnaire is written with this feature in mind. It must check the return value of each qaRunner.submitPage() call, and if it is zero (or commonly if it is less than 1) then the same page should be re-displayed. REMEMBER: that if the finish button was pressed, then the page should not finish the questionnaire under these circumstances. When the page is re-displayed, the appropriate instances of the qa$Mandatory variable are set, and error messages are automatically displayed according to which questions are at fault.