Skip to content

Latest commit

 

History

History
169 lines (110 loc) · 10.5 KB

basis.template_format.md

File metadata and controls

169 lines (110 loc) · 10.5 KB
Raw

Формат шаблонов

Шаблоны описываются в формате HTML, но имеет несколько правил:

  • теги должны быть закрыты (либо иметь закрывающий тег, либо <div/>);

  • имена тегов и атрибутов регистрозависимы, лучше всегда писать их в нижнем регистре (это имеет значение на этапе разбора и сравнения);

  • значения должны быть в двойных кавычках;

  • между именем атрибута и равно, как и между равно и значением атрибута не должно быть пробелов.

Несмотря на эти правила, любой текст описания шаблона считается валидным, даже если описание является пустой строкой.

<div class="example">
  <h1>Hello world!</h1>
</div>

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

При разборе шаблона игнорируются переводы строк и пробельные символы до и после перевода строки.

Маркеры

Для обозначения специальных частей шаблона используются специальные маркеры – ссылки и биндинги. Маркеры описываются между фигурными скобками. Между фигурными скобками обычно указывается имя маркера, или список имен разделенных вертикальной чертой |. Проблелы не допускаются.

<div class="item item_{selected}">
  <span class="item_title">{title}</span>
  <div{childNodesElement}/>
</div>

В данном примере задано три маркера: {selected}, {title} и {childNodesElement}. От расположения маркера зависит его значение.

Для имен маркеров действуют те же правила, что и для имен переменных javascript: в имени могут содержаться только латинские буквы (в любом регистре), цифры, знаки _ и $; имя не может начинаться с цифры. Если правила не выполняются хотя бы для одного имени – игнорируется весь маркер.

Маркеры определяют как можно будет сослаться на определеную часть шаблона (ссылки) и куда будут применены данные (биндинги).

Ссылки

Ссылки дают возможность ссылаться на определенный узел в экземпляре шаблона. Когда создается экземпляр шаблона, его DOM фрагмент, для него создается карта, где ключи – это названия ссылок, значения – узлы из его DOM фрагмента.

Ссылка может ссылаться только на один узел, но на один узел может ссылаться несколько ссылок. Можно сослаться на три типа узлов:

  • элемент (тег) – указывается после его имени;

  • комментарий – указывается после <!--, после маркера может любой текст;

  • текстовый узел – указывается вне описаний элементов и комментариев, такой маркер станет текстовым узлом в DOM фрагменте.

<div{element}>
  {text}
  <!--{comment} это пример комментария с маркером -->
</div>

Все другие расположения маркеров ссылками не являются (могут являться биндингами или игнорироваться). Если одно и то же имя указано в нескольких маркерах, то ссылкой является последний.

<div>
  <span{foo} class="first"></span>
  <span{foo} class="second"></span>
</div>

В данном случае ссылка foo будет ссылать на <span> с классом second.

Есть специальная ссылка element. Если маркер с таким именем не указан в шаблоне, то она добавляется первому узлу в шаблоне. В предыдущем примере element будет ссылаться на элемент <div>. Такое поведение является желательным в абсолютном большинстве случаех, поэтому маркер element практически никогда не указывается явно.

Ссылки используются для:

  • модификации описания шаблона, при его вставке в другой шаблон;

  • для того, чтобы владелец шаблона мог ссылаться на определенные узлы DOM фрагмента экземпляра шаблона.

Биндинги

Биндинги используются для определения мест привязки значений (данных) к шаблону (частям его DOM фрагмента). Такие маркеры могут быть расположены:

  • после имени элемента (тега) – биндинг на элемент;

  • в комментарии, сразу после <!-- – биндинг на комментарий;

  • вне описания элементов и комментариев – биндинг на текстовый узел;

  • внутри значения атрибута:

    • class – в зависимости от значения либо будет выставляться определенный класс, либо будет убираться;

        <span class="item item_{selected} item_{state}"/>

    • style – может использоваться в секции значения свойства вместе с другими биндигами и дополнительным текстом;

        <span style="color: {color}; background-position: {x}px {y}px; width: {progress}%"/>

    • остальные атрибуты – страновится частью выражения (сложения частей значения).

        <input checked="{selected}" placeholder="Введите значение {foo} или {bar}"/>

Маркеры в атрибутах должны содержать только одно имя, иначе будут проигнорированы. Для одного узла может быть назначен только один биндинг, поэтому, если в маркере указано несколько имен, то биндингом будет является первое имя.

<span title="{not|a|binding}">
  {title|value}
  <!--{comment|whatever}-->
</span>

В данном примере биндингами будут title и comment.

В зависимости от положения (типа) биндинга и значения, передаваемого в шаблон, применяются разные правила.

XML well-formed

Указание маркеров с использование фигурных скобок является простым и наглядным, но делает описание не валидным с точки зрения XML. Если необходимо, чтобы описание было валидным XML, чтобы использовать его возможности, можно воспользоваться альтенативным способом указания маркеров.

Основная проблема, это маркеры для элементов. Вместо указания маркера в фигурных скобках после имени, можно использовать специальный атрибут b:ref.

<div class="item item_{example}">
  <span b:ref="title">{title}</span>
</div>

Маркеры в атрибутах, для текстовых узлов и комментариев не вызывают проблем.

Технически, конечно, нужно так же определить пространство имен (namespace) b, которое используется в том числе и для специальных тегов шаблонов.

Специальная разметка

В описании шаблонов применяются специальные теги и атрибуты. Их имена предваряются префиксом b:, определяя неймспейс и не создавая конфликтов с остальной разметкой.

Элементы:

Атрибуты: