Fork me on GitHub

Преимущества


Tuna Tempaltes является частью библиотеки Tuna Framework, и предоставляет широкий функционал для отображения данных в браузере. Его основными плюсами являются:

  1. Скорость - Tuna Templates работает очень быстро, так как обновляeтся отображение только изменившихся данных.
  2. Сохранность DOM-дерева - при отображении данных ссылки на DOM-элементы и слушатели событий сохраняются.
  3. Независимоcть - для работы шаблонизатору требуется только Tuna Common.

Тесты скорости


Тесты для сравнения скорости:

Пример использования


Для использования Tuna Templates практически нет необходимости менять готовую верстку. Для примера возьмем разметку информации пользователя из одной популярной соц. сети:

<div id="user_info">
    <a class="avatar" href>
        <img width="50" height="50" />
    </a>
    <div class="name">
        <a href="#">
            <span>First Name</span>
            <br/>
            <small>Last Name</small>
        </a>
    </div>
</div>

Выберем формат данных для вставки, например:

{
    "firstName": "...",
    "lastName": "...",
    "avatarUrl": "http://..."
}

Далее необходимо отметить элементы, в которых будут отображаться данные. Для отметки используем специальные CSS-классы (удобно начинать их с префиксом t-):

<div id="user_info">
    <a class="avatar" href>
        <img class="t-avatar" width="50" height="50" />
    </a>
    <div class="name">
        <a href="#">
            <span class="t-first-name" ></span>
            <br/>
            <small class="t-last-name"></small>
        </a>
    </div>
</div>

Затем необходимо задать правило, указывающее на то как данные должны отображаться. Для задания правила используется специальная XML разметка.

Внимание!

Для того чтобы специальная разметка работала в IE тег html должен содержать аттрибут xmlns:tuna.

Вот так: <html xmlns:tuna> ... </html>

Добавим на страницу приложения спрятанный контейнер со следующим содержанием:

<tuna:template id="user_template">

    <tuna:spot tuna:target="t-last-name" tuna:path="lastName" />

    <tuna:spot tuna:target="t-first-name" tuna:path="firstName" />

    <tuna:attr tuna:target="t-avatar" tuna:path="avatarUrl"
               tuna:name="src" />

</tuna:template>

Данная разметка представляет собой правило распределения данных, по сути - шаблон. Шаблон состоит из следующих частей.

Объявление шаблона с идентификатором user_template.

<tuna:template id="user_template"> ... </tuna:template>

Объявление точки для вставки данных - в innerHTML элемента с классом t-last-name вставить свойство lastName.

<tuna:spot tuna:target="t-last-name" tuna:path="lastName" />

Объявление аттрибута для вставки данных - в аттрибут src элемента с классом t-avatar вставить свойство avatarUrl.

<tuna:attr tuna:target="t-avatar" tuna:path="avatarUrl"
           tuna:name="src" />

Теперь код для того чтобы шаблон заработал:

// Устанавливаем движок CSS-селекторов
tuna.dom.setSelectorEngine(jQuery.find);

// Элемент для отображения данных
var templateContainer = document.getElementById('user_info');

// Создание шаблона из разметки
var tunaTemplate =
    tuna.tmpl.compileFromMarkup(templateContainer, 'user_template');

// Отображение данных
tunaTemplate.processTransform({
    "firstName": "Sergey",
    "lastName": "Kononenko",
    "avatarUrl": "http://goo.gl/2pRFN"
});

Вот и все! Теперь можно посмотреть на то, как это работает (запустить):

Теги разметки


В качестве примера, при описании тегов и языка запроса данных шаблонизатора будет использоваться набор данных следующего вида:

{ "users": [
    { "name": "Сергей Кононенко",
       "isSelected": true,
       "imageUrl": "http://goo.gl/2pRFN" },
    { "name": "Милый котик",
       "isSelected": true,
       "imageUrl": "http://goo.gl/RHuA3" }
]}

Для разметки шаблона Tuna Templates существуют следующие теги:

tuna:template

Тег разметки шаблона, все остальные теги расположены в теле этого тега. Необходимые аттрибуты:

  • id - идентификатор шаблона, необходим для получения разметки данных из верстки.

Пример: объявление шаблона с идентификатором template_id:

<tuna:template id="template_id">
    <!-- теги разметки -->
</tuna:template>

tuna:spot

Тег объявления DOM-элемента для отображения данных во внутренней разметке. Должен содержать следующие аттрибуты:

  • tuna:target - имя CSS-класса DOM-элементов, в разметке которых необходимо отобразить данные.
  • tuna:path - путь выбоки данных, например: /users/length. Подробнее...

Пример: у всех элементов с CSS-классом t-second-user будут отображать имя второго пользователя в массиве users:

<tuna:spot tuna:target="t-second-user" tuna:path="users/1/name" />

tuna:attr

Тег объявления DOM-элемента для установки данных в аттрибут элемента. Должен содержать теже аттрибуты, что и тег tuna:spot, и дополнительно:

  • tuna:name - имя аттрибута, в который должны устанавливаться данные.

Пример: у всех элементов с CSS-классом t-second-user-picture в аттрибут src будет установленно значение поля imageUrl второго пользователя в массиве:

<tuna:attr tuna:target="t-second-user-picture"
           tuna:path="users/1/imageUrl"
           tuna:name="src" />

tuna:checkbox

Тег объявления DOM-элемента INPUT типа checkbox для установки аттрибута checked в зависимости от переданных данных:

  • В том случае если в качестве данных передан массив, выделены те элементы, аттрибут name, которых найден среди элементов массива.
  • Если в качестве данных передано булево значение оно будет определять выделенность всех элементов.
  • Во всех остальных случаях будут выделены те элементы аттрибут name, которых совпадает со строковым представлением данных.

Должен содержать теже аттрибуты, что и тег tuna:spot

Пример: у всех элементов с CSS-классом t-second-selection будет устанавливаться выделенность в зависимости от значения поля isSelected первого пользователя в массиве:

<tuna:checkbox tuna:target="t-user-selection"
               tuna:path="users/0/isSelected" />

tuna:if

Тег объявления условия в зависимости от выполнения которого, будет выполняться определенное действие с выбранными DOM-элементами.

Должен содержать теже аттрибуты, что и тег tuna:spot, а также один из возможных аттрибутов условия и один - действия с элементом.

Возможные аттрибуты условия:

  • tuna:eq - условие равенства строковых значений данных и указанного в аттрибуте значения.
  • tuna:ne - условие неравенства строковых значений данных и указанного в аттрибуте значения.
  • tuna:isset - условие наличия данных по заданному пути.
  • tuna:notset - условие отсутствия данных по заданному пути.

Информация!

Аттрибуты условий tuna:isset и tuna:notset могут указываться с отсутствующим значением.

Вот так: <tuna:if ... tuna:isset ... />

Возможные аттрибуты действия:

  • tuna:class - установка CSS-класса при успешном результате проверки условия и удаление, при провале.

Пример: всем элементам с CSS-классом t-hide-if-selected будет устанавливаться CSS-класс hide в том случае если значение поля isSelected первого пользователя в массиве будет равно true:

<tuna:if tuna:target="t-not-selected"
         tuna:path="users/0/isSelected" tuna:eq="true"
         tuna:class="hide" />

tuna:list

Тег объявления DOM-элемента отображения списка соотвествующего выбранным данным. Для отображения списка необходим DOM-элемент прототип элемента списка и шаблон для отображения данных в элементе.

Тег спсика должен содержать теже аттрибуты, что и тег tuna:spot, а также:

  • tuna:item-renderer-id - идентификатор прототипа элемента списка.
  • tuna:item-tempalte-id - идентификатор шаблона элемента списка.
  • tuna:key-path - путь данных к ключу элемента в списке. При перерисовке списка элементы не создаются заново, поэтому каждый элемент должен иметь уникальный ключ. Практически всегда достаточно в качестве пути к ключу указывать индекс элемента - $key.

Пример: во всех элементов с CSS-классом t-users-list отобразить список имен пользователей:

<tuna:template id="list_template">
    <tuna:list tuna:target="t-users-list" tuna:path="users"
               tuna:item-renderer-id="users_list_item"
               tuna:item-tempalte-id="user_template"
               tuna:key-path="$key" />
</tuna:template>

<tuna:template id="user_template">
    <tuna:spot tuna:target="t-name" tuna:path="name" />
</tuna:template>

<ul>
    <li id="users_list_item" class="t-name"></li>
</ul>

Язык выбора данных


Для описания пути выбора данных в исходном наборе используется специальный язык запросов, он похож на сильно упрощенный XPath.

Запрос выбора данных (путь) представляет собой последовательность шагов адресации разделенных косой чертой. Например:

users/0/name/length

Данный запрос выберет количество символов в имени первого пользователя в массиве.

Путь может быть как абсолютный так и относительный. Например, чтобы отобразить в элементе списка получить общее число пользователей, можно использовать абсолютный путь:

/users/length

Основным типом шага адресации является ключ элемента данных в текущем контексте. Кроме ключа элемента существуют следующие шаги:

  • "$key" - имя текущего ключа элемента данных. Данный шаг полезен при получении ключа элемента в списке.
  • ".." - возвращение к предыдущему контексту. Например, чтобы получить ключ предыдущего контекста можно использовать следующий путь: "../$key".
  • "." - взятие значения текущего контекста.