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:

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) {...});

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:

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 ...});

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 ...});

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 ...});

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 ...});

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 ...});

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):

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:

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

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.

dallinger.submitAssignment()¶

Notify the experiment that the participant’s assignment is complete. Performs a GET request to the experiment’s /worker_complete route.

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
);

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

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:

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");

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

mode - Dallinger experiment mode

participantId - Dallinger participant Id