API Documentation

Read the Manual


This document is also available as: PDF

Survana API Documentation v.1.0

Table of Contents

  1. Questionnaires
  2. Types
  3. Dependencies

1. Questionnaires

All questionnaires are described in JSON format. Survana reads these descriptions and generates the UI elements that form the questionnaire (questions, text boxes, buttons, etc).

High-level view of a questionnaire:

//array of items
[
    //first item
    {
        //item properties
    },
    //second item
    {
        //item properties
    }
    //other items, as needed
]

A questionnaire is an array of objects. Each property of the object is treated as an HTML attribute of the element to be generated, except for properties that begin with , which are treated as server-side instructions for Survana, and will not be output to the browser.

{
    "type":"text",
    "label":"Age:",
    "id":"age",
    "maxlength":3
}

This JSON object describes a text input box, with a label of "Age:" and an HTML attribute of maxlength=3. Survana will generate the following HTML code: <label for="age"><input type="text" id="age" maxlength="3"></label>".

2. Types

The type property specifies what kind of UI element to generate (text boxes, labels, radiogroups, etc). The following is a list of all recognized type values:

  • element - A basic HTML element
  • question - A dedicated field for question text (styled)
  • rtf - HTML-enhanced questions.
  • text - A text field
  • number - A number field
  • slider - A slider with a number box to display the current value
  • radio - A radio field
  • group - A collection of radio fields (single choice)
  • checkbox - A checkbox field
  • checkboxgroup - A collection of checkbox fields (multiple choice)
  • input - A generic HTML <input> field
  • option - An HTML <option> element in a select or optgroup field
  • optgroup - A named group of option elements
  • select - A list of option elements (single choice), optionally grouped using optgroup
  • store - A well known database of values (such as countries, US states, etc)

If the type property is omitted, Survana will try to intelligently detect the type of the item, in the following order:

  1. element
  2. group
  3. store

Basic HTML element

A basic HTML element is an item that contains a tag property and/or has an type value of element. The following example instructs Survana to create an HTML element with the specified inner HTML text:

{
   "tag":"div",
   "html":"Hello, world"
}
  • tag - HTML element tag name
  • html - the text value of the HTML element

All other properties of the item will by default be output as attributes of the element.

Question

A question is simply a heading containing text. For other styles, see rtf.

{
    "type":"question",
    "html":"Why did the chicken cross the road?"
}
  • html - the text of the question.

rtf

For questions that should not look like headings, rtf is an element that can either display simple text, or HTML-enhanced text. The html property of an rtf element is only minimally enhanced by the UI framework, allowing greater control over the style of the text.

[{
    "type": "rtf",
    "html":"Why did the chicken cross the road?"
},
{
    "type": "rtf",
    "html":"Why <strong>did</strong> the <u>chicken</u> cross the road?"
}]

Text

A text field is an input field specialized for text entry.

{
    "type":"text"
}

Options inherited from input:

  • label - prepend a label to the input. If label is "" (empty string), it will cause the field to align to the left of its container. If the label is " " (space), the label will be invisible to the user (but the field will not change its alignment).
  • inline - display the field immediately after the label (no alignment).
  • maximize - fill the entire space to the right of the field.
  • suffix - append any HTML or type elements to the text field.
  • id - assign an HTML id and name value to the input (required for storing responses)

Relevant HTML attributes:

  • disabled - if set to "disabled", will show the field as disabled. This is useful in combination with depend.
  • placeholder - shows a message inside the box, if it's empty.
  • maxlength - the maximum number of characters allowed.

A screenshot showing various combinations of the options above:

Number

A number field is an input field specialized for numeric data.

{
    "type":"number"
}

Options inherited from input:

  • label - prepend a label to the field. If label is "" (empty string), it will cause the box to align to the left of its container. If the label is " " (space), the label will be invisible to the user (but the field will not change its alignment).
  • inline - display the field immediately after the label (no alignment).
  • maximize - fill the entire space to the right of the field.
  • suffix - append any HTML or type elements to the field.
  • id - assign an HTML id and name value to the input (required for storing responses)

Relevant HTML attributes:

  • disabled - if set to "disabled", will show the field as disabled. This is useful in combination with depend.
  • placeholder - shows a message inside the box, if it's empty.
  • maxlength - the maximum number of characters allowed.

A screenshot showing various combinations of the options above:

Slider

A slider field is an input field specialized for numeric data that falls in a known range of values.

{
    "type":"slider"
}

Options inherited from input:

  • label - prepend a label to the field. If label is "" (empty string), it will cause the box to align to the left of its container. If the label is " " (space), the label will be invisible to the user (but the field will not change its alignment).
  • inline - display the field immediately after the label (no alignment).
  • maximize - fill the entire space to the right of the field.
  • suffix - append any HTML or type elements to the field.
  • id - assign an HTML id and name value to the input (required for storing responses)

Relevant HTML attributes:

  • disabled - if set to "disabled", will show the field as disabled. This is useful in combination with depend.
  • placeholder - shows a message inside the box, if it's empty.
  • maxlength - the maximum number of characters allowed.

A screenshot showing various combinations of the options above:

Radio

A radio input field. Mostly used as part of a radio group.

{
    "type":"radio",
    "value":0
}

See group.

Checkbox

A checkbox input field. Mostly used as part of a checkboxgroup.

{
    "type":"checkbox",
    "value":0
}

See group.

group

Several components can be grouped together: radio, checkbox and select.

radio group

A group of radio buttons. The user is only allowed to pick one element out of the group.

{
    "group":"radio",
    "items":{
        "Yes":1,
        "No":0
    }
}
  • items : An array of objects (or an object) of the form: { "some label" : "some value" }.
  • direction: Either vertical or horizontal (default).
  • label - prepend a label to the field. If label is "" (empty string), it will cause the box to align to the left of its container. If the label is " " (space), the label will be invisible to the user (but the field will not change its alignment).
  • inline - display the field immediately after the label (no alignment).
  • maximize - fill the entire space to the right of the field. Doesn't enlarge radio buttons in horizontal radiogroups.
  • id - assign an HTML name value to the radio buttons, and an id value, autoincremented for every item

Relevant HTML attributes:

  • disabled - if set to "disabled", will show the field as disabled. This is useful in combination with depend.

A screenshot showing various combinations of the options above:

checkbox group

A group of checkbox buttons. The user is allowed to pick multiple elements in the group.

{
    "type": "checkboxgroup",
    "items": {
        "Boston": 0,
        "Cambridge": 1,
        "Watertown": 2
    }
}
  • items - An object of the form { "item label" : "item value" }
  • id - assign an HTML name value and an autogenerated id to each checkbox (required for storing responses)

Input

An input field is a raw HTML <input> element, which can be enhanced using the options below. Some fields such as text and number, rely on this generic input field.

{
    "type":"input"
}

Options:

  • label - prepend a label to the input. If label is "" (empty string), it will cause the field to align to the left of its container. If the label is " " (space), the label will be invisible to the user (but the field will not change its alignment).
  • inline - display the field immediately after the label (no alignment).
  • maximize - fill the entire space to the right of the field.
  • suffix - append any HTML or type elements to the text field.
  • id - assign an HTML id and name value to the input (required for storing responses)

Relevant HTML attributes:

  • type - type of <input> (see list of HTML5 input types )
  • disabled - if set to "disabled", will show the field as disabled. This is useful in combination with depend.
  • placeholder - shows a message inside the box, if it's empty.
  • maxlength - the maximum number of characters allowed.

Option

An HTML <option> element in a select or optgroup field.

{
    "type":"option",
    "label":"My Option",
    "value":"1"
}
  • label - text to be displayed
  • value - value for this option

Optgroup

A named group of option elements within a select field.

{
    // ... declaration of a "select" field
    items:[
             {
                 "type": "optgroup",
                 "label": "Grade School",
                 "items": [
                     {
                         "1": 1,
                         "2": 2
                         // ... other options
                     }
                 ]
             },
             {
                 // ... another optgroup
             }
    ]
}
  • label - a label for the option group
  • items - an object of the form { "opt label":"opt value" } or option items.

Select

A list of option elements (single choice), optionally grouped using optgroup.

A select field containing only option elements:

{
    "type": "select",
    "empty": true,
    "label": "Country:",
    "items": [
        {
        "United States":"US",
            "Andorra":"AD",
            "United Arab Emirates":"AE",
            "Afghanistan":"AF",
            "Antigua and Barbuda":"AG",
            "Anguilla":"AI",
            "Albania":"AL",
            "Armenia":"AM",
            "Netherlands Antilles":"AN",
            "Angola":"AO",
            "Antarctica":"AQ"
        }
    ]
}

A select field which uses optgroup elements:

{
    "type": "select",
    "label": " ",
    "empty": true,
    "items": [
        {
            "type": "optgroup",
            "label": "Grade School",
            "items": [
                {
                    "1": 1,
                    "2": 2,
                    "3": 3,
                    "4": 4,
                    "5": 5,
                    "6": 6,
                    "7": 7,
                    "8": 8
                }
            ]
        }
   ]
}

Options:

  • label - field label.
  • empty - make the first option in a select be an empty item.
  • items - a list of option or optgroup elements.
  • id - assign an HTML id and name value to the select box (required for storing responses)

Store

A store is a collection of items, representing well-known values (e.g. list of countries, list of US states, etc). When a questionnaire asks for "Country of Birth" and "Country of Residence", one could create a select with 200 option items for "Country of Birth" and then duplicate it for "Country of Residence", but that would create a 600+ line long questionnaire. That's not cool. A more elegant solution would be to use a store provided by Survana and generate appropriate fields based on the values in the collection.

For example, the countries collection contains a list of countries and their codes:

{
    "United States":"US",
    "Andorra":"AD",
    "United Arab Emirates":"AE",
    "Afghanistan":"AF",
    "Antigua and Barbuda":"AG",
    "Anguilla":"AI",
    "Albania":"AL",
    "Armenia":"AM",
    "Netherlands Antilles":"AN",
    "Angola":"AO"
}

On each line, the first string is called a "key" (e.g. "United States") and the second string is called a "value" (e.g. "US").

Suppose we would like to create a "Country of Birth" select field:

    "type":"select",
    "label":"Country of Birth:",
    "items":[
        // ... countries go here
    ]

To use the countries store in a select field (or any other field that takes an array of items), one must include the following item:

{
    "type":  "store",
    "store": "countries",
    "sort":  true,
    "item":  {
        "type": "option",
        "label": "key",
        "value": "value"
    }
}
  • store - the name of the store (see Store List)
  • sort - sort the collection
  • item - a template for the item to generate (see below)

item specifies how to use the key and value properties of each item in the countries store. The code snippet above will generate an option field for each item, with key and value replaced by the actual values in the store:

[
    {
       "type":"option",
       "label":"United States",
       "value":"US"
    },
    {
       "type":"option",
       "label":"Andorra",
       "value":"AD"
    }
]

Thus, Survana generates a long list of items, instead of the person creating the questionnaire.

Finally, the declaration of the select looks like so:

{
    "type":"select",
    "label":"Country of Birth:",
    "items":[
        {
            "type":  "store",
            "store": "countries",
            "sort":  true,
            "item":  {
                "type": "option",
                "label": "key",
                "value": "value"
            }
        }
    ]
}

The type property is optional. It is sufficient to provide an store property for the item to be recognized as a store.

Store List

The following is a list of all known stores in Survana:

  • countries - Countries

    { "United States":"US" }
    
  • states - U.S. states

    { "Massachusetts":"MA" }
    
  • years - All years since 1900 till 2012

    { "2012": 2012 }
    
  • months - All months in a year

    { "January": 1 }
    
  • days - All days in a month (1 - 31)

    { "1": 1 }
    

User-stores are not supported at the moment.

3. Dependencies

Certain fields become relevant (or irrelevant) depending on the response to one or more previous questions. To describe such dependencies between fields, Survana requires one to specify conditional expressions on the value of those fields.

For example, field xyz is relevant only if the value of the age field (not shown) is greater than or equal to 21.

   {
        "id": "xyz",
        //...
        "depend": {
            "test": {
                "age": {        //id of the field this field depends on
                    ">=": 21    //condition to test for
                }
            }
        }
        //...
   }

For equality tests, there's a shorthand syntax:

   {
        "id": "xyz",
        //...
        "depend": {
            "test": {
                "age": 21    // condition: age = 21
            }
        }
        //...
   }

The following are all operators recognized by test:

  • = - "=": 21 - equals 21
  • != - "!=": 21 - does not equal 21
  • > - ">": 21 - greater than 21
  • >= - ">=": 21 - greater than or equal to 21
  • < - "<": 21 - less than 21
  • <= - "<=": 21 - less than or equal to 21
  • in - "in": [19,20,21] - either 19 or 20 or 21
  • has - "has": 21 - (checkbox only) response contains 21

It is also possible to test the value of multiple fields:

   {
        "id": "xyz",
        //...
        "depend": {
            "test": {
                "age": 21,    // age = 21
                "license": 1  // and license = 1 
            }
        }
        //...
   }

The above example shows an and expression (i.e. 'age is 21 and license is 1'). Generally, and expressions are specified within curly braces {}.

An example of testing for a range ('age is between 18 and 21'), using an and expression:

   {
        "id": "xyz",
        //...
        "depend": {
            "test": {
                "age": {
                    ">=": 18,   //greater than or equal to 18
                    "<=": 21    //and less than or equal to 21
            }
        }
        //...
   }

The other supported expression type is or, which makes use of brackets []:

   {
        "id": "xyz",
        //...
        "depend": {
            "test": [
                { "age": 21 },    //age is 21
                { "license": 1 }  //or license is 1
            ]
        }
        //...
   }

Below is the implementation of a more complex test, 'either age is between 18 and 21, and license is 1, or age is greater than 50':

   {
        "id": "xyz",
        //...
        "depend": {
            "test": [
                {
                    "age": {
                        ">=": 18,    // age is between 18 and 21
                        "<=": 21
                    },
                    "license": 1    // and license = 1
                },
                {
                    "age": {
                        ">": 50     // or age is greater than 50
                    }
                }
            ]
        }
        //...
   }

A canonical dependency declaration contains the following keywords:

  • depend - Start of the dependency declaration object
  • test - Start of the condition to test for
  • true - (optional) Action(s) to perform when the result of test is positive (default: [enable,focus])
  • false - (optional) Action(s) to perform when the result of test is negative (default: [disable, blur])

When the result of the test is positive, the true action(s) are performed, otherwise the false actions are performed.

Survana supports the following actions:

  • clear - clears the field
  • focus - sets the focus on the field
  • blur - removes the focus from the field
  • enable - enables the field
  • disable - disables the field (and clears its content)
  • hide - hides the field
  • show - shows the field
  • message - displays a message; parameters:
    • message - the text to display
    • title - (optional) title of the message box (default: Message)
  • hidenext - prevents the user from continuing to the next questionnaire
  • shownext - allows the user to continue to the next questionnaire

Actions can be chained together, to achieve the desired effect. For example, to prevent the participant from continuing, unless they've agreed to the terms and conditions, a dependency could be set on the Agree/Disagree field itself:

   {
        "id": "terms",
        "group": "radio",
        "items": {
            "Agree": 1,
            "Disagree": 0
        },
        "depend": {
            "test": {
                "terms": 1    // dependency on ourselves. checks when value = 1, i.e. 'Agree'
            },
            "true": ["shownext"],     // if the user chose Agree, allow them to continue
            "false": [
                      "hidenext",    // otherwise, hide the 'Next' button and display a message
                      {
                          "action": "message",
                          "title": "Terms and Conditions",
                          "message": "You must agree to our Terms and Conditions in order to continue."
                      }
                     ]
        }
   }

Actions are performed in the order in which they're listed.