How To: Task Builder


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:

  1. You must give your task a name, and
  2. You must choose how you want to build your task.

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.




Pro Tip

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.

  1. The task 'structure' defines how your task will appear and how it can be interacted with. In each display you specify the placement of content such as stimuli and the control of user responses and feedback.
  2. The 'stimuli' are the media files (images, video, gifs etc.) which will be presented to your particpants during the task.
  3. The 'spreadsheet' controls the flow of your task. It governs what stimuli and screens are displayed in each trial. The spreadsheet is also used to create randomised blocks.
  4. The 'manipulations' allow you to configure settings that can be changed from within the experiment tree to create a between subject experiment. For instance, this could be used to alter timing between condition, or whether or not feedback is received.

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:

  1. Displays which contain one or more screens
  2. Screens which are configured to show stimuli, record responses, and show feedback
  3. Screen Layout which is used to adjust the placement of visual elements
  4. Settings which are used to configure advanced settings such as stimuli and feedback timing.

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:

  1. Spreadsheet: For content that changes trial by trial. Learn more about spreadsheets here.
  2. Manipulation: For content that changes between participants and that you want to specify from within the experiment tree. Learn more about manipulations here.
  3. Static: For content that never changes. For instance, instructions.
In the example below:
  • The title is a text zone, with static content (orange) which is 'Rate this picture'
  • The image is an image zone, with content sourced from a spreadsheet (green - to match Excel) in a column labelled Picture. The image file to be displayed here would be uploaded as stimuli and declared in the spreadsheet in appropriate column. Once the source as been set to spreadsheet and named (i.e. Picture), the spreadsheet tab will be prepopulated with this column
  • The buttons are text response buttons, set as manipulations. In this experiment, the buttons might be labelled 'happy' or 'sad'. Having them set as manipulations allows us to have two conditions in the experiment tree, one with 'happy' on the right and 'sad' on the left, and vice-versa.

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':

  1. 'randomise_blocks' is used to group blocks together so that the blocks can be presented in a random order to each participate. Learn more about randomisation here.
  2. 'randomise_trials' is used to identify rows that will be shuffled before presenting them to a participant. This allows the trials to be presented in a random order.
  3. 'display' determines which 'Display' from your tasks structure is going to be shown. In the example below, the first display we want to have show from our task structure is the 'instructions' display. The next seven are 'task' displays and the final is the 'debrief' display.
How to read the spreadsheet shown above:
  • The spreadsheet above consists of 7 trials.
  • An instructions screen is shown before the first trial
  • The first trial doesn't not have a '1' in the randomise_trials or randomise-blocks column. Consequently, this trial will always be shown first.
  • The next six trials are split across three blocks using the randomise_trials column. You can't see the metadata, but this corresponds with two trials at each of three levels of difficulty (easy, medium and hard). Consequently, at each level of difficulty, the trials will be shown in a random order.
  • The 'randomise_blocks' column has a 1 next to the easy trials and a 2 next to the hard trials. These trials are block randomised. So, some will get the trials in the order easy, medium, hard. Whereas others will get hard, medium, easy.
  • Once the final trial has been completed, a debrief screen will be shown.

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.

The spreadsheet summarised!

  1. In the task structure tab, declare the name of the columns you will need in your spreadsheet.
  2. This will populate the columns on the spreadsheet tab
  3. Download the spreadsheet. This will be pre-populated with the column headings.
  4. Complete the spreadsheet with trial and trial content information
  5. Upload the spreadsheet

Pro Tip!

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.

Pro Tip!

Rows with the same randomise trial number don't need to be adjacent on the spreadsheet. Say for example that you wanted to have two blocks, each randomised. One of them could be a block of easy tasks and the other a block of harder tasks. Rather than have the easy block followed by the hard block, you could alternate with an easy trial followed by a hard trial. As each row is still part of a randomised block, each 'easy' trial will stick be taken from one in the '1' block and each 'hard' trial will be taken from one in the '2' block. What other ways do you think you could use this to create unique and imaginative tasks?

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. Image highlighting Edit button on Page

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'. Image highlighting Upload spreadsheet button on Page

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.

Need to download a Task Spreadsheet? Find out how here
Want to learn more about creating Task Spreadsheets? Check out our Spreadsheet Walkthrough!

Pro Tip!

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. Image highlighting Edit button on Page

2. Now navigate to the Spreadsheet Tab for your Task.

3. Click the 'Download Spreadsheet' button, to open the Download menu: Image highlighting Download Spreadsheet button on Page

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.

Below is an image of the Spreadsheet Download menu.
You can choose to download your spreadsheet as an XLSX, ODS or CSV file via the dropdown menu.
Image of Spreadsheet Download Menu

Image example of CSV selection in Download menu.
If you choose to download your file as a CSV you can also choose which separator/delimiter type you wish to use:
Image of CSV separator options in Spreadsheet Download Menu

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.

Examples


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: Image of Default example Spreadsheet opened in Excel


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: Image of CSV separator options in Spreadsheet Download Menu

Pro Tip!

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:

  1. Enter the Edit mode for your task by clicking the Edit button.
  2. Navigate to the Spreadsheet page of your task.
  3. Click the + Add Spreadsheet button.
  4. Enter a name for your spreadsheet.
  5. Press the Upload Spreadsheet button to upload your new spreadsheet.

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.


Organising your spreadsheets:
  • You can rename or delete a spreadsheet at any time by using the 'Options' menu.
  • You can also update an existing spreadsheet - by uploading a new spreadsheet - this will replace the existing spreadsheet.

In all of the above cases the action will always take place on the spreadsheet listed in the 'Show Spreadsheet' Dropdown menu.


Why would I use multiple spreadsheets?
Using multiple spreadsheets in the same task can allow you to easily create different versions of your task, quickly and simply without needing to spend time recreating structure and aspects of a task you want to reuse.

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.

  • This will allow you to view every display in your spreadsheet when you preview your task. This sort of testing spreadsheet is useful when you wish to make layout, grammatical or semantic changes and immediately see the visual effect for a participant.
  • This spreadsheet is also great for testing the basic functionality of your different displays - without having to go through all your trials.

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.

  • When testing your task make sure you get at least one answer correct and one answer incorrect
    • This will allow you to test if any feedback and scoring is working correctly.
  • Be sure to download the metrics and check the Response column
    • This will allow you to test the answers are being scored as 'correct' and 'incorrect' appropriately.

Lastly, for tasks with many trials or with multiple different sections create separate 'short-test' spreadsheet for your task:

  • For each different or unique 'section' create a separate spreadsheet with just these trials. This can also be useful for initial piloting - allowing you to test individual sections as you create them before combining them into your final task.
  • For tasks with many different trials, often randomised into blocks or split into sections with breaks - produce a cut down version of your full task spreadsheet by selecting only a couple of blocks or sections for testing purposes.

Stimuli


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?


  • Image files: All images files are supported. We recommend using PNGs.
  • Sound files: We recommend MP3s as they are mostly likely to work across different browsers, operating systems and device.
  • Video:
    • If you need tight control over the display of the video:
      • This can only be achieved by uploading the video file to Gorilla. In this case we recommend using MP4s as this is the most reliable across browsers. Nevertheless, we cannot guarantee that the video will work across all browsers. See the format compatibility table below to understand which formats will work in which broswers.
    • If you don't need tight control over the display of the video:
      • We recommend uploading the video to Vimeo or YouTube and embedding it. This is because different browsers, operating systems and devices required different video formats, and Vimeo or YouTube provides the video in multiple formats which takes care of this for you.
    • See here for more about browser compatibility.
Useful Links:
  • Details about configuring the Image Zone are here
  • Details about configuring the Audio Zone are here
  • Details about configuring the Video Zone are here
  • Details about configuring the Embed YouTube Zone are here
  • Details about configuring the Embed Vimeo Zone are here

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.

  1. Some stimuli you may always want to show on a screen. For instance, a trial example on an instruction screen for instance. These can be included as 'static' stimuli in an 'image zone' of your screen.
  2. If the stimuli on the screen will change as you progress through the task, then you would want to populate it from your spreadsheet. Select the 'spreadsheet' option and give the name of the column that will hold the stimuli for this zone. As Gorilla progresses through your task, it will change the stimuli in this zone based on the contents of that column in the spreadsheet.

Manipulations


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!

How do I use manipulations?

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:

Image of Task Builder Script Tab containing a simple script which changes the background colour and text colour of the task.

Using the Task Builder Script: Gorilla Script Library

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:

Gorilla Task Builder Scripts: Adding a custom Script to your 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


Task Builder Script or Code Editor Tool?

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.