Support Home

Gorilla Task Builder Scripts List

  • Overview
  • Alter Content
  • Add Content
  • Simple Spreadsheet Processing
  • Advanced Spreadsheet Processing
  • Dynamic Spreadsheet Alterations
  • Dynamic Redirection
  • Archived
  • Common examples

Overview


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.

Alter Content Scripts


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


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.

Uses: onScreenStart, retrieve, stimuliURL

Concepts: changing zone functionality, dynamic feedback


Audio After Delay

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.

Uses: onScreenStart

Concepts: changing zone functionality, manually triggering zone functionality, adding a timeout


Audio on Spacebar press

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


Fixed No of Pixel Size Image

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

Uses: onScreenStart, refreshLayout

Concepts: changing zone content, changing image appearence


Make Video Fullscreen

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.

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.

Uses: store, retrieve, manipulation

Concepts: collecting manipulation values, resetting embedded data


Urn Task with Live Scoring

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.

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


Delay Continue Button Action

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.

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.

Uses: onScreenStart, setTimeout, jQuery, jQuery data object

Concepts: changing zone functionality, accessing event listeners and handlers through jQuery


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


Add Content Scripts


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.

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


Task with Force Fullscreen

The script in this task demonstrates using the browsers fullscreen commands to require the participant to be in fullscreen 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 participants browser window to fullscreen. 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 participants 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

Uses: onScreenFinish, onScreenStart, store, retrieve, readStopwatch, refreshLayout

Concepts: adding custom task content, collect reaction time, display text to screen


Combining Multiple Scripts

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.

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


Dynamic Response Creation

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


Metric on Screen Load

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


Metric On Each Key Press

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


Procedural Activatible Grid

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


RR With Default Selection

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


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


PVT with Numbers

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


Simple Spreadsheet Processing Scripts


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.


Spreadsheet Processing Demo

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


Randomise Button Text Order

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.

Uses: preProcessSpreadsheet, store, retrieve, shuffle

Concepts: Changing the task spreadsheet, randomise row contents, shuffling spreadsheet content


Randomise Entries in Column

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.

Uses: preProcessSpreadsheet, store, retrievem 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% propability 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.

Uses: preProcessSpreadsheet, store, retrieve, shuffle

Concepts: Changing the task spreadsheet, metadata columns, randomise row contents, random stimuli selection, trial by trial randomisation


RR With Spreadsheet Subset

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.)

Uses: postProcessSpreadsheet

Concepts: changing the task spreadsheet, selecting trial subsets


Advanced Spreadsheet Processing Script


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 trials 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

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

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.

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.

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

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.

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


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.

Uses: preProcessSpreadsheet

Concepts: changing the task spreadsheet


Dynamic Spreadsheet Alteration Scripts


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 trail 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 participants 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 trail 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


Dynamic Redirection


The scripts in this section involve redirecting to different screens depending on partcipants' performance, i.e. staircasing.


Staircasing Demo

The script in this task demonstrates branching to different screens based on partcipants' performance, i.e. staircasing.

Uses: retrieve, manipulation, store, onScreenStart, forceAdvance, onScreenFinish

Concepts: changing which screen or row you are going to in spreadsheet


Archived


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 logner 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


Hide Stimuli After Timeout

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


RR With Droppable Sets

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


Show Random Stimuli Subset

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


Slider Value Using Interval

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


Video Playcount and Duration

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


Common examples


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!


Choosing a specific subset

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: