Quick start

  1. Before you start
  2. Theory
  3. Practice
  4. What's next

In this section, you will learn how to use Template Builder. As an example, you'll create a task interface for comparison of two images.

Before you start

Open Template Builder.

  1. You must be registered in Yandex.Toloka as a Requester.
  2. Log in to Yandex.Toloka.
  3. Start creating a new project in Yandex.Toloka. Template Builder is integrated into Yandex.Toloka and you can use it when creating or editing projects.
  4. Select Template Builder in the Editor field.
    Where do I find it in the interface?

Theory

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

  1. Template Builder interface
  2. Text editor
  3. If you are not familiar with JSON
  4. Configuration format

Template Builder interface

The Template Builder interface has 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 hide this panel, click Close Panel at the bottom.

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

To go to full-screen mode, click in the upper-right corner.

Text editor

Monaco Editor is used in the editing panels. This editor is also used in VS Code, so many of the shortcuts used there are also available in Template Builder. To view the list of commands and shortcuts, click F1.

Additional shortcuts:
  • Tab: Get auto-completion hints (IntelliSense).
  • Ctrl+S: Automatic formatting (aligns text indents).

If you are 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.

Learn how JSON works
Objects are the main elements in JSON. They are enclosed in curly brackets, {}. An object contains "key":value pairs separated by commas.
{
  "name": "John",
  "surname": "Smith"
}
Tip. JSON is insensitive to spaces and line breaks between JSON elements. You may omit line breaks. When you click Ctrl+S in the editor, the code is formatted automatically.
The values may contain different data types:
  • string: A string enclosed in quotation marks, like "Hello world".
  • number: A number without quotation marks, like "age": 25.
  • boolean: A Boolean value without quotation marks (true or false).
  • object: Anther object, for example:
    {
      "person": {
        "name": "John",
        "surname": "Smith"
      }
    }
  • array: An array of comma-separated elements. You can use absolutely anything as an element, like a string, a number, a Boolean value, or an object. An array is enclosed in square brackets, []:
    "cities": ["Moscow", "Tokyo", "New York"]
Important. If you enclose a number or Boolean value in quotation marks, it becomes a string. This means that "disabled": true is not the same as "disabled": "true".
If you have more questions, see the documentation on the website.

Configuration format

{
  "view": {
    "type": "category.name",
    ...
  },
  "plugins": [
    {
      "type": "plugin.name",
      ...
    }
  ],
  "vars": {
    "varName": "value",
    ...
  }
}
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"
      }
    }

Practice

In this section, you will create a task interface for comparing two photos.

Tip. If something goes wrong during the creation process, you can view the correct code in the sandbox.

Creating a task interface

Template Builder has a ready-made component for comparing images:

  1. Delete the view property value in the configuration editor, position the cursor there and click Tab:



    Tip. You can enable display of information about a component. To do this, click the icon next to the selected component. Additional information is also displayed when you hover over the text in the editor.
  2. Select layout.side-by-side and click Enter.
  3. On the Preview panel, you'll see a sample task for comparing two products.
  4. Go to the Example of input data panel to configure the input data.
  5. Copy the sample input data there, i.e., links to the left and right image. They will be used in the next steps.
    {
      "image_a": "https://images.pexels.com/photos/1521304/pexels-photo-1521304.jpeg",
      "image_b": "https://images.pexels.com/photos/1521306/pexels-photo-1521306.jpeg"
    }
  6. Go back to the Configuration panel (where you added layout.side-by-side).
  7. In the url properties, delete the links (with the double quotes) and click Tab. Select the data.input component in the list that shows up. This way you can get values from the sample input data.

  8. In the objects with the data.input type (path property), insert the names of fields with images: image_a and image_b.

  9. Change the question text in the photo selection component to "Which photo do you like best?".
  10. The task is created. Try to complete it in the preview window and click Send to view the result.
Full configuration code
{
  "view": {
    "type": "layout.side-by-side",
    "items": [
      {
        "type": "view.image",
        "url": {
          "type": "data.input",
          "path": "image_a"
        },
        "fullHeight": true
      },
      {
        "type": "view.image",
        "url": {
          "type": "data.input",
          "path": "image_b"
        },
        "fullHeight": true
      }
    ],
    "controls": {
      "type": "view.list",
      "items": [
        {
          "type": "field.radio-group",
          "label": "Which photo do you like best?",
          "options": [
            {
              "label": "A",
              "value": "a"
            },
            {
              "label": "B",
              "value": "b"
            },
            {
              "label": "Images didn't load",
              "value": "failure"
            }
          ],
          "data": {
            "type": "data.output",
            "path": "result"
          }
        },
        {
          "type": "field.textarea",
          "label": "Please explain why you chose this one",
          "data": {
            "type": "data.output",
            "path": "why"
          }
        }
      ]
    }
  }
}
Tip.

Use code snippets to see what property values you can use. In autocomplete, samples are labeled with the icon .

To view the list of samples for a property, delete the property value, position the cursor after the colon, and click Tab.

Adding shortcuts

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

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

Before the configuration's root view element, add the following code. Don't forget about the comma between view and plugins.
"plugins": [
    {
      "0": {
        "type": "action.set",
        "data": {
          "type": "data.output",
          "path": "result"
        },
        "payload": "failure"
      },
      "1": {
        "type": "action.set",
        "data": {
          "type": "data.output",
          "path": "result"
        },
        "payload": "a"
      },
      "2": {
        "type": "action.set",
        "data": {
          "type": "data.output",
          "path": "result"
        },
        "payload": "b"
      },
      "type": "plugin.hotkeys"
    }
  ],
This code adds the hotkey plugin and specifies the action.set actions triggered by the keys:
  • 0: Set the failure value in the output result field. This is the Images didn't load button.
  • 1: Set the a value into the output result field.
  • 2: Set the b value into the output result field.

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 the performers enter. Let's say you ask the performers to fill in the comment field.

To do this, add the validation property with the condition.required type to the comment field code:
{
  "type": "field.textarea",
  "label": "Please explain why you chose this one",
  "data": {
    "type": "data.output",
    "path": "why"
  },
  "validation": {
    "type": "condition.required"
  }
}

Go to the preview panel and try submitting the task with the comment field empty.

Checking the data specifications

After you configure the task interface, check the input and output data specifications. They are generated automatically, but errors are possible.

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