Welcome to the Task builder 'How To'
Here you can learn about the basic features of building Tasks in Gorilla by exploring the list of questions on the left.
Not sure where to start? Try one of these quick-start shortcuts:
Looking for more information on a specific Task Builder Zone? - Check out the Task Builder's Tooling Reference Guide.
If you can't find an answer to your question here please get in touch with us via our contact form. We are always happy to help you, simply tell us a little about what you are trying to achieve and where you are getting stuck.
What is a Task?
Tasks are used instead of Questionnaires when you want to collect Reaction Time Data.
The main body of a task will be blocks of trials that all have the same structure.
Trials can include text, image, video or audio (sound) files and responses can be collected in a variety of ways (touch, mouse, keyboard).
For advanced users; there are also options available for providing feedback to a participant, on both accuracy and reaction times, during a task.
How do I Start a New Task?
A new task can be created in a Project by pressing the 'Create' button and selecting 'Task' and 'Create New'.
When starting a new task, there are two necessary steps:
There are three options to choose from in step 2; the task builder or code-editor, or new code-editor.
Learn more about the task builder here.
When choosing a name for your task, try to make it something unique and memorable - a name you would easily associate with the task contents.
You will use this name when adding your task to an experiment or searching for it in your library. It is also the name people will see if you share your task with them, so it's important that they would be able to recognise it easily too!
What is the Task Builder?
The Task Builder allows you to assemble your task from both prepared and customisable components and to populate the content of each trial by specifying the content in a spreadsheet. You may recognise this principle from similar tools such as E-Prime. There is a very high degree of flexibility on the design of displays which you have complete control over!
Importantly, you do not have to touch a single line of code! The majority of classic reaction time experiments can be built in the Task Builder.
Learn more about building tasks with the Task Builder here
How do I Build a New Task?
There are four components to the task builder: the task structure, the stimuli, the spreadsheet and the manipulations.
In order to edit any aspect of your task, you must be in edit mode.
To do this, select the 'Edit task' button on the upper right handside of your screen. If instead you see the buttons 'Cancel changes' and 'Commit version' then you are already in edit mode.
How Do I Structure My Task?
In the task structure tab, you design how your task will be presented to your participants. You will decide where stimuli will be placed on the screen and how the user can interact with them. There are four levels of specification within the task structure:
What are Displays?
At the highest level, there are displays. Displays are made of at least one screen, more generally multiple screens. Each run of a display is triggered by a row in the spreadsheet.
In the example above, separate displays are used for the instructions, task and debrief. Both the instructions and debrief only consist of one screen. In contrast, the task is made of two screens, a fixation and the task screen itself. Multiple exposures to the task displays each with different stimuli is controlled by using the spreadsheet
If your experiment consisted of multiple different trial types, for instance massed or spaced trials, then these could be set up as two different displays and triggered sequentially or interleaved from the spreadsheet.
What are Screens?
A screen could consist of a fixation, text, stimuli, responses options or combinations of the former. The screen shown below contains a text title, an image, and a navigation button.
A screen can be added to your display by clicking on the circled 'plus' button within your display. This will open a modal titled 'Choose Template.' A range of common templates are included. The Rich Text template is useful for displaying instructions and debriefing information.
Each screen is initially based on a template, though this can later be customized by reconfiguring existing zones or changing the layout by moving or resizing existing zones or adding new zones. If you know you want a bespoke display, then you can select the 'Blank' template.
In edit mode, selecting a screen on the left-hand side of the task editor will open a more detailed screen configuration panel on the right-hand side shown below. In the screen layout area, the content and layout can be configured. Below this, in the screen settings area, additional settings can be configured.
What are Zones?
Zones are predefined areas of a screen that hold specific, customisable items.
For instance, the template above consists of three zones: an image zone and two response zones, in this case two more image zones. Some zones have an icon representing the type of content that they support. In the example above the large image zone has an icon of an image.
The content of zones can be sourced in three different ways:
In the example below:
How Does The Spreadsheet Work?
The spreadsheet governs the overall flow of your task. It will determine what displays are shown and in what order. If any zones are set to be populated from the spreadsheet, the spreadsheet will determine their content.
Each row of the spreadsheet triggers a display populated by a chosen set of data. We can show the same display multiple times with different stimuli by having multiple rows for that display, with different imput data in the columns. The task will progress through each row in the spreadsheet one after the other until the task is complete. The columns will contain all of the data necessary to run that display.
The first three columns in a spreadsheet are: 'randomise_blocks', 'randomise-trials' and 'display':
How to read the spreadsheet shown above:
The remaining columns determines what stimuli or data is shown on the screens within the display. For example, in the screen shown above we have indicated that an image zone called Puzzle will be populated from the spreadsheet column with the title Puzzle.
We highly recommend reading through our Spreadsheet Walkthrough to fully learn the tips and tricks of using the Spreadsheet.
You can find the Spreadsheet Walkthrough here
More On Randomisation
If the 'randomise_trials' column in a row is left empty, gorilla will always run that row in the order it is placed. If the 'randomise_trials' column in a row has a number then gorilla will run one of the rows that share the same randomise trial number.
How Do I Upload a Spreadsheet?
A Task Spreadsheet can be uploaded in XLSX_, ODS and CSV formats. You can upload your spreadsheet on your Task's Spreadsheet Page in a similar manner as you would Task Stimuli. You can upload a Spreadsheet in many formats however we recommend using only XLSX, ODS and CSV formats.
Here are the steps:
1. First, while in your task, be sure to enter Edit mode.
2. Now navigate to the Spreadheet Tab for your Task.
3. Finally click the 'Upload Spreadsheet' button, navigate to your spreadsheet file on your computer and click 'OK'.
Your task spreadsheet should now be uploaded. Check to see it working by pressing the Preview Task button and select the spreadsheet you just uploaded.
When adding the names of your stimuli files into your Spreadsheet, if your stimuli file names contain special characters or includes commas (,) as part of the name, you will need to upload your spreadsheet in a format other than CSV or else use a different separator/delimiter for your CSV. This is because the default separator for CSV files is 'comma'. Which results in the browser interpretting the comma's in your file name as separators!
How Do I Download a Spreadsheet?
A Task Spreadsheet can be downloaded from your Tasks Spreadsheet Tab in a similar manner as you uploaded your Spreadsheet. Whether you wish to download an existing (previously uploaded) spreadsheet, or else are creating your own task spreadsheet and wish to download the default example spreadsheet, the process is the same.
Here are the steps to download your Task Spreadsheet:
1. First, while in your task, be sure to enter Edit mode.
2. Now navigate to the Spreadsheet Tab for your Task.
3. Click the 'Download Spreadsheet' button, to open the Download menu:
4. Finally, from the download menu, select the file format that you wish your spreadsheet to be downloaded as. Press OK when you are happy with your selection.
Your task spreadsheet should now be downloaded!
Note: When you download a spreadsheet this will be regarded as a new file by your browser and computer. Depending on which browser you use and your computer's default download settings you may have to choose a folder location and file name when downloading your spreadsheet file.
If you are having trouble locating your recently downloaded spreadsheet first check your browser's download history. Then check your computers default downloads folder. If in doubt try re-downloading the spreadsheet file; Most major browsers (Chrome, Firefox, Edge) will give you the option to view the file immediately - you can then specify the location to save the file via your preferred spreadsheet programme's save function.
Downloading the Default Example Spreadsheet
You can download any Task spreadsheet that is currently uploaded to Gorilla, at any time. This includes the default spreadsheet you will find when you enter the Spreadsheet tab of a new task for the first time.
The default spreadsheet will contain the default standard column heading: randomise_blocks, randomise_trials and display.
Here's an example of what the default spreadsheet looks like:
Downloading an Existing Spreadsheet
You can download any Task spreadsheet that is currently uploaded to Gorilla, at any time. If you have started creating your task in the task structure this default spreadsheet may also include additional column headings for any zone content whose source is 'Spreadsheet' (Spreadsheet).
For example, if you have included any response zones which have 'active response' configuration settings then you will also see the default
column heading 'ANSWER'. Which is where you can enter the correct answer for each of your trials.
Here's an example of downloading an existing spreadsheet:
If you've had a task shared with you, you can use the 'download spreadsheet' button to obtain your own copy of the task spreadsheet. You can then make your own changes to the spreadsheet and upload the spreadsheet to change how your copy of the task runs or what stimuli are displayed.
Using Multiple Spreadsheets
Once you are familiar with the basics of building a task and creating spreadsheets you will likely want to start using multiple spreadsheets within your tasks!
You can add as many spreadsheets to your task as you wish, here are the steps to follow:
You can view all your uploaded spreadsheets from your Tasks Spreadsheet Page:
Press the Show Spreadsheet Dropdown menu to select the spreadsheet you would like to view.
You can also select which spreadsheet you would like to use when you preview your task: In the 'Manipulations' window - select the spreadsheet from the dropdown menu.
In all of the above cases the action will always take place on the spreadsheet listed in the 'Show Spreadsheet' Dropdown menu.
It's also very useful for testing your task; split your task into managable sections for your own testing purposes, save time by testing new task changes without having to run through all your task.
Example 1: Using mulitple spreadsheets to create multiple experimental tasks
Often you may wish to use the same task structure but with different stimuli sets or perhaps different response methods or stimuli presentation orders. All this can be done by uploading multiple spreadsheets in the same task.
You can even take this a step further and use your multiple spreadsheets as 'Manipulations' in your experiment tree.
In your Task Node in your Experiment Tree you can select which spreadsheet to use in your task. A common usecase of multiple spreadsheets is with stimuli sets of increasing difficulty.
You can see an example of performance branching using multiple spreadsheets here
Example 2: Streamline your testing
Some of your tasks may have many trials, or multiple different sections. You may wish to make minor semantic or layour changes which you want to preview and test. However sitting through all your task time and time again can become tiresome and a waste of valuable time.
Using multiple spreadsheets for testing purposes can help to streamline your testing and reduce the time taken to review and make changes. Here are some tips and tricks we recommend to help streamline your own task testing:
Start by creating a 'layout-testing' spreadsheet in which you include at least one display of each type.
Another testing spreadsheet which can be helpful to upload would be 'trials-test'. Here you include at least 1 trials of each 'type'. For example if your experiment is testing the difference between classification speed of two types of stimuli you would include at least one trial from each stimuli group.
Lastly, for tasks with many trials or with multiple different sections create separate 'short-test' spreadsheet for your task:
Stimuli are the media files you will present your participant as part of your task. They are typically images or sound files.
What File Types Are Supported?
How Do I Add or Upload New Stimuli?
To add new stimuli, press the 'Add New Stimuli' button.
Click 'Choose files' to then select files from your computer or attached device. You can upload stimuli from multiple locations by repeating this process. The stimuli will then be listed on the Stimuli screen.
How Do I Include Stimuli In A Task?
There are two ways to include stimuli in your task.
Manipulations allow you to change task wide settings which can then be varied between participants or experiment. They can also be useful when you are developing and piloting a task to see which settings work best!
Manipulations are set by using the 'Manipulation' option on either the zone settings screen or the screen settings screen.
Much like when using the spreadsheet, the manipulation is given a name. Rather than appearing in the column of a spreadsheet, the manipulation will appear under the manipulations tab.
In the manipulations tab, you can set a default value of the manipulation and also give a description of what the manipulation does and the different values it could take.
When previewing or running your task, you are then given the option to set or change these manipulations. Imagine a 'between subjects' experiment where you have a randomiser in the experiment tree which allocates participants to one of two versions of a task.
A manipulation can be used to create the two versions of the task.
How Do I Use a Task As Part Of An Experiment?
Tasks are included in experiments as 'nodes' in the experiment 'tree.'
You can control the various manipulations on your task through this node and also govern how a participant will interact with your task.
What is the Task Builder Script Tab?
The Script Tab in the Task Builder allows you to add custom script (code) to your GUI built Gorilla Task.
The Task builder Script tab is a powerful feature of the GUI Task Builder which allows you to add new functionality to your Task without needing to Code everything from scratch! You can also use the Script tab to alter the function of existing GUI Task Builder features or implement your own styling for your Tasks.
The Script Tab allows you complete flexibilty to design your tasks to look and function exactly as you need. While saving you time spent having to code everything yourself, you can instead focus on the aspects which really matter to you and your research.
The image example below shows an example of a script for changing the background colour and text colour for your task:
We have many Task Builder Script examples available and free to use within your tasks. You can find a full list of our exisiting scripts in our Task Builder: Script Examples library.
Once you have located a script you wish to use adding Gorilla scripts into your Task is simple. Just copy and paste the full example script into the script tab of your task and then change the required variables to get the script working.
Check out the video below to learn how to add a custom script from the Gorilla Script library into your own task:
Learn about the Gorilla Task Builder Script library and how to add custom scripts into your Task Builder Tasks.
Length (mins): 6:50
If you have any trouble implementing an existing Gorilla script do get in touch we are always happy to help and give advice.
Can't find what you need in our script library? Get in touch via our Support Contact Form
When the majority of your task can be built using the Task Builder GUI tools and available zones but you wish to modify functionality or style/formatting of a particular item then the Task Builder Script tab is for you.
If you wish to have complete control of the entire task function and write all your code from scratch then the Code Editor is the better tool for you to use.