Создание шаблонов
-----------------

Шаблон это JSON, YAML или PY файл, в котором указан набор фигур и параметры из рендеринга.

 В PY файле необходимо создать функцию `get_template(**kwargs)` которая вернёт шаблоны

Этот файл имеет строгую структуру, поэтому требует правильного составления.

Шаблон это словарь, в котором должно быть 4 основных поля:

name
    Имя шаблона (обязательное поле)

defaults
    Значения по умолчанию, используемые в фигурах. Предполагается что эти данные сохраняются внутри шаблона.

variables
    Различные переменные контекста, которые вы передаёте в рендер. Они используются в переменных фигур.

shapes
    Список фигур в шаблоне


.. note:: Поле ``variables`` имеет бОльший приоритет чем ``defaults``. Если имя параметра не найдено в поле ``variables``
          то будет поиск в параметрах ``defaults``.


.. code-block:: json

    {
        "defaults": {
            "font_size": 20
        },
        "variables": {
            "user": "User Name"
        },
        "shapes": [
            {
                "type": "shapename", "x": 0, "y": 0, "parm": "val"
            }
        ]
    }

.. note:: Шаблоны поддерживают комментарии с помощью двойного слеша ``//`` или хеша ``#``

.. note:: Фигуры рендерятся в порядке их указания в шаблоне. Чем позже указана фигура, тем позже она будет
          отрендерена и будет находиться поверх предыдущих.

Контекст
========

Что такое контекст? Это словарь, в котором указаны различные данные для рендера.
Чаще всего это данные, которые следует отобразить в шаблоне. Но так же могут быть другие данные.

- путь к картинке логотипа для рендера на шаблоне

- переменные для вычисления различных условий рендера

- оверрайды для любых дефолтных значений

И другие значения

Чем отличается поля ``variables`` и ``defaults``? Поле ``variables`` заполняется вне шаблона и приходит в виде словаря
как аргумент процесса рендера. Поле ``defaults`` сохраняется непосредственно в шаблоне.
Запрашиваемое значение всегда сначала ищется в ``variables``, и если не находится то берется из ``defaults``.
То есть ``variables`` имеет бОльший приоритет поиска.

Фигуры
======

Шаблонизатор поддерживает определённый набор фигур. Полный список смотрите в разделе :ref:`shapes`

Выражения
=========

Шаблонизатор поддерживает выражения в параметрах. Подробней в разделе :ref:`expressions`

Viewer
======

У шаблонизатора нет никакого GUI в котором можно легко расставить фигуры по картинке. Но есть удобный виджет
интерактивного предпросмотра шаблона. Подробней в разделе :ref:`viewer`

Как создать шаблон
==================

Для начала создайте пустой JSON-файл с любым именем. Начальные данные могут быть такими:

.. code-block:: json

    {
      "templates": [
        {
          "name": "new",
          "defaults": {
            "font_size": "4u",
            "text_spacing": 10
          },
          "variables": {},
          "shapes": []
        }
      ]
    }

Теперь можно заполнять фигурами список ``shapes`` и смотреть как изменяется шаблон с помощью вьювера.

В словарь ``variables`` удобно добавлять любе значения для теста. В реальном использовании этот словарь
передаётся из аргументов рендера. Не забудьте очистить его после финализации шаблона.

В словарь ``defaults`` записывайте значения, которые должны оставаться в шаблоне. Например пути к используемым файлам
или повторяющиеся значения.

.. note:: Когда утвердите шаблон, не забудьте очистить словарь ``variables`` и указать правильное имя шаблона в поле ``name``.

.. note:: В одном файле может быть несколько шаблонов, которые могут друг друга наследовать.
