You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
This page contains a full listing of all the scripts available in the Task Builder Script Examples Project. Each entry includes a link to the script and brief description of its functionality. This includes some background on the use case the script was developed for where relevant. It also lists the key functions or Hooks used in the script and the concepts it addresses, such as uploading metrics, changing zone behaviour, or changing spreadsheet contents.
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section involve altering existing content within the Gorilla Task Builder.
Scripts that change the background colour or the colour of text, change how buttons are interacted with or how zones display are included in this section.
Changing Background Colour and Text
The script in this task changes the background colour in the whole task to Black and the text colour to White.
Uses: onScreenStart
Concepts: changing task appearence
Changing Background Colour for Selected Displays
The script in this task changes the background colour for selected displays only. Other displays will remain the default colour.
Uses: onScreenStart
Concepts: changing task appearence, selected displays and screens
This script changes the background of your displays to an image that will be displayed throughout your task.
Uses: onScreenStart
Concepts: changing task appearence, adding and scaling a background image
Add Recent Answer Image to Screen
The script in this task dynamically adds the recently selected answer to the screen. When a participant selects an incorrect answer, from a set of multiple options, they are presented with that same answer again on an incorrect answer screen, so they are reminded of the answer they chose.
Note: this can now be done without scripting in Task Builder 2 by binding an Image component to a stored response. See the Task Builder 2 Binding Guide for more information.
Uses: onScreenStart, retrieve, stimuliURL
Concepts: changing zone functionality, dynamic feedback
The script in this task sets an audio zone to play after a short delay, rather than immediately or on the click of a play button. This works by overriding the existing play button functionality and adding in a short delay before triggering the play button functionality via the script. IMPORTANT NOTE: Autoplay restrictions may prevent this functionality from working on some browsers/devices.
Note: this can now be done without script in Task Builder 2 by adding a Trigger - Active component to an Object with an Audio component.
Uses: onScreenStart
Concepts: changing zone functionality, manually triggering zone functionality, adding a timeout
The script in this task change the Audio Zone to be triggered via a spacebar press rather than a button press. It hides the play button and adds a keyboard response (the spacebar) to manually trigger the original play buttons functionality IMPORTANT NOTE: Autoplay restrictions may prevent this functionality from working on some browsers/devices.
Uses: onScreenStart
Concepts: changing zone functionality, manually triggering zone functionality, adding keypress detection
The script in this task changes the Video Zone to be triggered via a spacebar press rather than by clicking on the video. It hides the play button and adds a keyboard response (the spacebar) to manually trigger the original play buttons functionality.
Uses: onScreenStart
Concepts: changing zone functionality, manually triggering zone functionality, adding keypress detection
This script demonstrates using onScreenStart and css to change the visibility of zones for a fixed duration at the start of a screen.
Note: this can now be done without script in Task Builder 2 using the Trigger - Visible component.
Uses: onScreenStart, addTimerSequence
Concepts: changing zone functionality, adding timer sequence
The script in this task fixes an image to a fixed number of pixels, adjusting the images position on the new screen to be optimal for its new size. IMPORTANT NOTE: As the physical size of a pixel varies depending on screen size and resolution this script WILL NOT present the same size image across all participants. If this is the functionality you require, you should look at the Screen Calibration zone
Note: this can now be done without script in Task Builder 2 using the Advanced Positioning component.
Uses: onScreenStart, refreshLayout
Concepts: changing zone content, changing image appearence
The script in this task forces a video to play in fullscreen, returning the screen to normal when the video has finished.
Uses: onScreenStart, onScreenFinish
Concepts: changing zone content, fullscreen
Reset Embedded Data (Source: Static)
The script in this task shows how to reset the answer Embedded Data from the Task Builder - the embedded data available in the Active Response - Embedded data settings. The keys for the embedded data are static within the task and are hardcoded into the script. This script is useful for the case where a participant repeats a task multiple times, with the goal of achieving a certain percentage of correct answers in order to progress, for example. If you want to discount the result from the previous iteration (i.e. have them start with a clean slate each time) you will need to reset the embedded data between task runs.
Note: This can now be achieved in Task Builder 2 without additional scripting. Use the Set Field on Start to control the value saved to the Store at the beginning of a task.
Uses: store, retrieve
Concepts: resetting embedded data
Reset Embedded Data (Source: Manipulation)
The script in this task shows how to reset the answer Embedded Data from the Task Builder - the embedded data available in the Active Response - Embedded data settings. The keys for the embedded data are drawn from manipulations, which the screen collects and the creates the appropriate keys for, before reseting the values for the embedded data back to zero. This script is useful for the case where a participant repeats a task multiple times, with the goal of achieving a certain percentage of correct answers in order to progress, for example. If you want to discount the result from the previous iteration (i.e. have them start with a clean slate each time) you will need to reset the embedded data between task runs.
Note: This can now be achieved in Task Builder 2 without additional scripting. Use the Set Field on Start to control the value saved to the Store at the beginning of a task.
Uses: store, retrieve, manipulation
Concepts: collecting manipulation values, resetting embedded data
The script in this task creates a custom scoring system based on the participants chose of urn and the colour ball they draw. Within the spreadsheet, the result of the draw, the number of points awarded and the award text are predefined. We use the advanced branching settings to mark a Red Urn choice as a 'correct' answer, sending them to a screen which links to the Red Urn choice, with the Green Urn marked as the 'incorrect' answer and the participant sent to the Green Urn screen. Within the script, we use what screen we are on to decided if we should use the Red Urn or Green Urn data, update some embedded data to store the total score and update the text on the screen accordingly.
Note: this can now be done without script in Task Builder 2 using the Save Data On Response component.
Uses: onScreenStart, store, retrieve
Concepts: changing zone content, dynamic feedback, adding text to the screen, using embedded data, custom scoring
Delay Space-to-Continue Action
The script in this task delays the action of the space to continue zone (advancing the screen) by a predefined amount of time. This is useful when using any of the Audio-Visual recording zones, to make sure the data-stream is flushed before the screen moves on. Otherwise, some of the participants response may be cut off. This is achieved through a combination onScreenStart and the jQuery _data object to access the current Gorilla function assigned to the Space to Continue zone and add in additional functionality.
Uses: onScreenStart, setTimeout, jQuery
Concepts: changing zone functionality, accessing event listeners and handlers through jQuery
The script in this task delays the action of the Continue Button zone (advancing the screen) by a predefined amount of time. This is useful when using any of the Audio-Visual recording zones, to make sure the data-stream is flushed before the screen moves on. Otherwise, some of the participants response may be cut off. This is achieved through a combination onScreenStart and the jQuery _data object to access the current Gorilla function assigned to the Continue Button zone and add in additional functionality.
Note: this can now be done without script in Task Builder 2 using the Trigger - Active component.
Uses: onScreenStart, setTimeout, jQuery
Concepts: changing zone functionality, accessing event listeners and handlers through jQuery
Convert Response Text to Number Field
The script in this task converts a normal input (Response Text) field into a number only field. This prevents participants from typing in any letters. Further, minimum and maximum values can be added - these will prevent the participant from advancing if the entered response is outside of this range. This is achieved through a combination onScreenStart and the jQuery _data object.
Note: This can now be achieved in Task Builder 2, without any additional scripting. See the Number Entry component for more information.
Uses: onScreenStart, setTimeout, jQuery, jQuery data object
Concepts: changing zone functionality, accessing event listeners and handlers through jQuery
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section involve adding additional content to a Task. Scripts that add additional custom scripted zones, completely new functionality and participant interactions are included in this section.
Adding Audio Element for Background Music
The script in this task adds an audio element to the main html page so background music can be played throughout the task.
Note: this can now be done without script in Task Builder 2 using the Background Audio component.
Uses: onScreenStart, stimuliURL, metric
Concepts: adding custom task content, uploading metrics
Adding Audio Element for Background Music On Click
The script in this task adds an audio element to the main html page so background music can be played throughout the task. However, the audio playing is triggered on a button click. This "should" allow us to reliably play the audio on devices where autoplay is restricted.
Uses: onScreenStart, stimuliURL, metric
Concepts: adding custom task content, uploading metrics
Adding Audio Element for Background Music On Click by Block
The script in this task adds an audio element to the main html page so background music can be played throughout the task. However, the audio playing is triggered on a button click. This "should" allow us to reliably play the audio on devices where autoplay is restricted. Further, the audio can be changed in each 'block' of the task
Uses: onScreenStart, stimuliURL, metric
Concepts: adding custom task content, uploading metrics
Link for Downloadable Instructions
The script in this task adds a link that allows the participant to download a set of instructions. The instructions are added to the task as a stimuli. The URL for the link is then generated in the script and presented onto the page.
Uses: onScreenStart, stimuliURL
Concepts: adding custom task content, retrieving stimuli
The script in this task demonstrates using the browsers fullscreen commands to require the participant to be in full screen mode before proceeding. The script has a FullscreenCheck screen where code is run to detect if the participant is in fullscreen mode. If they are not, a message is presented along with a button which, when pressed, will force the participant's browser window to full screen. The final step is important - the users browser window can only be forced into fullscreen following an action from the participant i.e. a button press. If you want the participant to view the task in fullscreen mode, place this check screen (or set it up as a seperate display) at intervals throughout your task. This way, the participant's fullscreen status can be checked regularly and corrected if necessary.
Uses: onScreenStart, forceAdvance
Concepts: adding custom task content, require fullscreen
Collect and Display Reaction Time
The script in this task collects the reaction time for the recent trial and then displays it on the next screen. It collects the reaction time using the stopwatch built into Gorilla and then manually adds the time to Rich Text zone. This allows you to give instant feedback to participants on their performance. You can adapt this script to store the reaction time across several trials and then display participants and average or range of RT values
Note: This can now be achieved without scripting in Task Builder 2. See the Save Reaction Time component component for more information.
Uses: onScreenFinish, onScreenStart, store, retrieve, readStopwatch, refreshLayout
Concepts: adding custom task content, collect reaction time, display text to screen
The script in this task briefly demonstrates how to combine the functionality create by multiple different scripts. The specific scripts combined are Audio on Spacebar Press and Metric on Screen Load.
Uses: onScreenStart, metric
Concepts: combine multiple scripts
Conditional Feedback with Scoring
The script in this task creates a custom scoring system based on the participants response and presents the score to the participant. It makes use of the advanced branching settings to send the participant to specific correct or incorrect answer.
Note: this can now be done without script in Task Builder 2 using the Save Data On Response component.
Uses: onScreenStart, retrieve, store
Concepts: custom scoring, creating embedded data
Display Participants PublicID in a Task
The script in this task collects the participants PublicID and displays it to the screen. You can use this is you need your participants to present their PublicID in a third party service. IMPORTANT NOTE: In any form of preview, the PublicID will be blank. You can only see this functionality in action in a real experiment.
Uses: onScreenStart
Concepts: adding custom task content, display text to screen, retrieving Public ID
The script in this task dynamically forms the users response following a button press. The participant is presented with an incomplete word and two text elements containing a letter, which have been altered to look and act like buttons. Pressing one of the buttons will fill the letter into the gap to complete the word. A hide response text zone on the screen stores the participants created response, so it can be submitted to the metrics when the screen ends.
Uses: onScreenStart
Concepts: adding custom task content, display text to screen, create custom buttons, save responses to metrics
Dynamic Slider with Custom Min and Max
The script in this task recreates the existing Task Builder slider. The minimum and maximum values of this slider vary based on the participants response in previous trials and a multiplicative factor.
Uses: onScreenStart, onScreenFinish, store, retrieve, slider
Concepts: adding custom task content, creating a slider, customising slider range, responding to participant actions
Dynamic Waiting Screen with Random Player Name
The script in this task creates a fake multiplayer-matching environment. The participant is placed in a fake lobby to matched with a random player chosen from a list of potential players. The lobby includes a loading spinner set to wait for a variable length of time. The player the participant is matched to is chosen from a list in a metadata column
Uses: preProcessSpreadsheet, onScreenStart, forceAdvance
Concepts: adding custom task content, fake multiplayer
The script in this task will upload a metric when the screen loads (at the beginning of the onScreenStart hook). If you need to know precisely how much time has passed since or during a stimuli presentation, you can use this additional metric to account for the time between screen loads. This is usually no more than a single frame.
Uses: onScreenStart, metric
Concepts: adding custom task content, uploading metrics
The script in this task uploads a metric upon each key press within a response text entry zone. The rationale behind developing this was to look at points and lengths of hesitation while creating a fake name or number. This was enabled for the researcher by recording each key press in the response text zone as a seperate metric, allowing the time between key presses to be calculated
Uses: onScreenStart, onScreenFinish
Concepts: adding custom task content, uploading metrics, binding key events
Naming Task with End Screen Recap
The script in this task uses the recent answer embedded data to store all of a participants responses. They are then entered into a custom text zone on the final task screen as a recap.
Uses: onScreenStart, onScreenFinish, retrieve, store
Concepts: adding custom task content, collecting embedded data, display text to screen
Probability Branching with forceAdvance
The script in this task uses the third argument of forceAdvance to branch participants to a different screen depending on their response and some component of probability/randomness. This can be used to fake a multiplayer environment. In the task, the participant has to chose a number of tokens to offer another player. Depending on the number of tokens offered, the player will either accept or reject the offer based on probability rules. The script collects the number of tokens offered when the participant presses the continue button and then, based on the rules, either branches them immediately or 'rolls a die' to determine if their offer is accepted or rejected.
Uses: onScreenStart, forceAdvance
Concepts: adding custom task content, custom branching, fake multiplayer
The script in this task builts a six by six grid of blank squares that can turned black one by one with a mouse click. The script was created for researcher who wanted participants to create patterns/shapes within this grid and then latter rate them on various features. The grid is setup with a limit on how many squares can be highlighted at a time. Once ready, the participant can press the continue button, which will save the created grid in embedded data, allowing it to be presented to the screen again in a latter display or in another task entirely. The task features two different spreadsheets for demonstration purposes - one just for collection and one for collection and presentation (showing the created grid back to the participant)
Uses: onScreenStart, onScreenFinish, store, retrieve
Concepts: adding custom task content, storing participant responses, creating embedded data
The script in this task presents a relational reasoning task where one of the options is highlighted by default. This script was created in response to a researcher who wanted to investigate how often users would change their response from a default or recommended response. The response options are images with are changed to look and behave like buttons using the script. The default response is highlighted in the script and the chosen response is saved to a response text entry zone hidden on the page. When the user submits their response, the value in the text entry zone is submitted to the metrics.
Uses: onScreenStart
Concepts: adding custom task content, creating buttons, storing participant responses
RR With Exit Condition Consecutive
The script in this task will cause the task to end early if the participant gets too many incorrect answers CONSECUTIVELY. Everytime a participant gets an answer wrong, we iterate the number of incorrect answers that have occured. If this reaches a threshold defined in the script, we terminate the task. However, if the participant gets a response correct, we reset the incorrect answer counter i.e. they have to get X answers incorrect in a row to be exited from the task.
Uses: onScreenFinish, store, retrieve, finish
Concepts: adding custom task behaviour, monitoring participant performance, ending the task
RR With Exit Condition Percentage
The script in this task will cause the task to end early if the participant gets an insufficient percentage of correct answers. We initially allow the task to run for ten trials and then check the percentage of correct answers. If this is below 50%, we terminate the task. After the first ten trials, we'll check this percentage on every trial, so as soon as the participant drops below 50% correct, the task will end.
Uses: onScreenFinish, store, retrieve, finish
Concepts: adding custom task behaviour, monitoring participant performance, ending the task
This script demonstrates using preProcessSpreadsheet, gorilla.retrieve and gorilla.metric to retrieve embedded data (performance scores), and add these to the participant metric spreadsheet.
Note: This can now be achieved in Task Builder 2 without any additional scripting. By default, in Task Builder 2, data saved to the Store will be automatically included in the task metrics.
Uses: onScreenStart, retrieve, metric
Concepts: storing participant responses, creating embedded data, adding saved embedded data to the participant metric spreadsheet
Store Slider Value and Redisplay
This script demonstrates using onScreenFinish, onScreenStart and the store and retrieve commands to collect a value from a slider on the page and save it as embedded data. The selected values (responses) are then redisplayed on another screen. See this script implemented in the context of a real experiment in this Gorilla Academy case study.
Note: this can now be done without script in Task Builder 2 using the Save Response component.
Uses: onScreenFinish, onScreenStart, retrieve
Concepts: storing participant responses, creating embedded data, displaying embedded data to participants within the same task
This script can be used to carry out a live count of the number of effort button presses and then store this to embedded data. The primary use cases for this would be if you wanted to reuse the effort button result in a later task or if you wanted to show live feedback on a participants progress towards their target, such as by populating a progress bar. In this particular script, we demonstrate how to collect data over three uses of the effort button and generate a value for the participants 'maximum effort'.
Uses: onScreenStart, onScreenFinish, store, metric
Concepts: storing participant responses, creating embedded data, storing embedded data, adding saved embedded data to the participant metric spreadsheet
Three Urn with Procedural Draw
The script in this task generates three Urns, each containing different proportions of white and black balls. The contents of each urn is then shuffled. On each trial, the participant selects an urn to draw from and the script populates the next screen with the appropriate colour ball from the chosen urn. The script keeps seperate indexes for each urn, so that the chose of ball chosen is not linked to the trial number but instead, on how many draws have already been made from the specific urn chosen. This is the limitation when creating this kind of functionality using only the spreadsheet and the script is intended to overcome this.
Uses: onScreenStart, onScreenFinish, store, retrieve, shuffle
Concepts: adding custom task content, randomising task content, responding to participant choices
Home Page with Response Storing
The script in this task creates a fake 'home page' like environment, with participants travelling back and forth between the home page and other pages. On the 'home page' the participant is presented with size animals they have to give a rating for. They can click on each animal to get more information on each animal. The animals are presented as images which have custom click functionality assigned to them. The click functionality triggers a forceAdvance where we use the third argument of forceAdvance to send the participant to the correct screen for the given animal. Participants can rate animals either on the main home page or on the sub pages, with the ratings carried over between them. Oh, and just so we're clear, Squirrels are the best. You rate them anything less than a hundred and we probably can't be friends in real life!
Uses: onScreenStart, onScreenFinish, forceAdvance
Concepts: adding custom task content, assigning custom zone behaviour, dynamic task branching
The script in this task creates a simple Psychomotor Vigilance Task with a number display that counts up from 0.000 s in a milliseconds increment. Using javascript's inbuilt setInterval function, we setup a callback function called every X ms which updates the chosen display with the elapsed time in seconds (fixed to three decimal places). On the participant triggering a response, their final time is displayed to the screen before advancing to the next iteration.
Uses: onScreenStart, onScreenFinish, setInterval
Concepts: adding custom task content, creating looping functionality, updating zone content dynamically
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section involve making simple alterations to the task spreadsheet prior to the task running. Scripts that randomise the contents of a column, select a random subset of trials or randomise the contents of columns within a row will be included here.
The script in this task demonstrates the usage of both preProcess and postProcessSpreadsheet. It was created as a demo task when the preProcess and postProcess hooks were first created and demonstrates the difference in usage. Specificially, preProcess runs before Gorilla's own randomisation whereas postProcess runs after
Uses: preProcessSpreadsheet, postProcessSpreadsheet
Concepts: changing the task spreadsheet
Change Spreadsheet Column per Iteration
The script in this task changes the column used for a stimuli set on each iteration of the task. When the task is places inside a repeat node, a different metadata column will be used on each iteration to populate the main set of stimuli
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: Changing the task spreadsheet, metadata columns, changing stimuli
The script in this task randomises the contents of four columns in the spreadsheet within a single row. The result is that the four possible pieces of text for four buttons on the screen appear in a random order. Note that this is randomises the contents of the buttons for each trial in the same way. For trial by trial randomisation, see the equivalent script in the advanced section.
Note: This can now be achieved in Task Builder 2 without additional scripting. See the Randomise Between Columns randomisation component for more information.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: Changing the task spreadsheet, randomise row contents, shuffling spreadsheet content
The script in this task randomises the contents of a full column in the spreadsheet. While randomise trials or randomise blocks will shuffle the ordering of rows, this script would allow you to shuffle the ordering of entries within a single column. This is useful if you have two columns of stimuli that need to be randomly paired for each participant. Use this script to randomise the contents of one of the columns and then allow randomise trials to randomise the presentation order of the other.
Note: this can now be done without script in Task Builder 2 using the Randomise Within Column component.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: Changing the task spreadsheet, randomise column contents, shuffling spreadsheet content
Randomise Fixation Cross and Timelimit(Screen)
The script in this task randomises the duration of a fixation cross and the timelimit screen, using two different methods. For the fixation cross, the duration for the fixation cross is drawn from a metadata column containing possible values, with the values assigned randomly on a trial by trial basis. For the Timelimit (Screen), we generate a random duration by perturbating around a mean value, where the mean and perturbation maximum is defined in the script.
Uses: preProcessSpreadsheet, store, retrieve, Math.random()
Concepts: Changing the task spreadsheet, generating random values, metadata columns
Randomise Stimuli to Conditions
The script in this task randomises the presentation of stimuli into one of two conditions: image or text. The spreadsheet for the task is populated with both an image and a word version of the stimuli for each row. The script will then assign trials to either an image condition, where we change the display name to in the trial to one that uses an image stimuli. Or, to a text condition, changing the display name in the trial to one that uses the text stimuli. The assignment is made with a 70% probability that a trial will be assigned to the image condition. However, this is done on a random 'random' basis, so for small trial numbers, you should not expect a 70/30 split.
Uses: preProcessSpreadsheet, store, retrieve, Math.random()
Concepts: Changing the task spreadsheet, generating random values, metadata columns, randomising display, condition assignment
Randomised Content from Single Datasets
The script in this task randomly assigns stimuli from a metadata column on a trial by trial basis. All of the potential stimuli available are contained in one metadata column. In building the spreadsheet, we first collect all the stimuli from this metadata column. Then, on each trial that requires stimuli assignmed, we shuffle the stimuli and collect the top X stimuli. With appreciation for the normal rules of true randomness, this will result in a random set of stimuli on each trial. For a more advanced version, where stimuli are set to different categories, see Randomised Content from Multiple Datasets.
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: Changing the task spreadsheet, metadata columns, randomise row contents, random stimuli selection, trial by trial randomisation
The script in this task selects a subset of the available trials. It makes use of Gorilla's own randomisation via randomise trials and uses postProcessSpreadsheet to select the first ten of the available trials. As these will already be randomised on a per user basis, this set of ten will be random for each participant (with an appreciation for the normal rules for true randomness.)
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
Uses: postProcessSpreadsheet
Concepts: changing the task spreadsheet, selecting trial subsets
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section involve more advanced alterations to the spreadsheet prior to the task running. Scripts that select random subsets based on the type of trial or condition and scripts that build entire spreadsheet columns (or, indeed, the entire spreadsheet) from scratch will be included in this section.
Counterbalanced Subset of Trials - Conditions
The script in this task demonstrates creating a counterbalanced subset of trials based on multiple conditions. Each trial has five conditions, each having multiple states, and we want to select a balanced subset of 24 trials from the possible set of 96. This scripts creates limits on how many of each state of condition we can have in the subset and then randomly selects trials, ticking conditions off of the list. Once we reach the limit of a condition state, we'll discard any further trials that have the condition state. In the event that we don't end up with a set of 24 balanced trials, we'll reset and try again, up to five times. We use postProcessSpreadsheet to take advantage of Gorilla's inbuilt randomisation capabilities, rather than shuffling the spreadsheet our selves for the first iteration
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
Uses: postProcessSpreadsheet
Concepts: advanced counterbalancing, shuffling spreadsheet content, selecting trials
Randomise Button Text Order per Trial
The script in this task randomises the contents of four buttons on a trial by trial basis i.e. row by row. For each trial, the contents of four buttons will be presented in a 'random' order (with appreciation for the normal nature of randomness). This is a more advanced version of the Randomise Button Text Order script
Note: this can now be done without script in Task Builder 2 using the Randomise Between Columns component.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: Changing the task spreadsheet, randomise row contents, shuffling spreadsheet content, trial by trial randomisation
Randomised Content from Multiple Datasets
The script in this task selects stimuli from metadata columns on a trial by trial basis. This is a more advanced version of the Randomised Content from Single Datasets script. There are five metadata columns, each containing image stimuli that belong to a different category (food, tools, vehicles etc.) There are then three different types of trial: two choice, three choice and four choice, requiring two, three and four stimuli respectively. Based on the kind of trial, we draw an appropriate number of stimuli frm the metadata columns, selected only one stimuli from a column per trial.
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: changing the task spreadsheet, randomise stimuli presentation, metadata columns, trial by trial randomisation, random stimuli selection
Randomised Trial Subset from each Trial Type
The script in this task selects a random subset of each type of trial. Using a metadata column, the trials in the spreadsheet are assigned to one of four categories. The script sorts the spreadsheet into the different trial types and then builds a new spreadsheet, selecting at most one trial from each type.
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: changing the task spreadsheed, random subset, random trial selection
Select Subset of Trial Types by Condition
The script in this task selects a subset of trials based on the trial condition. This bears similarity to the task Randomised Trial Subset from each Trial Type though taking a different approach. In the spreadsheet, a metadata column assigns trials to one of three conditions. We then collect trials from only two of the conditions, shuffle them and then select a subset of each to use in the main spreadsheet
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: changing the task spreadsheed, random subset, random trial selection
Select Subset of Trial Types by Display
The script in this task selects a subset of trials based on the trial display name. This takes the same approach as Select Subset of Trial Types by Condition, using the display column rather than a metadata column. In the spreadsheet, there are three kinds of trial based on their display name. We then collect trials from only two of the display names, shuffle them and then select a subset of each to use in the main spreadsheet.
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
Uses: preProcessSpreadsheet, store, retrieve, shuffle
Concepts: changing the task spreadsheed, random subset, random trial selection
RR With Spreadsheet Subset Iterations
The script in this task selects a subset of the available trials, making sure that the subset is different for each iteration of the task. The relevant trials are collected and then shuffled using a random seed stored in embedded data. This way, on future iterations of the task, we can shuffle the trial set in an IDENTICAL way. Then, we select a subset of the trials based on how many times we've looped through the task so that over successive iterations, we will go through the whole trial set. In the default use case we CANNOT repeat the tasks more times than we have available trial i.e. if you have 100 trials with 25 trials on each repeat, you can take the task a maximum of 4 times. The script includes additional code, commented out, to allow the trial set to be refreshed (rerandomised) and progress reset, so the participant can continue repeating the task indefinitely.
Uses: postProcessSpreadsheet
Concepts: changing the task spreadsheet, selecting trial subsets, repeating the task
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section demonstate how to alter the spreadsheet dynamically, during task run time. This could range from simple alterations, such as adding additional information to metadata columns, to be stored in the participants metrics. Or, it could involve adding trials or altering future trials. These take advantage of the fact that, in Javascript, arrays get passed by reference into a function. So, any alterations we make to the spreadsheet inside any of our script hooks, will affect the 'real' spreadsheet deep in the Gorilla Task Builders memory. The more extensive the alterations to the spreadsheet, the more care is required in implementing the scripting and testing it!!
Add Trials Dynamically - Repeat Incorrect Trials
The script in this task dynamically adds more rows to the spreadsheet. Any time a participant gets a response incorrect, they'll be required to repeat the trial again. This script involves live editing the spreadsheet.
Uses: preProcessSpreadsheet, onScreenRedirect
Concepts: adding additional rows to the spreadsheet
Add Trials Dynamically - Study Test Drop
The script in this task dynamically adds more rows to the spreadsheet, depending on a participant's choice. On each trial, they have the choice to Study, Test or Drop. If they choose to Study or Test the trial, they will see the trial again, either using a study display or a test display. This process repeats until all trials have been dropped. This script involves live editing the spreadsheet.
Uses: preProcessSpreadsheet, onScreenRedirect
Concepts: adding additional rows to the spreadsheet
Dynamically update screen timelimit based on participant's Reaction Time
This script is used to calculate the Reaction Time (RT) for correct trials in the Practise display which is then used to change the timelimit of the screen presenting stimuli in the Test display, on a trial-by-trial basis. This way, the screen timelimit for the Test display dynamically changes per each trial based on participant's performance.
Uses: onScreenStart, onScreenFinish, readStopwatch, store, metric, retrieve
Concepts: calculating RT, calculating RT for correct trials, dynamically updating screen timelimit based on participant's performance
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section involve dynamic redirection to different screens depending on partcipants' performance.
The script in this task demonstrates branching to different screens based on participants' performance, i.e. staircasing.
Note: This can now be achieved in Task Builder 2 without any additional scripting by using the Change - Difficulty Staircase component.
Uses: retrieve, manipulation, store, onScreenStart, forceAdvance, onScreenFinish
Concepts: changing which screen or row you are going to in spreadsheet
This script decides if the trial is a win or lose trial based on a fixed probabilty. Depending on their response, participants are directed to either a win or lose screen using the onScreenRedirect function. In the case of a win trial, participants' total score will increase.
Uses: onScreenStart, onScreenRedirect, store
Concepts: Saving pariticipants' responses to embedded data; directing participants to different screens depending on their responses
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section allow for setting up a custom scoring system that dynamically adapts during the task based on participant's performance.
Score Multiple Answers as Correct
Normally in Gorilla Task Builder only one answer can be specified as correct. This script allows to score multiple answers as correct using the isCorrect hook.
Note: This can now be achieved in Task Builder 2 without any additional scripting. See the Scorer (Multi) component for more information.
Uses: isCorrect
Concepts: adding custom answer scoring, scoring multiple answers as correct
Wisconsin Card Sorting with Category Switch
The script in this task implements a custom correct/incorrect answer scoring system, using the Wisconsin Card Sorting task. After ten correct answers in a row, a switch in the correct answer category being used occurs. The initially chosen category for the correct answers, and the subsequent order of other categories is randomised.
Uses: isCorrect
Concepts: adding custom answer scoring
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The scripts in this section have been archived as they contain content that is no longer relevant or useful.
Usually, these are scripts that have inspired us to create content within the GUI to replace them, so the same functionality is available with no scripting required (this is the ultimate goal for almost all scripts.)
This section also includes scripts where the desired functionality is no longer possible or desirable because of changes to browser infrastructure, or where more advanced scripting methods have been made available.
While interesting to review, the scripts in this section shouldn't be used in a real task for data collection. Scripts that relate to content now available within the Task Builder GUI, as settings or zones, and scripts that are no longer workable due to changes in browser archetecture are included in this section.
Check Passive Likert Answer with Custom Continue Button
The script in this task replaces the normal continue button with a custom coded one that checks a passive likert for a response. It will prevent participant progression until a response is given. This script is ARCHIVED because the Passive Likert Zone now has a 'requires response' setting. This setting was added following the creation of this script.
Uses: onScreenStart, refreshLayout, forceAdvance
Concepts: changing zone functionality, adding a custom zone, manually advancing the screen
Choose Spreadsheet Dynamically
The script in this task dynamically overrides the choice of spreadsheet based on the value of an embedded data field. This allows you to determine which spreadsheet is used on a per-participant basis, for example: using an earlier task to decide which spreadsheet to use later, using a Counterbalance Node to ensure that a balanced number of participants receive each spreadsheet, or using other values such as the Public ID to tailor individual spreadsheets to individual participants. This script is ARCHIVED because the Experiment Builder now has a built-in 'Manual Override' option for spreadsheet selection.
Uses: preProcessSpreadsheet
Concepts: changing the task spreadsheet
Dynamically Choose Spreadsheet
The script in this task dynamically chooses which spreadsheet to use based on an embedded data setting. This script is ARCHIVED because Task manipulations set via a Dropdown, such as Spreadsheet, can now be populated via embedded data without the use of scripting.
Uses: preProcessSpreadsheet
Concepts: changing the task spreadsheet
The script in this task hides a text based stimuli after a set delay. This script is ARCHIVED because text zones now have a 'Hide after X ms' setting. This setting was added following the creation of this script
Uses: onScreenStart, refreshLayout
Concepts: changing zone functionality, hiding a zone
Relational Reasoning with Exit
The script in this task adds a custom button to the screen which allows the user to exit the task early. This script is ARCHIVED because there is now an Early Exit Button zone in the Task Builder. This zone was created following the creation of this script.
Uses: onScreenStart, finish
Concepts: creating new task builder zones, ending the task
The script in this task demonstrates dropping trials assigned to certain conditions depending on user performance. The Relational Reasoning trials in this task are assigned to either easy, medium or hard, with the performance measured on the basis of number of incorrect answers. If the participant reaches a certain threshold of incorrect answers in a certain condition, then that condition will be dropped and future trials will not be displayed. This script is ARCHIVED because it uses onGetSpreadsheetRow which we generally recommend to avoid using and is undocumented. This is because of the complexity of how onGetSpreadsheetRow is called and its association with the lookahead system. There is no GUI based functionality to replace it, so this script can still be used but caution is advised when altering it.
Uses: onScreenFinish, store, retrieve, onGetSpreadsheetRow
Concepts: managing embedded data
Sentence Reading with Blanked Out Words
The script in this task used a combination of HTML in the spreadsheet and custom classes in the script to hide words in a sentence so that the full setence is revealed over progressive screens. This script is ARCHIVED because the Gorilla Task Builder now has the Reading Zone, which enables this functionality without the need for HTML or custom styling.
Uses: onScreenStart
Concepts: using html in the spreadsheet, custom styling
The script in this task selects a random subset of trials by category from the spreadsheet for presentation in the task. This script is ARCHIVED because it uses onGetSpreadsheetRow which we generally recommend to avoid using and is undocumented. This is because newer hooks like preProcess and postProcessSpreadsheet make this functionality significantly easier to create.
Uses: onGetSpreadsheetRow
Concepts: changing the task spreadsheet, selecting trial subsets
The script in this task selects a random subset of stimuli from the spreadsheet. This script is ARCHIVED because newer hooks like preProcess and postProcessSpreadsheet make this functionality significantly easier to create.
Uses: onGetSpreadsheetRow
Concepts: changing the task spreadsheet, selecting trial subsets
The script in this task manually collects and uploads the value of the slider every X ms. This script is ARCHIVED because the Response Slider now has an advanced setting which allows the slider value to be collected automatically every X ms. This setting includes multiple safeguards that prevent against unnecessary metric data (if the participant leaves the slider stationary) and will work with all combinations of slider usage. This new setting was created following the creation of this script.
Uses: onScreenStart, onScreenFinish, setInterval, metric
Concepts: changing zone functionality, uploading metrics
Slider Value Using Interval with Manual Play Video
The script in this task manually collects and uploads the value of the slider every X ms, where initial collection is triggered by a video being played This script is ARCHIVED because the Response Slider now has an advanced setting which allows the slider value to be collected automatically every X ms. While this isn't setup to sync with the playing of a video, it has various safety features which are preferred. Further, the video zone will now automatically upload a metric when the video is started, so you can still get a full analysis of participant actions.
Uses: onScreenStart, onScreenFinish, setInterval, metric
Concepts: changing zone functionality, uploading metrics
The script in this task tracks the number of times a video has been played and the total duration of views and uploads it to the metrics. This script is ARCHIVED because this information is now uploaded by the zone automatically. This functionality was added in response to this script
Uses: onScreenStart, onScreenFinish, store, retrieve, metric
Concepts: uploading metrics
You're viewing the support pages for our Legacy Tooling and, as such, the information may be outdated. Now is a great time to check out our new and improved tooling, and make the move to Questionnaire Builder 2 and Task Builder 2! Our updated onboarding workshop (live or on-demand) is a good place to start.
The examples listed in the pages above are all the scripts available in the Task Builder Script Examples Project.
To show exactly how to add specific scripts to your task, we'll be adding common examples here with a detailed walkthrough!
In this task, we present only a subset of the main 'trials' display. We do this by parsing through the spreadsheet to collect the trials we are interested in, select a reduced number of them and then rebuild the spreadsheet using only that subset of the target trials. All other trials, such as instructions or practice trials remain in place. In this example, we actually use postProcessSpreadsheet to achieve this - we let Gorilla randomise the order of the trials first and then we just select X trials off the top of the list. For each participant, this will generally be a different subset each time.
To do so, we need to use the 'Script' part of the Task Builder, copying the script from the example task above into your 'Script' part of the experiment.
While looking at the script, these will be the specific lines (lines 36-54) that you will have to make changes to, specifying the subset:
Note: this can now be done without script in Task Builder 2 using the Select Randomised Subset component.
