Redwood Subject
RedwoodSubject is the redwood service to be included by subject pages. It provides a comprehensive set of functionality to help create redwood experiments more quickly and easily. In the example experiments, the service is included the alias rs.
##Functions
@param {function} the event handler function
The on_load event is the first event that is triggered once the experiment page has loaded and all framework initialization is complete. This event should be used as the starting point for the experiment.
@param {string} the event key
@param {object} (optional) an event value
trigger and on are intended to be used by a subject to transition from one state to the next. This method is used to trigger an event that can then be handled to perform some functionality. This method is intended to be used for events that are generated and handled by the same subject using the on method described below. Under the hood, the trigger method sends a message just like the send message.
@param {string} the event key
@param {function} the event handler function
This method is used for a subject to handle an event but it will only be called for the subject that triggered the event.
@param {string} the event key
@param {object} (optional) an event value
send and recv are intended to be used to transfer information from one subject to other subjects. This method is used to send a message that can then be handled by other subjects to perform some functionality.
@param {string} the event key
@param {function} the event handler function
This method is used for a subject to handle a message sent by another subject and will be called for all subjects except the subject that sent the message.
@param {integer} The value for the points earned this period
@param {integer} The amount of points to add to the current period points
@param {string} the event key
@param {object} the value for that key
This method does not trigger an event but is used to set data values for subjects. Values assigned using this set method will persist through subsequent periods.
@param {integer} (optional) the amount of time, in seconds, to delay before executing
This method causes the subject to advance to the next period in the experiment.
@param {integer} (optional) the amount of time, in seconds, to delay before executing
This method causes the subject to skip to the end of the experiment (the period after the last defined period).
@param {string} A key to uniquely identify this request so that it can be cancelled if necessary
@param {function} The function to call when the subject is in real-time
This method provides a means of triggering some functionality only when the subject is running in real-time (a page refresh has not occurred). In normal circumstances, this would be similar to putting the functionality in the on_load method. However, in cases where the page is refreshed and the experiment state is restored, certain functionality, such as intervals and timeouts, should only be restarted once state restoration is complete and the subject is back in real-time.
@param {string} The key to identify the when_live request to cancel
This method should be called when, for instance, a timer has been stopped and it should not be restarted in the case of a page refresh. It will remove the function from the list of functions to call when the subject is back to real-time after a page refresh.
@param {function} the callback function
This method will cause the given function to be called once all other subjects have also reached this point in the experiment. It provides a convenient way to sync subjects in time.
@param {array} an array of userIDs to wait for
@param {function} the callback function
This method is the same as after_waiting_for_all except that only the specified users will be waited for.
This is an array of objects, one for each subject, that contains data for that subject. The array is sorted by subjectID but the array index is not necessarily the subjectID. Each object in the array contains the following properties:
user_id {string} The subject id
points {integer} The points earned by the subject this period
accumulated_points {integer} The total points earned by the subject including previous periods
data {object} All experiment-specific data for the subject. Organized as a collection (indexed by event key) of arrays of values. Where the last value in each array is the most recent value for that key.
Each object also contains the following convenience methods:
get
@param {string} the event key
@return {object} the most recent data value for the given key
getPrevious
@param {string} the event key
@return {object} the second-most recent data value for the given key
This object simply provides an easy way of accessing the subject objects in the subjects array described above. It is a collection of references to the subject objects indexed by subjectID.
{string} The subjectID
{integer} Points earned this period
{integer} Total points earned including previous periods