API - Gorilla


Overview


Welcome to the Gorilla API Guide.

Explore the list of available functions in the menu on the left.

Overview


This section contains functions that are accessible in either the task builder scripting tools or the code editor. To invoke any of them, they must be proceeded by gorilla.

gorilla is a Javascript file that contains a set of functions for interacting with Gorilla and its systems. In the Task Builder and Questionnaire Builder, the gorilla file is provided for you by default, along with useful packages and tools like jQuery and Bootstrap. In the Code Editor, the gorilla file must be added to the code manually by using the import function. Please see the Code Editor section for more information.

.ready()


.ready(f: function)

gorilla.ready accepts a function to be run when the page is loaded and ready to accept data. This is a drop in replacement for $(document).ready. Here you could begin building the various pages and their functionality.

Example

gorilla.ready( startFunc() => { 

    //code to intialise task

});

.run()


.run(cb: () => any)

gorilla.run should be called to indicate the start of the task. It takes as an argument a callback to be run once the start process has finished. This call must be made before beginning the task!

metric()


.metric(results: any, key: string = '' ): any

The metric() function should be called to upload a metric to the main data server.


Arguments

The metric() function takes two arguments, only the first of which is mandatory.

  1. [Mandatory] results, a dictionary (an object of key-value pairs) of metrics
  2. [Optional] key, a string used as an identifier for the specific row of metrics being uploaded

The function has no return value.

The results argument must consist of a dictionary where the keys are known to Gorilla. In the Task Builder, these must be chosen from a preassigned list of available keys which are listed here (list). In the Code Editor, these must be chosen from the list of keys created in the Metrics tab of your code task.

The key argument, if provided, is attached to the metric and can be used to retrieve it later if this specific metric is required during runtime for analysis. For example, you may choose to vary the difficulty of a task based on in-task performance or end a task early under certain circumstances. In practice, if you are uploading metrics manually, there are usually better ways to achieve this functionality.


Usage example

gorilla.metric({
    reaction_time: reactionTimeValue,
    answer: userResponse
});

In the example above, only the first argument is given to the metric function. This consists of a dictionary of two key-value pairs. Both of the keys: reaction_time and answer are keys available in the task builder and their corresponding values will appear in the Reaction Time and Answer columns in the data download. If this code was used in the Code Editor, the keys would need to be setup in the Metrics tab along with the desired headers for the spreadsheet columns.

Click to view a Demo of using gorilla.metric to upload to your metrics additional information on video play count and duration.

manipulation()


.manipulation(name: string, def?: any)

The manipulation() function should be called to retrieve a manipulation set before the task was run.


Arguments

The manipulation() function takes two arguments: only the first is mandatory.

  1. [Mandatory] name, a string identifying the manipulation
  2. [Optional] def, a default value to give the manipulation

The function returns either the value of the manipulation or the value of def (if def has been set).

The name argument is a string used as a key to access the manipulation from storage. It must be identical to the key assigned to the manipulation in either the Task Builder or the Code Editor under the Manipulations tab.

In the event that a manipulation stored under the provided key cannot be found, or if the manipulation has not been given a setting, the value of def will be returned. def is short for 'default'. If def is not set, the function will return null. Setting a default is useful in cases where you may not always set the manipulation directly and want some default behaviour to occur.


Usage example

var NoOfTrials = gorilla.manipulation('noOfTrial', 20);

The name 'noOfTrials' would be set in the 'manipulations' tab of the Code Editor or Task Builder. In the event that the manipulation associated with 'noOfTrial' has not been set, the default (def) value of 20 will be returned. The return value of manipulation is, in the example above, assigned to the variable NoOfTrials.

store()


.store(key:string, value:any, global?:boolean)

The store() function should be called to add information either to the task/questionnaires data storage or to the experiments data storage. This storage is unqiue to the participant currently logged into the experiment and only that participant. It could be used to store a participants progress through a task, so there progress can be resumed if they refresh the page. Or, it could be used to store a participants performance so they can be branched in a later part of an experiment.

This storage persists across experiment logins. If your experiment contains multiple phases, requiring participants to login and take part across multiple days, the same storage will be used. For example, if your experiment consisted of a multi-day training study, where each day the difficulty of a task was altered based on the previous days performance, you could use the experiment wide storage to keep track of their performance across days and alter the challenge of the task accordingly.


Arguments

The store() function takes three arguments, of which the first two are mandatory.

  1. [Mandatory] key, a string to uniquely identify the stored information
  2. [Mandatory] value, the value to be stored
  3. [Optional] global, a boolean to indicate the stored information's accessibility level in the experiment

The function has no return value.

The key argument is a string use to uniquely identify the stored information within its current accessibility level (indicated by the optional global variable). This string will be used in the companion function retrieve() to retrieve the stored information later.

The value argument is the value to be stored under the given key. This value can be of any variable type: number, string, boolean or object. When using the companion function retrieve(), the returned value will be of the same type as the originally stored value.

The global argument is an optional argument which indicates the stored information accessibility level. By default, the value for this argument is false, which means the data is stored locally. Locally stored data is only available in the task or questionnaire in which it was stored. This is useful for storing variables that relate to a specific instance of a task but aren't required outside of that task. This could be a progress tracker, that allows the participant to resume where they were if they have to refresh the page. Our a counter that keeps track of the participants score in a task.

However, the data stored under the key won't be available at the experiment level nor in other tasks i.e. it couldn't be used in a Branch node. Further, the data won't persist between instances of the same task. So, for the last example, if the participants score needed to be used in other parts of the experiment or in other instances of the same task, it would not be appropriate to store it locally.

Conversely, if the global argument is given the value of true, the stored data will be available globally. The key can be used to access and alter the stored data from anywhere in your experiment and the stored values will persist across the whole experiment. The most common use case for using globally stored data is for experiment tree branching based on a participants performance in a task.

Either local or global, data is stored on a participant by participant basis. As a participant takes part in an experiment, any data stored is associated uniquely with them. As a result, if the participant were to leave the experiment and then log back in as the same participant i.e. using their unique recruitment link or participant ID, the experiment would have access to their uniquely stored information. This can be very useful for longitudinal studies, where participants have to log in multiple times across a number of days/weeks/months etc.


Usage example

gorilla.store('correctAnswers', 15, true);

In the example above, all three of the available arguments are used. We store the value 15 under the key 'correctAnswers' with a global setting of true. This means that, using 'correctAnswers', we can access 15 from anywhere in our experiment.

Click to view a Demo of using store() to store the current running total of a participants current score. This example also demonstrates the companion function retrieve().

retrieve()


.retrieve(key:string, default?:any, global?:boolean)

The retrieve() function should be called to retrieve any information for either the task/questionnaires data storage or from the experiments data storage. This storage is unqiue to the participant currently logged into the experiment and only that participant. It could be used to store a participants progress through a task, so there progress can be resumed if they refresh the page. Or, it could be used to store a participants performance so they can be branched in a later part of an experiment.

This storage persists across experiment logins. If your experiment contains multiple phases, requiring participants to login and take part across multiple days, the same storage will be used. For example, if your experiment consisted of a multi-day training study, where each day the difficulty of a task was altered based on the previous days performance, you could use the experiment wide storage to keep track of their performance across days and alter the challenge of the task accordingly.


Arguments

The retrieve() function takes three arguments, of which only the first is mandatory.

  1. [Mandatory] key, a string that uniquely identifies the stored information
  2. [Optional] default, a value to return in the event that there is no value assigned to the current key or the key cannot be found
  3. [Optional] global?, a boolean to indicate the stored information's accessibility level in the experiment

The function returns either the value found or the value of default

The key argument is a string that identifies the information that is to be retrieved at the current accessibility level (indicated by the optional global variable). The key is also used in the companion function store() to store information.

The default argument can take a value of any type and indicates the information that should be returned in the event that the given key cannot be found in the datastore. If no default is given, the function will return null.

The global argument is an optional argument which indicates the stored information accessibility level. By default, the value for this argument is false, which means the data is stored locally. Locally stored data is only available in the task or questionnaire in which it was stored. This is useful for storing variables that relate to a specific instance of a task but aren't required outside of that task. This could be a progress tracker, that allows the participant to resume where they were if they have to refresh the page. Our a counter that keeps track of the participants score in a task.

However, the data stored under the key won't be available at the experiment level nor in other tasks i.e. it couldn't be used in a Branch node. Further, the data won't persist between instances of the same task. So, for the last example, if the participants score needed to be used in other parts of the experiment or in other instances of the same task, it would not be appropriate to store it locally.

Conversely, if the global argument is given the value of true, the stored data will be available globally. The key can be used to access and alter the stored data from anywhere in your experiment and the stored values will persist across the whole experiment. The most common use case for using globally stored data is for experiment tree branching based on a participants performance in a task.

Either local or global, data is stored on a participant by participant basis. As a participant takes part in an experiment, any data stored is associated uniquely with them. As a result, if the participant were to leave the experiment and then log back in as the same participant i.e. using their unique recruitment link or participant ID, the experiment would have access to their uniquely stored information. This can be very useful for longitudinal studies, where participants have to log in multiple times across a number of days/weeks/months etc.


Usage example

var correct_answers = gorilla.retrieve('correctAnswers', 15, true);

In the example above, all three of the available arguments are used. Gorilla will look for information, stored at the experiment (global) level, associated with the key 'correctAnswer'. If this key is not found in the store then the default of 15 will be returned.

Click to view a Demo of using retrieve() to retrieve the current running total of a participants current score. This example also demonstrates the companion function store().

stimuliURL()


stimuliURL(name: string)

The stimuliURL() function returns the URL to a named stimuli, present in the task's (Task Builder or Code Editor) uploaded stimuli. In the Task Builder, the task builder zones themselves usually handle collecting stimuli url for display. In the Code Editor, or if you are manually building task elements in the Task Builder, the stimuliURL() function is required to retrieve the URL of the stimuli.


Arguments

The stimuliURL function take one mandatory argument.

  1. [Mandatory] name, a string which matches the full filename of an uploaded stimuli.

The function returns the URL to the given stimuli.

The name argument is a string which indicates the filename of the required stimuli. This must match the full filename exactly as it appears in the Stimuli tab of your task, including the file extension. If no stimuli is found matching the given name, the function will return null.


Usage example

var fileURL = gorilla.stimuliURL('instructions.txt');

In the example above, Gorilla will look for a stimuli called 'instructions.txt' and, if it is found, return its URL. This would allow us to, for example, create a download link for participants to download a set of instructions.

Click to view a Demo of using stimuliURL() to obtain the URL to a set of instructions uploaded to the task stimuli for use in creating an instructions download link.

shuffle()


shuffle(array: [], seed?: number)

The shuffle() function randomly shuffles the elements of an array.


Arguments

The shuffle() function takes two arguments, of which the first is mandatory.

  1. [Mandatory] array, an array containing elements of any type which is to be shuffle.
  2. [Optional] seed, a number to be used as the initialiser for the random number generator which will shuffle the array

The function returns an array, which is the original array following the shuffle.

The array argument must be an array, of any length. This array will then have its elements randomly shuffled into a different order.

The seed argument is an optional number which represents the seed that will be used to initialise the random number generator before shuffling the contents of array. By default, if no value for seed is given, Gorilla will use whatever random seed is currently set within the task. Providing this argument is useful for the cases where you which to guarantee the same shuffle each time. For instance, if you are randomly assigning new content to your task spreadsheet, or preparing a list of stimuli, you want to make sure you can retrieve the same list in the event that the user refreshes the page. This would, potentially, run all of your script/code logic again.


Usage example

var arrayToShuffle = [1, 2, 3, 4];
var shuffledArray = gorilla.shuffle(arrayToShuffle);

In the example above, Gorilla will take the array 'arrayToShuffle' and shuffle its contents. It will then return the array, and this will be assigned to the variable 'shuffledArray'.

Click to view a Demo of using shuffle() to shuffle a subset of trials into a random order, using the optional seed variable to preserve the shuffle within-participants.

.finish()


finish(overrideURL?: string)

The finish() function immediately ends the current task, marking it as complete. Gorilla will then move on to the next node in the experiment tree. Warning: Implement this function with care, as improper usage could significantly alter the participant experience.


Arguments

The finish() function takes a single, option argument.

  1. [Optional] overrideURL, a string indicating the URL to direct the participant to upon completing the function call

The function has no return value.

The overrideURL is an optional argument which takes a URL to direct the participant to after completing the finish call. The task will be marked as complete and the participant will be sent to the provided URL, rather than progressed through the experiment tree. Note that this will cause the participant to leave the current experiment and, even if the next node in the experiment would be the finish node, the participant will never be marked as complete, unless they are later directed back into the experiment. When using this function, consider whether you could use the onward URL functionality in the finish node to redirect the participant instead.


Usage example

gorilla.finish();

The task will immediately end when the above function is called, with no further trials or stimuli presented. As no overrideURL has been provided, the experiment will advance on to the next node in the experiment tree.

Click to view a Demo of using finish() to end the task following a threshold of incorrect answers in a row being reached.

Task Builder Script


This section contains hooks and functions that are accessible only in the Task Builder script tab. All of these must be proceeded by gorillaTaskBuilder in order to access them.

Note that some of these are hooks rather than functions. Hooks allow you to tap into existing functionality within Gorilla at specific points during a tasks execution. Using these hooks, you can add additional functionality that the task will run at these points. For instance, the hook onScreenStart allows you to access the screen just as a screen is being displayed. With it, you could alter the appearance of the screen, set up new response events or implement custom scoring.

Importantly, you can only define content for each hook ONCE in a given script. If you attempt to define multiple instances of onScreenStart, Gorilla will only use the last definition in the script file. The hooks available in the script allows you to register a function with the equivalent hook in Gorilla and you can at most only register one function per hook. Subsequent registrations will overwrite previous ones.

Each hook provides you with a set of information about the current task state. Some of the hooks expect you to return information back to Gorilla, such as preProcessSpreadsheet which allows you to alter the contents of the current spreadsheet.

To see Examples of using code in the Task Builder Script, check out the linked project!

.onScreenStart()


onScreenStart((spreadsheet: any, rowIndex: number, screenIndex: number, row: any, container: string) => {})

onScreenStart is a hook that is run when a new screen is loaded and ready to start. Any code that you place in the onScreenStart hook will be executed only when a new screen starts.


Provided variables

onScreenStart provides you with five variables.

  1. spreadsheet, an array of objects containing the entire contents of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet.
  2. rowIndex, a number, the current index of the spreadsheet the task is on
  3. screenIndex, a number, the index for the current screen within the current display
  4. row, an object, containing the information just from the current row of the spreadsheet being used to populate this screen
  5. container, a string, a key that identifies the current html container for the screen

The function expects no return values.

The spreadsheet is an array of all of the rows of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet, expressed as an object.

The rowIndex is a number indicating which row of the spreadsheet the task is currently on. This conforms to standard notation in relation to arrays (and numbering schemes in general) in Javascript i.e. rowIndex = 0 represents the first elements in the spreadsheet array.

The screenIndex is a number indicating which screen of the current display the task is currently on. This also conforms to the standard numbering scheme in that screenIndex = 0, indicates the first screen of the display.

The row is an object containing just the information in the current row of the spreadsheet being used to display this screen.

The container is a string which can be used in jQuery requests to uniquely identify the contents of the current screen. Gorilla uses a lookahead system that prepopulates future content in hidden containers on the screen. The container string allows you to select the container currently being used for the screen. This should always be used in jQuery selections that are used to make sure you are collecting elements from the currently presented screen only.


Example usage

gorillaTaskBuilder.onScreenStart((spreadsheet: any, rowIndex: number, screenIndex: number, row: any, container: string) => {
   if(row.display == 'task'){
        if(screenIndex == 0){
            var htmlToShow = '<h3>You are on the first screen of the task display</h3>';
            $(container + '.answer-list').html(htmlToShow);
        }
    }
});

In the example above, in the onScreenStart hook, we check to see if the display of the current row matches the string 'task'. Next, we check if the current screenIndex is 0. If both of these return true, we create a string which we then add as html to an element on the screen that we have given the class 'answer-list'. We use the container string to make sure we only select the 'answer-list' element present in the container for the current screen and not any containers that have been prepared (and hidden) by the lookahead.

If you are more familiar with Javascript then you will recognise the notation above for onScreenStart. Simplified this is

gorillaTaskBuilder.onScreenStart((variables) => {
    // function body
});

The () => {} notation is a shorthand method for expressing a function in Javascript. So, the onScreenStart hook is creating a function, with the set of arguments described above (for which Gorilla automatically provides the values) but where you define the function body.

Click to view a Demo of using onScreenStart to check if the participants browser is in fullscreen mode.

.onScreenFinish()


onScreenFinish((spreadsheet: any, rowIndex: number, screenIndex: number, row: any, container: string, correct: boolean) => {})

onScreenFinish is a hook that is executed when a screen finishes, before loading the next screen in the display. This occurs after participant input has been received, a timeout has triggered or any other effect that results in the screen transitioning. Importantly, this occurs after the correct answer processing - at this stage you know whether or not the participants response has been recorded as correct or incorrect.


Provided variables

onScreenFinish provides you with six variables. The first five are the same as those for the onScreenStart hook. The sixth is new and unique to this hook.

  1. spreadsheet, an array of objects containing the entire contents of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet.
  2. rowIndex, a number, the current index of the spreadsheet the task is on
  3. screenIndex, a number, the index for the current screen within the current display
  4. row, an object, containing the information just from the current row of the spreadsheet being used to populate this screen
  5. container, a string, a key that identifies the current html container for the screen
  6. correct, a boolean, the participants answer marked as either correct (true) or incorrect (false)

The function expects no return values.

The spreadsheet variable is an array of all of the rows of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet, expressed as an object.

The rowIndex variable is a number indicating which row of the spreadsheet the task is currently on. This conforms to standard notation in relation to arrays (and numbering schemes in general) in Javascript i.e. rowIndex = 0 represents the first elements in the spreadsheet array.

The screenIndex variable is a number indicating which screen of the current display the task is currently on. This also conforms to the standard numbering scheme in that screenIndex = 0, indicates the first screen of the display.

The row variable is an object containing just the information in the current row of the spreadsheet being used to display this screen.

The container variable is a string which can be used in jQuery requests to uniquely identify the contents of the current screen. Gorilla uses a lookahead system that prepopulates future content in hidden containers on the screen. The container string allows you to select the container currently being used for the screen. This should always be used in jQuery selections that are used to make sure you are collecting elements from the currently presented screen only.

The correct variable is a boolean which indicates whether the participants response on the screen was marked as correct or incorrect. If it was marked as correct, the correct variable will be true. If it was marked as incorrect, the correct variable will be false. For screens where there is no response to mark, the default value is false.


Example usage

var participantPoints: number = 0;

gorillaTaskBuilder.onScreenFinish((spreadsheet: any, rowIndex: number, screenIndex: number, row: any, container: string, correct: boolean) => {
   if(row.display == 'task'){
        if(screenIndex == 1){
            if(correct){
                participantPoints += 5;
            } else {
                participantPoints += 1;
            }
        }
    }
});

In the example above, we begin by defining a new variable which we'll use to store the number of points a participant has scored. Then, in the onScreenFinish hook, we check to see if the display of the current row matches the string 'task'. Next, we check if the current screenIndex is 1. Finally, we then check the value of correct. If correct is true, the participant got the answer correct, and we award them 5 points. Otherwise, the participant got the answer wrong, so we award them only 1 point.

If you are more familiar with Javascript then you will recognise the notation above for onScreenFinish. Simplified this is

gorillaTaskBuilder.onScreenFinish((variables) => {
    // function body
});

The () => {} notation is a shorthand method for expressing a function in Javascript. So, the onScreenFinish hook is creating a function, with the set of arguments described above (for which Gorilla automatically provides the values) but where you define the function body.

Click to view a Demo of using onScreenFinish to check if a participant has made multiple incorrect answers in a row.

.preProcessSpreadsheet()


preProcessSpreadsheet((spreadsheet: any) => {})

preProcessSpreadsheet is a hook that is executed before the contents of the task spreadsheet have been processed by Gorilla when executed a task. Particularly, this hook is run before Gorilla has carried out any randomisation based on the randomise_trials and randomise_blocks columns in the task spreadsheet. This hook allows you to interact with the uploaded spreadsheet, altering it in ways that may not be accessible using the GUI tools. You could use to randomly assign trials to one of two (or more) possible stimuli presentations. You could select a subset of trials from the whole spreadsheet. Or, you could alter the whole structure of the spreadsheet to change the task presentation on a per participant basis.


Provided variables

preProcessSpreadsheet provides you with one variable.

  1. spreadsheet, an array of objects containing the entire contents of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet.

The function expects a return value which takes the same form as the spreadsheet variable: an array of objects where each element represents a single row of the spreadsheet.

The spreadsheet variable is an array of all of the rows of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet, expressed as an object.


Example usage

gorillaTaskBuilder.preProcessSpreadsheet((spreadsheet: any) => {

    var count: number = 1;
    for(var i = 0; i < spreadsheet.length; i++){
        if(spreadsheet[i].Word && spreadsheet[i].Word != 'Break'){
            spreadsheet[i].Word += ' (was ' + count + ', ';
            count++;
        }
    }
    
    return spreadsheet;
});

In the example, (which is taken from the demo linked at the bottom of this page), we begin by defining a new variable, count, which we'll use to store the number of trials (that satisfy certain conditions). In the for loop, we then go through element of the spreadsheet. For each element, which represents a single spreadsheet row, we look to see if the column Word exists in that row. If it does and if the entry in that column isn't 'Break', we append some text to that columns entry in the row.

After we have completed the loop, we then return the amended spreadsheet to Gorilla.

If you are more familiar with Javascript then you will recognise the notation above for preProcessSpreadsheet. Simplified this is

gorillaTaskBuilder.preProcessSpreadsheet((variables) => {
    // function body
});

The () => {} notation is a shorthand method for expressing a function in Javascript. So, the preProcessSpreadsheet hook is creating a function, with the set of arguments described above (for which Gorilla automatically provides the values) but where you define the function body.

Also, to access each column in a row, we use the same dot notation that has been discussed before for variables such as row in onScreenStart. For example, if our spreadsheet has a column 'display' (which generally all spreadsheets should have!) we can access it from the spreadsheet variable with

spreadsheet[0].display

This will retrieve the value in the 'display' column for the first row of the spreadsheet. Note also that the order of rows in the spreadsheet array will match the order of rows in the uploaded spreadsheet, as viewed from the 'Spreadsheet' tab.

Click to view a Demo of using preProcessSpreadsheet to label some text in a trial with the trials original position in the spreadsheet, before randomisation.

.postProcessSpreadsheet()


postProcessSpreadsheet((spreadsheet: any) => {})

postProcessSpreadsheet is a hook that is executed after the contents of the task spreadsheet have been processed by Gorilla when executed a task. Particularly, this hook is run after Gorilla has carried out any randomisation based on the randomise_trials and randomise_blocks columns in the task spreadsheet. This is the only difference between this and the preProcessSpreadsheet hook. Otherwise, the functionality and purpose remain the same.


Provided variables

postProcessSpreadsheet provides you with one variable.

  1. spreadsheet, an array of objects containing the entire contents of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet.

The function expects a return value which takes the same form as the spreadsheet variable: an array of objects where each element represents a single row of the spreadsheet.

The spreadsheet variable is an array of all of the rows of the current spreadsheet being used to run the task. Each element of the array is a single row of the spreadsheet, expressed as an object.


Example usage

gorillaTaskBuilder.postProcessSpreadsheet((spreadsheet: any) => {

    var count: number = 1;
    for(var i = 0; i < spreadsheet.length; i++){
        if(spreadsheet[i].Word && spreadsheet[i].Word != 'Break'){
            spreadsheet[i].Word += ' now ' + count + ')';
            count++;
        }
    }
    
    return spreadsheet;
});

In the example, (which is taken from the demo linked at the bottom of this page), we begin by defining a new variable, count, which we'll use to store the number of trials (that satisfy certain conditions). In the for loop, we then go through element of the spreadsheet. For each element, which represents a single spreadsheet row, we look to see if the column Word exists in that row. If it does and if the entry in that column isn't 'Break', we append some text to that columns entry in the row.

After we have completed the loop, we then return the amended spreadsheet to Gorilla.

If you are more familiar with Javascript then you will recognise the notation above for preProcessSpreadsheet. Simplified this is

gorillaTaskBuilder.preProcessSpreadsheet((variables) => {
    // function body
});

The () => {} notation is a shorthand method for expressing a function in Javascript. So, the preProcessSpreadsheet hook is creating a function, with the set of arguments described above (for which Gorilla automatically provides the values) but where you define the function body.

Also, to access each column in a row, we use the same dot notation that has been discussed before for variables such as row in onScreenStart. For example, if our spreadsheet has a column 'display' (which generally all spreadsheets should have!) we can access it from the spreadsheet variable with

spreadsheet[0].display

This will retrieve the value in the 'display' column for the first row of the spreadsheet. Note also that the order of rows in the spreadsheet array will not match the order of rows in the uploaded spreadsheet, as viewed from the 'Spreadsheet' tab. This is because this hook is run after Gorilla has carried out any randomisation from the 'randomise_trials' and 'randomise_blocks' columns.

Click to view a Demo of using preProcessSpreadsheet to label some text in a trial with the trials new position in the spreadsheet, after randomisation.

.forceAdvance()


forceAdvance(correctAnswer: boolean, isTimeout: boolean)

forceAdvance is a function that allows you to force the task to advance on to the next screen in display. If the current screen is the last in the display, then Gorilla will move to the next row in the spreadsheet. This function is generally used when implementing custom logic for controlling the progression of the task. For example, you may want to advance the screen after displaying your own content to the screen that you are handling outside of Gorilla's zone system. Or, you could be implementing a variable time-limit system where you dynamically alter the time-limit on screens based on whether the previous trial was answered correctly or incorrectly.


Arguments

The forceAdvance() function takes two arguments, both of which are optional.

  1. [Optional] corrrectAnswer, a boolean that indicates whether the answer given on the screen should be marked as correct (true) or incorrect (false)
  2. [Optional] isTimeout, a boolean that indicates whether the forceAdvance was triggered as part of timeout, such as from an expired timelimit

The default value for both of these arguments is false.

As the forceAdvance() function allows you to subvert the usual process for advancing a screen, answers will not be collected from the screen (except for passive responses). Using the correctAnswer argument, you can implement your own system for scoring trials where forceAdvance is used. For example, you could use forceAdvance() in a variable time-limit Go/NoGo and use the correctAnswer variable to indicate whether the forceAdvance() triggering indicates a correct or incorrect answer.


Example usage

gorillaTaskBuilder.forceAdvance(true, false);

In the example code, the forceAdvance function is called with the correctAnswer variable set to 'true' and the isTimeout variable set to 'false'. These values will be passed into the metric uploaded for this trial and placed in the appropriate columns.

The moment this line of code is reached, the task will advance to the next screen in the display (or the next row in the spreadsheet.) This action is irreversible.

Note that the forceAdvance() function will have no effect in the onScreenFinish hook: at this point, we are already advancing the screen and have already resolved whether the answer was correct/incorrect and whether it resulted from a timeout. Further, forceAdvance() will have no effect in the preProcessSpreadsheet, postProcessSpreadsheet and onGetSpreadsheetRow hooks. These hooks are trigged outside of the task screen display system.

Click to view a Demo of using forceAdvance() manually advance the screen after requesting the user enter full-screen mode in their desktop browser.