Quick start

In this section, you will learn how to use Template Builder. As an example, you will create a task interface for a picture with multiple response options.

Before you start

Open Template Builder.

Theory

We recommend that you read these sections to get familiar with Template Builder:

Template Builder interface

The Template Builder interface consists of four vertical panels:

1. Configuration: for editing the task interface in JSON format. It supports auto-completion with hints and preset code snippets.

2. Example of input data: for editing input data in JSON format. The input data specification is automatically generated based on this field.

3. Preview: shows what the task will look like.

   If the configuration contains an error, the reason is displayed here. For example, [3:2]The closing bracket "}" is missing. It means that you omitted a bracket at character 2 on line 3.

4. Sent data: sample JSON output. This panel appears when you click Send in the preview. To copy the output data, click . To hide this panel, click Close Panel at the bottom.

To hide or display the first three panels, use the buttons in the upper-left corner.

If you opened Template Builder in Toloka, click in the upper-right corner to switch to full-screen mode. If you opened the Template Builder sandbox, it is already displayed full-screen.

Shortcuts

To view all the available commands and shortcuts, click F1. Main shortcuts:

• Tab: Get auto-completion hints.
• Ctrl+S: Use for automatic formatting (alignment of text indents).

If you're not familiar with JSON

If you haven't written in JSON before, you might have some difficulties like unclosed brackets or missing commas and quotation marks.

Configuration format

{
  "view": {
    "type": "category.name",
    ...
  },
  "plugins": [
    {
      "type": "plugin.name",
      ...
    }
  ],
  "vars": {
    "varName": "value",
    ...
  }
}
Copy text

There are 3 elements at the top configuration level:

• view: The component to be displayed, such as an image or list of nested components.

  In the type property, specify the name of the component, then list the other properties. Each component has its own set of properties. See the hints in the editor and the component descriptions in the Component reference guide.

• plugins: An array of added plugins. These are special components that provide additional functionality, such as shortcuts.

• vars: Variables with JSON code that can be reused anywhere in the configuration using the $ref structure as follows:

  {
    "view": {
      "type": "view.text",
      "content": {
        "$ref": "vars.my-text"
      }
    },
    "vars": {
      "my-text": "Hello World"
    }
  }
  Copy text

Practice

In this section, you will create a task interface for an image. The interface will consist of three elements: a title with the task description, a picture, and a group of three buttons with answer options.

Creating a task interface

1. The configuration editor will display an empty code template with two blocks: view and plugins.

   If you're working in Template Builder, not in the Toloka interface, use the empty template.

   The view block has the view.list component to display data in a list. We'll use it to create the interface we need.

   

   Tip

   To see additional information about a component, hover over it in the list of components or in the editor.

2. Go to the Example of input data panel to configure the input data.

   Copy the sample input data there (the link to an image). It will be used in the next steps.

   {
     "image": "https://yastatic.net/s3/toloka/p/requester/a66492018a130d7337d57a787970f376.jpg"
   }
   Copy text

3. Go back to the Configuration panel. Add the array of elements of the future interface to the items property of the view.list component. To do this, place the cursor inside the square brackets and click Tab. A list will appear where you need to select the view.text component. Change the value of the content property to "Look at the picture and answer the question.". This text will appear above the image as the task title.

   

4. Add the next element. To do this, place the cursor behind the curly bracket that closes the view.text component, type a comma, and click Tab. A list will appear where you need to select the view.image component. It is used to display the image. Its url property contains a link to the image. Delete the link and the quotation marks and click Tab. A list will appear where you need to select the data.input component. It is used to get values from the sample input data.

   

5. Change the value of the path property in the data.input component to "image". The image from the sample input data will appear on the Preview panel.

6. The next interface element is the field.button-radio-group component that adds a group of buttons. Its label property contains the text that will be displayed above the answer options. Change its value to "What is the cat's mood?".

7. The options property contains a list of options for selecting a response. By default, there are two options. Add a third option the same way you added other components. Don't forget to put a comma between the second and third options.

   Each option contains two properties: label (title) and value (the value to be passed in the output). Change the property titles to "Good", "Bad", and "Loading error", and the values to "ok", "bad", and "error".

8. The next property after the group of buttons is data. It determines what the output data will look like (data.output). The output data is the values that take the responses to the task questions.

9. The plugin.toloka component at the end of the code specifies the additional task settings. Change the value of the taskWidth property (the width of the task block) to 500.

10. The task is ready to use. Try to complete it in the Preview window and click Submit to view the result.

Adding shortcuts

To help Tolokers complete your tasks faster, add shortcuts to the interface.

Learn more about shortcuts in Configure keyboard shortcuts.

Shortcuts are not part of visual components. They are added via a separate plugin, plugin.hotkeys. Use this plugin to assign keys to actions.

1. Shortcuts are added to the plugins section. Place the cursor after the square bracket that opens theplugins section and press Tab. In the list that appears, select plugin.hotkeys.

   

2. The plugins.hotkeys component is now empty. Fill it with the desired values. To do this, place the cursor after the opening curly bracket and click Tab. Two lists will appear in the following order: the first for selecting a shortcut, and the second for setting an action. In the first list, select the "1" shortcut; in the second, the action.set action.

   

   

3. Add two more shortcuts. To do this, place the cursor at the end of the "1" shortcut block (after the closing curly bracket and comma) and press Tab. Add the "2" shortcut with the same action.set action. Then add the "3" shortcut in the same way.

   

4. Each shortcut block has a data property that specifies the output data format. Change the value of its path property to "result" for each shortcut. The output data path should be the same for shortcuts as for the buttons that you assign them to.

5. Each shortcut also has a payload property with the value to be passed to the output data when this button is selected. Change this property for the three buttons to "ok", "bad", and "error".

6. Go to the Preview panel and click anywhere on the panel to move the cursor away from the editor. Now you can test the shortcuts.

Configuring validation

Validation lets you check the values that Tolokers enter. The next part of the code in this section checks that Tolokers select one of the options.

To enable this, add the validation property with the condition.required component to the component's code. In the examples above, this code has already been added.

You can also add a hint to this code telling Tolokers what they need to correct to pass validation. To do this, add a hint property with the hint so that it looks like this:

{
  "validation": {
    "type": "condition.required",
    "hint": "select one of the options"
  }
}
Copy text

Go to the Preview panel and try submitting the task without selecting any of the options.

Learn more about automated checks in Reviewing assignments automatically.

Checking the data specifications

After you configure the task interface, check the input and output data specifications in the Data specification field. It's located right below the field for choosing an editor. Specifications are generated automatically, but errors are possible.

After that, you can continue creating or editing the project in Toloka.

What's next

• See instructions for popular tasks.
• Check the list of available components.

Last updated: August 2, 2023