[Из песочницы] Handlebars. Руководство к действию21.12.2015 13:19

Данная статья содержит в себе описание основных возможностей шаблонизатора Handlebars и является свободным переводом его официальной документации. Итак, поехали…

С помощью Handlebars вы сможете построить эффективные семантические шаблоны. Шаблоны Handlebars во многом совместимы с шаблонами Mustache — в большинстве случаев они взаимозаменяемы. Полные сведения можно найти по этой ссылке.

Для начала работы с Handlebars необходимо подключить файл handlebars.js:

Шаблоны Handlebars выглядят как обычный HTML, со встроенными handlebars-выражениями.

Самое простое handlebars-выражение представляет собой простой идентификатор:

{{some_contents}}

Идентификатором может быть любой символ Unicode за исключением следующих:

Пробел ! " # % & ' ( ) * + , . / ; < = > @ [ \ ] ^ ` { | } ~

Вы можете вставить шаблон Handlebars в ваш HTML-код, включив его в тэг :

В JavaScript шаблон компилируется с помощью Handlebars.compile:

var source   = $("#entry-template").html();
var template = Handlebars.compile(source);

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

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

var context = { title: "Собаке Качалова" };
var html    = template(context);

Мы получим HTML-код:


  Собаке Качалова

Handlebars-выражения могут иметь пути, разделенные точками. Они позволяют искать свойства, вложенные ниже текущего контекста:


  {{title}}
  {{author.name}}

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

Этот шаблон будет работать со следующим контекстом:

var context = {
  title: "Собаке Качалова",
  author: {
    id: 47,
    name: "Сергей Есенин"
  }
};

Пути Handlebars также могут включать …/ сегменты, позволяющие указать путь относительно родительского контекста. С ними мы столкнемся, когда будем рассматривать блоковые хелперы.

Handlebars экранирует выражения, помещенные в двойные скобки {{ }}. Чтобы избежать этого, необходимо поместить выражение в тройные скобки {{{ }}}. Чтобы в будущем при написании генерирующего HTML-код хэлпера избежать экранирования возвращаемого им результата, мы будем возвращать new Handlebars.SafeString(result)

Хелперы

Handlebars-хелпер представляет собой простой идентификатор, за которым следуют ноль или более параметров (через пробел). Каждый параметр представляет собой handlebars-выражение. Параметром хелпера может также являться простая строка, число или логическое значение. Хелпер производит определенные операции с параметрами и возвращает HTML код.

{{{link "Подробнее..." poem.url}}}

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


  {{poem.title}}
  {{link "Подробнее..." poem.url}}

Вы можете зарегистрировать хелпер с помощью метода Handlebars.registerHelper. При использовании следующего контекста и хелпера:

var context = {
  poem: {
    title: "Собаке Качалова",
    url: "Sobake_Kachalova.html"
  }
};
Handlebars.registerHelper('link', function(text, url) {
  url = Handlebars.escapeExpression(url);      //экранирование выражения
  text = Handlebars.escapeExpression(text);
  return new Handlebars.SafeString("" + text + "");
});

Получим следующий результат:


  Собаке Качалова
  Подробнее...

Handlebars-хелперам также можно передать последовательность пар ключ-значение после всех непарных параметров. Ключи должны быть простыми идентификаторами, а значения — handlebars-выражениями (т.е. значения могут быть идентификаторами, путями, или строками).

{{link "Подробнее..." href=poem.url class="poem"}}

Регистрация хелпера:

Handlebars.registerHelper('link', function(text, options) {
  console.log(options.hash['href']);   //значение, лежащее в poem.url
  console.log(options.hash['class']); //"poem"
  return new Handlebars.SafeString("" + Handlebars.escapeExpression(text) + "");
});

Потенциально может возникнуть конфликт имен между хелперами и полями данных (скажем, у нас используются в одном контексте handlebars-выражение {{name}} и хелпер {{name}}). Handlebars предлагает нам следующую возможность разрешения этого конфликта:

{{./name}} or {{this/name}} or {{this.name}}

Любое из вышеперечисленных handlebars-выражений вызовет поле данных {{name}} в текущем контексте, а не хелпер с тем же самым именем.

Блоковые хелперы

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

{{#helper_name}}some_block{{/helper_name}}

При регистрации хелпера параметры в Handlebars.registerHelper передаются в том порядке, в котором они были переданы хелперу пользователем. Вслед за всеми указанными пользователем параметрами следует параметр options. Он имеет следующие свойства:

1) options.fn — содержит функцию, которая ведет себя как обычный скомпилированный шаблон Handlebars. В качестве параметра функция принимает контекст и возвращает строку.

Пример 1. Давайте определим блоковый хелпер, который изменяет разметку обернутого в него текста:


  {{#bold}}{{body}}{{/bold}}

Регистрация:

Handlebars.registerHelper('bold', function(options) {
  return '' + options.fn(this) + '';
});

Так как содержание блокового хелпера экранируется при вызове options.fn (context), Handlebars не экранирует результат, возвращаемый блоковым хелпером. Если это сделать, то внутреннее содержание будет экранировано дважды!

Здесь в качестве параметра функции мы передали текущий контекст (this). Давайте укажем другой контекст, передав его хелперу как параметр:

Пример 2.


{{author}}
{{#with poem}}
  {{title}}
  {{../author}}
  {{year}}
{{/with}}

Выполнить этот шаблон мы могли бы со следующим JSON, имеющим вложенные в объект poem ключи title и year:

{
  author: "Сергей Есенин",
  poem: {
    title: "Собаке Качалова",
    year: 1925
  }
}

Регистрация:

Handlebars.registerHelper('with', function(context, options) {
  console.log(context);   //{title: "Собаке Качалова", year: 1925}
  return options.fn(context);
});

Мы получим HTML-код:


  Сергей Есенин
  Собаке Качалова
  Сергей Есенин
  1925

Обратим внимание, что в этом примере мы использовали сегмент …/ для указания пути к свойству author, находящемуся вне контекста poem.

Пример 3. Давайте напишем итератор, создающий обертку

.
```
{{#list nav}}
  {{title}}
{{/list}}
```
Выполнить этот шаблон мы могли бы, используя следующий контекст:
```
{
  nav: [
    { url: "http://www.museum-esenin.ru/biography", title: "Биография Сергея Есенина" },
    { url: "http://www.fedordostoevsky.ru/biography", title: "Биография Ф. М. Достоевского" },
  ]
}
```
Регистрация хелпера:
```
Handlebars.registerHelper('list', function(context, options) {
  var ret = "";

  for(var i=0, j=context.length; i" + options.fn(context[i]) + "";
  }

  return ret + "";
});
```
Мы получим HTML-код:
```
  Биография Сергея Есенина
  Биография Ф. М. Достоевского
```
2) options.inverse — функция используется при работе с управляющими структурами Handlebars. Управляющие структуры обычно не изменяют текущий контекст — вместо этого они решают, вызвать ли блок, основываясь на значении переданного параметра.
```
{{#if isActive}}
  
{{else}}
  
{{/if}}
```
Handlebars возвращает блок, следующий за {{else}}, через функцию options.inverse:
```
Handlebars.registerHelper('if', function(conditional, options) {
  if(conditional) {
    return options.fn(this);
  } else {
    return options.inverse(this);
  }
});
```
3) options.hash — содержит последовательность пар ключ-значение, передаваемых хелперу после всех непарных параметров.

Пример. Давайте вернемся к хелперу list и сделаем возможным добавление любого количества атрибутов создаваемой нами обертки

[Из песочницы] Handlebars. Руководство к действию21.12.2015 13:19

Собаке Качалова

{{title}}

{{author.name}}

Хелперы

{{poem.title}}

Собаке Качалова

Блоковые хелперы

{{firstName}} {{lastName}}

Автор неизвестен

ВНИМАНИЕ: Эта запись не имеет лицензии!

{{title}}

{{firstName}} {{lastName}}

Автор неизвестен