Press "y" to Continue. Press "n" to end this node of the experiment.
', on_finish: function(data) { if (jsPsych.pluginAPI.compareKeys(data.response, 'n')) { jsPsych.endCurrentTimeline(); } }, timeline: trials } var after_block = { type: jsPsychHtmlKeyboardResponse, stimulus: 'The next node
' } jsPsych.run([block, after_block]); ``` --- ## jsPsych.endExperiment ```javascript jsPsych.endExperiment(end_message) ``` ### Parameters | Parameter | Type | Description | | ----------- | ------ | ---------------------------------------- | | end_message | string | A message to display on the screen after the experiment is over. | ### Return value None. ### Description Ends the experiment, skipping all remaining trials. If the `on_finish` event handler for `jsPsych` returns a `Promise` then the `end_message` will not be displayed until the promise is resolved. ### Example #### End the experiment if a particular response is given ```javascript var trial = { type: jsPsychImageKeyboardResponse, stimulus: 'image1.jpg', choices: ['y', 'n'] prompt: 'Press "y" to Continue. Press "n" to end the experiment
', on_finish: function(data){ if(jsPsych.pluginAPI.compareKeys(data.response, "n")){ jsPsych.endExperiment('The experiment was ended by pressing "n".'); } } } ``` --- ## jsPsych.finishTrial ```javascript jsPsych.finishTrial(data) ``` ### Parameters | Parameter | Type | Description | | --------- | ------ | -------------------------------- | | data | object | The data to store for the trial. | ### Return value Returns nothing. ### Description This method tells jsPsych that the current trial is over. It is used in all of the plugins to end the current trial. When the trial ends a few things happen: * The data is stored using `jsPsych.data.write()` * The on_finish callback function is executed for the trial * The on_trial_finish callback function is executed * The progress bar is updated if it is being displayed * The experiment ends if the trial is the last one (and the on_finish callback function is executed). * The next trial, if one exists, is started. ### Example ```javascript // this code would be in a plugin jsPsych.finishTrial({correct_response: true}); ``` --- ## jsPsych.getAllTimelineVariables ```javascript jsPsych.getAllTimelineVariables() ``` ### Parameters None. ### Return value Returns an object with all available timeline variables at this moment in the experiment, represented as `key: value` pairs. ### Description This function can be used to get all the timeline variables at a particular moment in the experiment. Can be useful for annotating data, such as in the example below. ### Example ```javascript var trial = { type: jsPsychHtmlKeyboardResponse, stimulus: 'Just a demo', on_finish: function(data){ // merge all timeline variables available at this trial into the data for this trial Object.assign(data, jsPsych.getAllTimelineVariables()) } } ``` --- ## jsPsych.getCurrentTimelineNodeID ```javascript jsPsych.getCurrentTimelineNodeID() ``` ### Parameters None. ### Return value Returns the ID of the TimelineNode that is currently active. ### Description Gets the ID of the active TimelineNode. The ID is a string that follows a specific format: * `"0.0"` is the ID of the first top-level TimelineNode * `"1.0"` is the ID of the second top-level TimelineNode * `"2.0"` is the ID of the third top-level TimelineNode, and so on... If a TimelineNode iterates multiple times (using the loop function, for example), then the iterations are indicated in the second number: * `"0.0"` is the ID of the first top-level TimelineNode during the first iteration * `"0.1"` is the ID of the first top-level TimelineNode during the second iteration * `"0.2"` is the ID of the first top-level TimelineNode during the third iteration, and so on... If TimelineNodes are nested in other TimelineNodes, then the hierarchical structure is shown with `"."`: * `"0.0-1.0"` is the ID of the second TimelineNode on the timeline of the first top-level TimelineNode. * `"0.0-2.0"` is the ID of the third TimelineNode on the timeline of the first top-level TimelineNode, and so on... The rules about iterations apply throughout the hierarchical ID: * `"0.2-1.3"` is the ID of the second TimelineNode, executing for the fourth time, on the timeline of the first top-level TimelineNode, executing for the third time. ### Example ```javascript var id = jsPsych.getCurrentTimelineNodeID(); console.log('The current TimelineNode ID is '+id); ``` --- ## jsPsych.getCurrentTrial ```javascript jsPsych.getCurrentTrial() ``` ### Parameters None. ### Return value Returns the object describing the current trial. The object will contain all of the parameters associated with the current trial. ### Description Get a description of the current trial ### Example ```javascript var trial = jsPsych.getCurrentTrial(); console.log('The current trial is using the '+trial.type+' plugin'); ``` --- ## jsPsych.getDisplayElement ```javascript jsPsych.getDisplayElement() ``` ### Parameters None. ### Return value Returns the HTML DOM element used for displaying the experiment. ### Description Get the DOM element that displays the experiment. ### Example ```javascript var el = jsPsych.getDisplayElement(); // hide the jsPsych display el.style.visibility = 'hidden'; ``` --- ## jsPsych.getInitSettings ```javascript jsPsych.getInitSettings() ``` ### Parameters None ### Return value Returns the settings object used to initialize the experiment. ### Description Gets the object containing the settings for the current experiment. ### Example ```javascript var settings = jsPsych.getInitSettings(); // check the experiment structure console.log(JSON.stringify(settings.timeline)); ``` --- ## jsPsych.getProgress ```javascript jsPsych.getProgress() ``` ### Parameters None. ### Return value Returns an object with the following properties: | Property | Type | Description | | -------------------- | ------- | ---------------------------------------- | | total_trials | numeric | Indicates the number of trials in the experiment. Note that this does not count possible loops or skipped trials due to conditional statements. | | current_trial_global | numeric | Returns the trial index of the current trial in a global scope. Every trial will increase this count by 1. | | percent_complete | numeric | Estimates the percent of the experiment that is complete. Works as expected for experiments without conditional or looping timelines. For complex timelines, the percent is an approximation. | ### Description This method returns information about the length of the experiment and the subject's current location in the experiment timeline. ### Example ```javascript var progress = jsPsych.getProgress(); alert('You have completed approximately '+progress.percent_complete+'% of the experiment'); ``` --- ## jsPsych.getProgressBarCompleted ```javascript jsPsych.getProgressBarCompleted() ``` ### Parameters None. ### Return value Returns a value between 0 and 1 representing how full the progress bar currently is. ### Description Used to get the current value of the progress bar. Works for automated and manual control. ### Example ```javascript var progress_bar_amount = jsPsych.getProgressBarCompleted(); ``` --- ## jsPsych.getStartTime ```javascript jsPsych.getStartTime() ``` ### Parameters None. ### Return value Returns a `Date` object indicating when the experiment began. ### Description Get the time that the experiment began. ### Example ```javascript var start_time = jsPsych.getStartTime(); ``` --- ## jsPsych.getTotalTime ```javascript jsPsych.getTotalTime() ``` ### Parameters None. ### Return value Returns a numeric value indicating the number of milliseconds since `jsPsych.run` was called. ### Description Gets the total time the subject has been in the experiment. ### Example ```javascript var time = jsPsych.getTotalTime(); console.log(time); ``` --- ## jsPsych.pauseExperiment ```javascript jsPsych.pauseExperiment() ``` ### Parameters None. ### Return value None. ### Description Pauses the experiment. The experiment will finish the current trial, but will not execute any additional trials until `jsPsych.resumeExperiment()` is called. ### Example ```javascript var trial = { type: jsPsychHtmlKeyboardResponse, stimulus: 'Press p to take a 30 second break. Otherwise, press c to continue immediately.', choices: ['p','c'], on_finish: function(data){ if(jsPsych.pluginAPI.compareKeys(data.response, "p")) { jsPsych.pauseExperiment(); setTimeout(jsPsych.resumeExperiment, 30000); } } } ``` --- ## jsPsych.resumeExperiment ```javascript jsPsych.resumeExperiment() ``` ### Parameters None. ### Return value None. ### Description Resumes the experiment after a call to `jsPsych.pauseExperiment()`. If the post trial delay (`post_trial_gap`) has not yet been reached, then the experiment will not continue until the delay is finished. For example, if `post_trial_gap` was 10,000ms and `jsPsych.resumeExperiment()` was called 6,000ms after the previous trial finished, then the experiment would not continue for another 4,000ms. ### Example ```javascript var trial = { type: jsPsychHtmlKeyboardResponse, stimulus: 'Press p to take a 30 second break. Otherwise, press c to continue immediately.', choices: ['p','c'], on_finish: function(data){ if(jsPsych.pluginAPI.compareKeys(data.response, "p")) { jsPsych.pauseExperiment(); setTimeout(jsPsych.resumeExperiment, 30000); } } } ``` --- ## jsPsych.run ```javascript jsPsych.run(timeline) ``` ### Parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | timeline | array | An array containing the objects that describe the experiment timeline. See [Creating an Experiment: The Timeline](../overview/timeline.md). | ### Return value None. ### Description Start the jsPsych experiment with the specified timeline. ### Example ```javascript var timeline = [trial1, trial2, trial3]; jsPsych.run(timeline); ``` --- ## jsPsych.setProgressBar ```javascript jsPsych.setProgressBar(value) ``` ### Parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | value | numeric | Proprotion (between 0 and 1) to fill the progress bar. | ### Return value None. ### Description Set the progress bar to a custom amount. Proportion must be between 0 and 1. Values larger than 1 are treated as 1. ### Example ```javascript jsPsych.setProgressBar(0.85); ``` --- ## jsPsych.timelineVariable ```javascript jsPsych.timelineVariable(variable, call_immediate) ``` ### Parameters Parameter | Type | Description ----------|------|------------ variable | string | Name of the timeline variable call_immediate | bool | This parameter is optional and can usually be omitted. It determines the return value of `jsPsych.timelineVariable`. If `true`, the function returns the _value_ of the current timeline variable. If `false`, the function returns _a function that returns the value_ of the current timeline variable. When `call_immediate` is omitted, the appropriate option is determined automatically based on the context in which this function is called. When `jsPsych.timelineVariable` is used as a parameter value, `call_immediate` will be `false`. This allows it to be used as a [dynamic trial parameter](/overview/dynamic-parameters). When `jsPsych.timelineVariable` is used inside of a function, `call_immediate` will be `true`. It is possible to explicitly set this option to `true` to force the function to immediately return the current value of the timeline variable. ### Return value Either a function that returns the value of the timeline variable, or the value of the timeline variable, depending on the context in which it is used. See `call_immediate` description above. ### Description [Timeline variables](/overview/timeline/#timeline-variables) are a powerful technique for generating experiments with repetitive procedures but different parameter values. This function fetches the current value of a particular timeline variable. It must be used in conjunction with a timeline that has timeline variables. See the [timeline variable section](/overview/timeline/#timeline-variables) for details. ### Examples #### Standard use as a parameter for a trial ```javascript var trial = { type: jsPsychImageKeyboardResponse, stimulus: jsPsych.timelineVariable('image') } var procedure = { timeline: [trial], timeline_variables: [ {image: 'face1.png'}, {image: 'face2.png'}, {image: 'face3.png'}, {image: 'face4.png'} ] } ``` #### Invoking immediately in a function ```javascript var trial = { type: jsPsychHtmlKeyboardResponse, stimulus: function(){ return "