Javascript API

Dallinger provides a javascript API to facilitate creating web-based experiments. All of the dallinger demos use this API to communicate with the experiment server. The API is defined in the dallinger2.js script, which is included in the default experiment templates.

The dallinger object

Any page that includes dallinger2.js script will have a dallinger object added to the window global namespace. This object defines a number of functions for interacting with Dallinger experiments.

Making requests to experiment routes

dallinger provides functions which can be used to asynchronously interact with any of the experiment routes described in Web API:

static dallinger.get(route, data)

Convenience method for making an AJAX GET request to a specified route. Any callbacks provided to the done() method of the returned Deferred object will be passed the JSON object returned by the the API route (referred to as data below). Any callbacks provided to the fail() method of the returned Deferred object will be passed an instance of AjaxRejection, see Deferred objects.

Arguments:

route (string) – Experiment route, e.g. /info/$nodeId
data (object) – Optional data to include in request

Returns:

jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.get('/participant/1');
// Wait for response and handle data
response.done(function (data) {...});

static dallinger.post(route, data)

Convenience method for making an AJAX POST request to a specified route. Any callbacks provided to the done() method of the returned Deferred object will be passed the JSON object returned by the the API route (referred to as data below). Any callbacks provided to the fail() method of the returned Deferred object will be passed an instance of AjaxRejection, see Deferred objects.

Arguments:

route (string) – Experiment route, e.g. /info/$nodeId
data (object) – Optional data to include in request

Returns:

jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.post('/info/1', {details: {a: 1}});
// Wait for response and handle data or failure
response.done(function (data) {...}).fail(function (rejection) {...});

The dallinger object also provides functions that make requests to specific experiment routes:

static dallinger.createAgent()

Creates a new experiment Node for the current partcipant.

Returns:: jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.createAgent();
// Wait for response
response.done(function (data) {... handle data.node ...});

static dallinger.createInfo(nodeId, data)

Creates a new Info object in the experiment database.

Arguments:

nodeId (number) – The id of the participant’s experiment node
data (Object) – Experimental data (see Info)

Returns:

jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.createInfo(1, {details: {a: 1}});
// Wait for response
response.done(function (data) {... handle data.info ...});

static dallinger.getInfo(nodeId, infoId)

Get a specific Info object from the experiment database.

Arguments:

nodeId (number) – The id of an experiment node
infoId (number) – The id of the Info object to be retrieved

Returns:

jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.getInfo(1, 1);
// Wait for response
response.done(function (data) {... handle data.info ...});

static dallinger.getInfos(nodeId)

Get all Info objects for the specified node.

Arguments:

nodeId (number) – The id of an experiment node.

Returns:

jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.getInfos(1, 1);
// Wait for response
response.done(function (data) {... handle data.infos ...});

static dallinger.getReceivedInfos(nodeId)

Get all the Info objects a node has been sent and has received.

Arguments:

nodeId (number) – The id of an experiment node.

Returns:

jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.getReceivedInfostInfos(1);
// Wait for response
response.done(function (data) {... handle data.infos ...});

static dallinger.getTransmissions(nodeId, data)

Get all Transmission objects connected to a node.

Arguments:

nodeId (number) – The id of an experiment node.
data (Object) – Additional parameters, specifically direction (to/from/all) and status (all/pending/received).

Returns:

jQuery.Deferred – See Deferred objects

Examples:

var response = dallinger.getTransmissions(1, {direction: "to", status: "all"});
// Wait for response
response.done(function (data) {... handle data.transmissions ...});

Additionally, there is a helper method to handle error responses from experiment API calls (see Deferred objects below):

static dallinger.error(rejection)

Handles experiment errors by requesting feedback from the participant and attempts to complete the experiment (and compensate participants).

Arguments:

rejection (dallinger.AjaxRejection) – information about the AJAX error.

Examples:

// Let dallinger handle the error
dallinger.createAgent().fail(dallinger.error);

// Custom handling, then request feedback and complete if possible
dallinger.getInfo(info).fail(function (rejection) {
 ... handle rejection data ...
 dallinger.error(rejection);
});

Deferred objects

All of the above functions make use of jQuery.Deferred, and return Deferred objects. These Deferred objects provide the following methods to facilitate handling asynchronous responses once they’ve completed:

.done(callback): Provide a callback to handle data from a successful response

.fail(fail_callback): Provide a callback to handle error responses

.then(callback[, fail_callback, progress_callback]): Provide callbacks to handle successes, failures, and progress updates.

The fail_callback function will be passed a dallinger.AjaxRejection object which includes detailed information about the error. Unexpected errors should be handled by calling the dallinger.error() method with the AjaxRejection object.

Experiment Initialization and Completion

In addition to the request functions above, there are a few functions that are used by the default experiment templates to setup and complete an experiment. If you are writing a highly customized experiment, you may need to use these explicitly:

static dallinger.createParticipant()

Create a new experiment Participant by making a POST request to the experiment /participant/ route. If the experiment requires a quorum, the response will not resolve until the quorum is met. If the participant is requested after the quorum has already been reached, the dallinger.skip_experiment flag will be set and the experiment will be skipped.

This method is called automatically by the default waiting room page.

Returns:: jQuery.Deferred – See Deferred objects

Examples:

// Create a new participant using entry information from dallinger.identity
result = dallinger.createParticipant();
result.done(function () {... handle ``data.status`` ...});

static dallinger.loadParticipant(assignment_info)

Load an existing Participant into the dlgr.identity by making a POST request to the experiment /participant route with some assignment_info which can be a scalar assignment_id or an object with entry_information parameters

Returns:: jQuery.Deferred – See Deferred objects

static dallinger.hasAdBlocker(callback)

Determine if the user has an ad blocker installed. If an ad blocker is detected the callback will be executed asynchronously after a small delay.

This method is called automatically from the experiment default template.

Arguments:

callback (function) – a function, with no arguments, to call if an ad blocker is running.

static dallinger.submitAssignment()

Notify the experiment that the participant’s assignment is complete. Performs a POST request to the experiment’s /worker_complete route, then redirects the main/parent window to the /recruiter-exit route and closes the secondary window in which the experiment ran.

Returns:: jQuery.Deferred – See Deferred objects

Examples:

// Mark the assignment complete and perform a custom function when successful
result = dallinger.submitAssignment();
result.done(function (data) {... handle ``data.status`` ...}).fail(
    dallinger.error
);

static dallinger.submitQuestionnaire(name="questionnaire")

Submits a Question object to the experiment server. This method is called automatically from the default questionnaire page.

Arguments:

name (string) – optional questionnaire name

static dallinger.waitForQuorum()

Waits for a WebSocket message indicating that quorum has been reached.

This method is called automatically within createParticipant() and the default waiting room page.

Returns:: jQuery.Deferred – See Deferred objects

Helper functions and properties

Finally, there are a few miscellaneous utility functions and properties which are useful when writing a custom experiment:

static dallinger.getUrlParameter(sParam)

Returns a url query string value given the parameter name.

Arguments:

sParam (string) – name of url parameter

Returns:

string|boolean – the parameter value if available; true if parameter is in the url but has no value;

Examples:

// Given a url with ``?param1=aaa&param2``, the following returns "aaa"
dallinger.getUrlParameter("param1");
// this returns true
dallinger.getUrlParameter("param2");
// and this returns null
dallinger.getUrlParameter("param3");

static dallinger.goToPage(page)

Advance the participant to a given html page; the participant_id will be included in the url query string.

Arguments:

page (string) – Name of page to load, the .html extension should not be included.

dallinger.identity

dallinger.identity provides information about the participant. It has the following string properties:

recruiter - Type of recruiter

hitId - MTurk HIT Id

workerId - MTurk Worker Id

assignmentId - MTurk Assignment Id

uniqueId - MTurk Worker Id and Assignment Id

mode - Dallinger experiment mode

participantId - Dallinger participant Id