# jsPsych.pluginAPI The pluginAPI module contains functions that are useful when developing new plugins. --- ## jsPsych.pluginAPI.cancelAllKeyboardResponses ``` jsPsych.pluginAPI.cancelAllKeyboardResponses() ``` ### Parameters None. ### Return value Returns nothing. ### Description Cancels all currently active keyboard listeners created by `jsPsych.pluginAPI.getKeyboardResponse`. ### Examples ```javascript jsPsych.pluginAPI.cancelAllKeyboardResponses(); ``` --- ## jsPsych.pluginAPI.cancelKeyboardResponse ``` jsPsych.pluginAPI.cancelKeyboardResponse(listener_id) ``` ### Parameters Parameter | Type | Description ----------|------|------------ listener_id | object | The listener_id object generated by the call to `jsPsych.pluginAPI.getKeyboardResponse`. ### Return value Returns nothing. ### Description Cancels a specific keyboard listener created by `jsPsych.pluginAPI.getKeyboardResponse`. ### Examples ```javascript // create a persistent keyboard listener var listener_id = jsPsych.pluginAPI.getKeyboardResponse(after_response, ['p','q'], 'date', true); // cancel keyboard listener jsPsych.pluginAPI.cancelKeyboardResponse(listener_id); ``` --- ## jsPsych.pluginAPI.enforceArray ``` jsPsych.pluginAPI.enforceArray(params, possible_arrays) ``` ### Parameters Parameter | Type | Description ----------|------|------------ params | object | An object of `key: value` pairs. possible_arrays | array | Array of strings where each string is a key from `params` indicating which `keys` should have arrays as the `value`. ### Return value Returns a copy of `params` where all of the `keys` in `possible_arrays` are guaranteed to be arrays. ### Description This function checks if specified parameters are arrays. If they are not arrays, then it converts them to arrays. Practically, this is used for cases where a plugin calls for an array, but a single value is also a reasonable option. An example would be specifying a stimulus for the `single-stim` plugin. Technically, the plugin requires the stimuli to be specified in an array. Each element of the array is then given its own trial. However, a single element array to present one trial is possible. This function means that users can declare the single element array as either an array or just the value that would be the element in the array. ### Examples ```javascript // a snippet from the text plugin plugin.create = function(params) { params = jsPsych.pluginAPI.enforceArray(params, ['text','data']); // other stuff here ... }; ``` --- ## jsPsych.pluginAPI.getKeyboardResponse ``` jsPsych.pluginAPI.getKeyboardResponse(callback_function, valid_responses, rt_method, persist) ``` ### Parameters Parameter | Type | Description ----------|------|------------ callback_function | function | The function to execute whenever a valid keyboard response is generated. valid_responses | array | An array of key codes or character strings representing valid responses. Responses not on the list will be ignored. An empty array indicates that all responses are acceptable. rt_method | string | Indicates which method of recording time to use. The `'date'` method uses calls to `(new Date()).getTime()` to record timing information. The `'performance'` method uses calls to `performance.now()`, which is a more modern JavaScript feature. The `'performance'` approach is [not supported by all the major browsers yet](http://caniuse.com/#search=performance), but adoption rates are increasing. persist | boolean | If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by `jsPsych.pluginAPI.cancelKeyboardResponse` or `jsPsych.pluginAPI.cancelAllKeyboardResponses`. ### Return value Return an object that uniquely identifies the keyboard listener. This object can be passed to `jsPsych.pluginAPI.cancelKeyboardResponse` to cancel the keyboard listener. ### Description Gets a keyboard response from the subject, recording the response time from when the function is first called until a valid response is generated. A valid response triggers the `callback_function` specified in the parameters. A single argument is passed to the callback function. The argument contains an object with the properties `key` and `rt`. `key` contains the numeric key code of the response, and `rt` contains the response time. ### Examples #### Get a single response from any key ```javascript var after_response = function(info){ alert('You pressed key '+info.key+' after '+info.rt+'ms'); } jsPsych.pluginAPI.getKeyboardResponse(after_response, [], 'date', false); ``` #### Get a responses from a key until the letter Q is pressed ```javascript var after_response = function(info){ alert('You pressed key '+info.key+' after '+info.rt+'ms'); if(info.key == 81){ // the key code for 'Q' is 81. jsPsych.pluginAPI.cancelKeyboardResponse(listener); } } var listener = jsPsych.pluginAPI.getKeyboardResponse(after_response, [], 'date', true); ``` --- ## jsPsych.pluginAPI.evaluateFunctionParameters ``` jsPsych.pluginAPI.evaluateFunctionParameters(trial, protect) ``` ### Parameters Parameter | Type | Description ----------|------|------------ trial | object | An object representing the trial (typically the same variable that gets passed to the `plugin.trial` method). It contains `key: value` pairs describing all the trial parameters. protect | array | An array of strings, indicating which parameters in the `trial` object should be protected from normalization ### Return value Returns a new trial object with all values that were functions replaced by the return value of the function. ### Description This method replaces any parameters that are functions with the output of the function. ### Example ```javascript // a snippet from a trial method plugin.trial = function(display_element, trial) { trial = jsPsych.pluginAPI.evaluateFunctionParameters(trial); // the rest of the trial code... } ```