Templates

Description

Templates are required to get rid of code duplication and not to describe each card from scratch. When using a template, you can specify and override all fields of the parent element.

If you often create cards with the same or similar content, save them as templates.

Templates help you:

  • Spend less time creating cards.

  • Reduce the size of incoming JSON.

  • Reduce the number of possible errors and typos when creating cards.

Without a template
{
  "states": {
    "state1": {
      "data": {
        "type": "container",
        "direction": "vertical",
        "paddings": {
          "left": 4,
          "top": 4,
          "right": 4,
          "bottom": 4
        },
        "items": [
          {
            "type": "image",
            "width": {
              "type": "fixed",
              "value": "40",
              "unit": "dp"
            },
            "height": {
              "type": "fixed",
              "value": "40",
              "unit": "dp"
            },
            "image_url": "https://image.storage.net/icon.png"
          },
          {
            "type": "text",
            "font_size": 16,
            "text": "Hello, World!"
          }
        ]
      }
    }
  }
}
With a template
{
  "templates": {
    "image-with-text": {
      "type": "container",
      "direction": "vertical",
      "paddings": {
        "left": 4,
        "top": 4,
        "right": 4,
        "bottom": 4
      },
      "items": [
        {
          "type": "image",
          "width": {
            "type": "fixed",
            "value": "40",
            "unit": "dp"
          },
          "height": {
            "type": "fixed",
            "value": "40",
            "unit": "dp"
          },
          "$image_url": "icon_url"
        },
        {
          "type": "text",
          "font_size": 16,
          "$text": "title_text"
        }
      ]
    }
  },
  "states": {
    "state1": {
      "data": {
        "type": "image-with-text",
        "icon_url": "https://image.storage.net/icon.png",
        "title_text": "Hello, World!"
      }
    }
  }
}

Examples

Templates can be used in complex elements (for example, in a container with child elements). To change the fields of the child elements, they need to be renamed in the parameters: $field_name_in_element: new_field_name

Edit the gallery_item element type with the item_image_url field.

Renaming example

{
  "templates": {
    "gallery_item": "container",
    <...>
    "items": [
      {
        "type": "image",
        "$image_url": "item_image_url"
      }
    ]
  }
}

Usage example

{
  "type": "gallery",
  <...>
  "items": [
    {
      "type": "gallery_item",
      "item_image_url": "https://<...>"
    }
  ]
}

Usage features

Templates can be inherited from each other. They are subject to the same rules as when creating a regular template.

Template restrictions:

  • You can't use system names in template and variable names. For example, you can't create a container template or a text field.
  • You can create templates of only basic visual elements.
  • The template must have a type field.

Learn more

Follow DivKit news in the Telegram channel: http://t.me/divkit_news

You can also discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_ru

DivKit Repository