API

• Core
  • Overview
  • Introduction
  • API
    • Pages
      • Page Timer
      • Page Messages
    • Questions
      • Hooks
      • Info
      • Text & Textarea
      • textNumber
      • dropdown
      • selectOne & selectMulti
      • grid
      • multGrid
      • slider
      • rank
    • settings
      • onEnd
      • logger
      • timer
      • Debugging
    • Data
  • Playground
• Question types
  • Text
  • Textarea
  • Text Number
  • Select One
  • Select Multi
  • Grid
  • Multi Grid
  • Slider
  • Rank
• Examples
  • Hello world
  • Body Awareness
  • Weight demo
  • Using Images
  • Buttons
  • Buttons Advanced
  • Buttons One Page
  • Dependency
  • Live Dependency
  • Grid
  • Timer
  • Open Ended
  • Open Ended Long
  • Rate Images
  • Rate Images Sizes
  • Scale With Feedback
  • Slider
  • User Prev Resp
  • Agreement scale

Pages

The basic unit in PIquest is the page. A page is usually one screen in your questionnaire. If your questionnaire presents all its questions in one screen, it will probably have only one page. The properties within a page manage how the question(s) is(are) displayed and how the participants interact with it (e.g., select an answer and then click a submit button).

For example, a page can look something like this:

var page = {
    header: 'Personal information:',
    headerStyle: {'background-color':'red',color:'blue'},
    decline: true,
    declineText: 'I prefer to keep this information to myself',
    questions: [
        {type:'text', stem:'What is your name?'},
        {type:'text', stem:'Where do you live?'}
    ]
}

Page Timer

The page timer allows you to constrain the time that users have to answer their questions. In order to control it, you may use the following properties.

Page Messages

You may want to display a message to the users when they run out of time at the end of a timer. Messages can be simple strings, or if you want finer control over the content of the message you can use the object API, that may be used as follows:

All these strings may use templates, and have access to the following objects: global, current, pagesData, pagesMeta.

Questions

Here are the types of questions PIQuest currently supports:

• Info
• Text & Textarea
• textNumber
• dropdown
• selectOne & selectMulti
• grid
• slider

All question types share some basic properties:

You may want to debug questions by activating the question DEBUG setting. You will then be warned in the console if a question name is reused (note: sometimes a question is supposed to be reused, if this warning pops up just make sure the use case is correct).

Hooks

Questions have hooks that allow you to respond to many events in the life time of the question. Each hook is invoked with global, current, the question log and the current question.

For example, in case the participant made an error you can mark it on the current object:

var questions = {
    stem: 'Please write "Hello"',
    onSubmit: function(log, current){
        // if the question response is not correct
        if (log.response !== 'Hello'){
            // mark an arbitrary flag so that it may be accessed somewhere else
            current.error = true;
        }
    }
}

Info

The info question isn't strictly a question. It allows you to use the common question properties in order to display information to the users. For example you can use it as follows:

{
    type: 'info',
    description: '<p>The following questions deal with emotions</p>' +
        '<p>Please answer them as honestly as possible</p>'
}

This question will simply display the description without offering any additional user interface (explicit question).

Text & Textarea

The text and textarea questions consist of a simple text input in which the users can type in text. The difference between them is that text questions consist of a single line, whereas textareas are multiline. There are also several properties that are unique to textareas. Both types of questions support the following properties.

The following properties are supported only by textareas:

For example, this is a text question that requires a valid email address (although there are better patterns out there for this purpose):

var quest = {
    stem: "Please type your email address",
    dflt: "my@email.com",
    required: true,
    pattern: /[A-Z0-9._%+-]+@[A-Z0-9.-]+.[A-Z]{2,4}/igm,
    errorMsg: {
        required: "You must enter a valid email address.",
        pattern: "This is not a valid email address"
    }
}

textNumber

The textNumber questions consist of a simple text input that limits the participant to numeric responses only. This type of questions have the following parameters:

For example, this is a text question that asks for a number under 273:

var quest = {
    type: 'textNumber',
    stem: "Please enter your height in cm",
    max: 273,
    required: true,
    errorMsg: {
        max: "That is a bit too much to believe... - even Robert Wadlow wasn't this tall!",
        number: "Your height has to be a number"
    }
}

dropdown

The dropdown question presents a dropdown that the user can use to select a single response. It has the following parameters:

selectOne & selectMulti

The selectOne and selectMulti questions present a list of possible response options for the user to pick from. The only difference between them is that select Multi allows the user to select more than one response option. They have the following parameters:

Each answer on the list has a value associated with it. By default the value is equal to the text of the answer. If numericValues is set, the value is set to the appropriate number. Using the object notation, you can set values of your own.

For example, the following question uses the plain notations, using numericValues to abstract numbers out of the result.

var quest = {
    type: 'selectOne',
    stem: "Do you like bananas?"
    numericValues: true,
    answers: [
        'Very much',    // ==> 0
        'I guess',        // ==> 1
        'Not at all'    // ==> 2
    ]
}

The following question uses the object notation to do the exact same thing:

var quest = {
    type: 'selectMulti',
    stem: "Do you like bananas?"
    numericValues: true,
    answers: [
        {text:'Very much', value:0},    // ==> 0
        {text:'I guess', value:1},        // ==> 1
        {text:'Not at all', value:2}    // ==> 2
    ]
}

grid

The grid question allows you to group multiple "multiple choice" questions into a single table. This is often useful when asking several likert type questions using the same scale.

The grid question itself keeps track of the sum of the row questions (excluding any questions that have non-number values).

grid.columns

If you set a string instead of a column object it will be treated as if you set only the stem and all other values will be set by default.

There are several column types at your disposal,

grid.rows

If you set a string instead of a row object it will be treated as if you set only the stem and all other values will be set by default.

Here is a simple example of using a grid:

var grid =     {
    type: 'grid',
    name:'grid',
    columns: ['Strongly agree' , 'agree' , 'don\'t know' , 'disagree' , 'Strongly disagree'],
    rows: ['I like grids', 'I like bananas too']
}

You can, of course have tighter control over the way things work:

var grid =     {
    type: 'grid',
    name:'grid',
    columns: [
        'Strongly agree',
        'agree',
        'don\'t know',
        'disagree',
        'Strongly disagree',
        {stem:'Decline to answer', value:'n/a', noReverse:true}
    ],
    rows: [
        {stem:'I like grids',name:'likeGrids'},
        // This questions scores will be reversed so that the sum of scores is meaningful 
        {stem:'I hate bananas', name:'likeBananas', reverse:true},

        // Allow only the extreme responses and declining to answer for this row only
        {stem:'Only extremes', name:'extremes', overwrite:[false, {type:'text'}, {type:'text'}, {type:'text'}, false, false]}
    ]
}

multiGrid

The multiGrid question allows you to group multiple questions into a single table. This is often useful when you are asking a set of simple qustions repeatedly.

The response for this question is an array of responses corresponding to the columns of the grid, so that the first item in the array corresponds to the response in the first column and so on.

multiGrid.columns

If you set a string instead of a column object it will be treated as if you set only the stem and all other values will be set by default.

There are several column types at your disposal,

multiGrid.rows

If you set a string instead of a row object it will be treated as if you set only the stem and all other values will be set by default.

Here is a simple example of using a multiGrid:

var multiGrid =     {
    type: 'multiGrid',
    name:'multiGrid',
    columns: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    rows: ['Days you work out', 'Days you go to work']
}

You can, of course have tighter control over the way things work:

var grid =     {
    type: 'multiGrid',
    name:'multiGrid',
    columns: [
        {stem:'Gender', type:'dropdown', answers: ['Male', 'Female']},
        'Study together',
        'Work together',
        {stem:'Description', type:'input'}
    ],
    rows: ['Friend 1', 'Friend 2' ]
}

slider

The slider question presents a slider that allows the user to pick a response along a preassigned range. It allows either the creation a continuous scale or dividing the range into steps. The values of the slider are always numbers. These are the supported properties:

The most common use of the slider is the creation of a visual analog scale (VAS). This is an example of using a slider to create a Likert type scale:

var quest = {
    type: 'slider',
    stem: 'Sliders are exremely useful.',
    min:1,
    max:7,
    steps:7,
    labels: ['Strongly Agree', 'Neutral', 'Strongly Disagree']    
}

rank

Ranking questions allow your subjects to sort a list of values. By default elements in the list are randomized. The response returned by this question is an array of numbers corresponding to the original - pre-randomized list. For example if you had a list ['a','b','c'] and it was sorted into['a','c','b'] then the response array will be [1,3,2] because the second and third element changed locations.

The syntax is fairly simple:

var quest = {
      type: 'rank', 
      stem: 'Please sort the follownig activities according to level of difficulty:',
      name: 'mart',
      correct: false,
      list: ['Cooking', 'Running', 'Dancing', 'Studying']
}

settings

Settings allow you to control the generic way that the player works. Change the settings using the addSettings function. The first argument to the function is always the name of the setting, the second argument is the setting values. In case the setting is an object, subsequent objects will extend each other so that settings may be progressively added.

onEnd

onEnd is a function to be called as soon as the task ends. It should be taken care of automatically when PIQuest is run from within the task manager.

API.addSettings('onEnd', function(){
    // Do something: for instance, redirect to 'my/url.html'
    location.href = 'my/url.html';
});

logger

This setting controls the way that logging works within the player.

API.addSettings("logger", {
    pulse: 34,
    url: '/my/url',    
    logfn: function(log,pagesData, global){
        return {name: log.name, set: global.setName};
    }
});

Within the player, each question (as defined by unique question name) may be logged only once. By default questions are logged at the end of a page (on submit or decline), if you want to delay logging until the end of the task, you may do so by setting nolog in the appropriate page or question.

If you want a question not to be logged at all, simply do not give it a name.

You may want to debug the logger by activating the DEBUG logger setting. When activated, it prints each logged object into the console.

Timer

The questionnaire timer allows you to constrain the time that users have to answer the whole questionnaire.

API.addSettings('timer', {
    duration: 10,
    message: {
        header: 'Time out!',
        body: 'You will now be redirected to the next task.'
    }
});

In order to control it, you may use the following properties.

Debugging

PIQuest can supply some extra information regarding its inner workings, all you have to do is set the DEBUG setting property like so:

// Log everything
API.addSettings('DEBUG', {
    level: 'warn', // log errors and warnings
    tags: ['page','animation'], // Log page and animation related messages
    hideConsole: true 
});

tags: Logs are broken down into subjects by tags. The tags property allows you to insert an array of tags that you want to be logged. If you want all tags to printed you may use the string 'all' instead of an array (this is also the default).

The tags currently available are as follows: page, question, conditions and animate.

level: The player has several levels of logging, by default it logs only error level logs. When you want to debug you should probably use info or warn. The precedence of logging levels is as follows: error>warn>info>debug. Each logging level includes any levels higher than itself.

hideConsole: This property allows you to control the display of logs inside the browser, if it is set to true then the logs will only be printed into your console.

Data

miQuest keeps record of user responses using plain js objects. These objects are both kept locally (see variables) and sent to the server.

The data logs are available as properties of the questsion object in current:

current.questions = {
    questionName1 : {...}, // log object
    questionName2 : {...} // log object
}

Following are the properties of the logged object:

The response for the question 'questionName1' in the current questionnaire can be accessed using current.questions.questionName1.response. The response for the question 'questionName1' in the questionnaire called 'taskName' can be accessed using global.taskName.questions.questionName1.response. You can use this data within templates or from within branches.