Variables

• Core
  • Overview
  • Javascript
  • Creating a task
  • Deploying a task
  • API
  • Resources
• Sequencer
  • Introduction
  • Mixer
  • Templates
  • Variables
  • Inheritance
• Inheritance
  • Abstraction
  • Random
  • Exclusive Random
  • Sequential
  • By Data
  • Custom
  • Seed
  • Repeat
• Mixers
  • Random
  • Repeat
  • Weighted Random
  • Choose
  • Wrapper
  • Branch
  • Multi Branch
• Variables & Templates
  • Global
  • Data
  • Meta

• Accessing variables
• Global
  • Url
• The task object (current)
• Local Variables (local & meta)

Sometimes it is not enough to hard code behaviors into your tasks, sometimes you want behavior to depend on a previous response, or change some texts according to randomization. In order to achieve these behaviors you can use variables.

We will first describe variables that are common across all tasks, and are always available - these are the global and current variables. Then we will get down to variables variables that are available only in specific contexts - such as the data and meta variables.

Accessing variables

There are many ways to use variables within the PI tasks. You can learn about them in their respective documentation, check out conditions and templates. In addition, some of the variables can be accessed directly from your JavaScript, in cases that this is possible it will be mentioned in the description of the variable.

Global

The PI tasks expose one central object that serves as the hub of all of you tasks. The task objects get automatically registered on the global object, so that you can access them all from here. In addition, you can register any data that you want shared between your tasks onto global. This options is useful in various cases of branching, as well as when you want a common theme to appear in multiple tasks.

The following snippet sets global.value to 123, and global.variable to [1,2,3].

API.addGlobal({
    value: 123,
    variable: [1,2,3]
})

It may sometimes be handy to access global directly as window.piGlobal. Note that this allows you to access task objects as well.

window.piGlobal.greeting = 'Hello world';
console.log(window.piGlobal);

Meta

The global.$meta variable has a special meaning within the player. Each time the logger triggers within any of the manager tasks, all the data with then global.$meta object is added to each row of the log.

The following definition will cause each log posted to the server to include uid:

API.addGlobal({
    $meta: {uid: '12345678'}
});

postOnce

The global.$postOnce variable is posted to the server immidiately at the start of the task sequence. Note that any changes to this variable during the sequence will have no effect.

The following definition will cause the condition to be saved to the server at the begining of the session.

API.addGlobal({
    $postOnce: {condition: 'long'}
});

Url

The query string is a set of parameters that can be passed within a URL string. The global object exposes the url query string in a dedicated object called $url.

So that if you have a url such as example.com?bar=buz&bam=bif the object takes the following form:

global.$url == {
    bar: 'buz',
    bam: 'bif'
}

The task object (current)

Each PI task creates an object that holds information regarding that task. The object is automatically updated with data from within the tasks (such as question answers or other logs). The task object can be changed manually as well. You can extend it however you like using API.addCurrent:

API.addCurrent({
    value: 123,
    variable: [1,2,3]
});

While a task is running, its task object is available as current. Even when the task is not active it is available from within the global object, as global.<taskName>, where <taskName> stands for the task name as defined within the task manager.

For your convenience, here is a table describing some of the data available within the different task objects.

Local Variables (local & meta)

The variables that we've discussed so far are relevant for whole tasks or even whole studies. We now approach variables that have a narrower scope: they have to do with specific elements within your task. These variables are called Data and Meta.

The Data variables allow you to manually set useful information into each element. Their behaviour is described fully within as part of element inheritance.

The Meta variables hold some meta information regarding this element that is auto-generated by the mixer. In particular it holds two properties: `

The naming convention for these variables is <elementName>Data and <elementName>Meta respectively. For example, for tasks they appear as tasksData and tasksMeta.

The elementNames for the various tasks are as follows: