Handlebars.js

Handlebars предоставляет необходимые возможности для эффективного создания семантических шаблонов без проблем.

Handlebars в значительной степени совместим с шаблонами Mustache. В большинстве случаев можно заменить Mustache на Handlebars и продолжить использование ваших текущих шаблонов. Полные подробности можно найти здесь.

Установка

Начало работы

Выражения

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

<div class="entry">
  <h1>{{title}}</h1>
  <div class="body">
    {{body}}
  </div>
</div>

Выражение Handlebars представляет собой {{, некоторые содержимое, за которым следует }}

Подробнее: Выражения

Вы можете передать шаблон в браузер, включив его в тег <script>.

<script id="entry-template" type="text/x-handlebars-template">
  <div class="entry">
    <h1>{{title}}</h1>
    <div class="body">
      {{body}}
    </div>
  </div>
</script>

Важно поместить шаблон внутрь тега <script>. Не помещайте его непосредственно в HTML, так как HTML-парсер может его изменить (например, если он содержит таблицу).

Предварительная компиляция

Скомпилируйте шаблон в JavaScript, используя Handlebars.compile

var source   = document.getElementById("entry-template").innerHTML;
var template = Handlebars.compile(source);

Обратите внимание, что этот подход не рекомендуется для приложений в производстве. Лучший способ — предварительная компиляция шаблонов. Это приведет к меньшему необходимому библиотеке времени выполнения и существенной экономии за счёт того, что шаблон не нужно компилировать в браузере. Это особенно важно при работе с мобильными устройствами.

Подробнее: Предварительная компиляция

Выполнение

Получите HTML-результат оценки шаблона Handlebars, выполнив шаблон с контекстом.

var context = {title: "My New Post", body: "This is my first post!"};
var html    = template(context);

приводит к

<div class="entry">
  <h1>My New Post</h1>
  <div class="body">
    This is my first post!
  </div>
</div>

Подробнее: Выполнение

Вывод HTML

Handlebars экранирует значения, возвращаемые {{expression}}. Если вы не хотите, чтобы Handlebars экранировал значение, используйте "тройной символ", {{{.

<div class="entry">
  <h1>{{title}}</h1>
  <div class="body">
    {{{body}}}
  </div>
</div>

с этим контекстом:

{
  title: "All about <p> Tags",
  body: "<p>This is a post about &lt;p&gt; tags</p>"
}

приводит к:

<div class="entry">
  <h1>All About &lt;p&gt; Tags</h1>
  <div class="body">
    <p>This is a post about &lt;p&gt; tags</p>
  </div>
</div>

Handlebars не будет экранировать Handlebars.SafeString. Если вы пишете помощник, который генерирует собственный HTML, вам обычно нужно вернуть new Handlebars.SafeString(result). В такой ситуации вам необходимо вручную экранировать параметры.

Handlebars.registerHelper('link', function(text, url) {
  text = Handlebars.Utils.escapeExpression(text);
  url  = Handlebars.Utils.escapeExpression(url);

  var result = '<a href="' + url + '">' + text + '</a>';

  return new Handlebars.SafeString(result);
});

Это экранирует переданные параметры, но отмечает ответ как безопасный, поэтому Handlebars не будет пытаться его экранировать, даже если "тройной символ" не используется.

Блочные выражения

Блочные выражения позволяют определять помощники, которые будут вызывать раздел вашего шаблона с другим контекстом, чем текущий. Эти помощники-блоки определяются # перед именем помощника и требуют соответствующего закрывающего знака фигурной скобки /, с тем же именем.

Рассмотрим помощника, который будет генерировать HTML-список:

{{#list people}}{{firstName}} {{lastName}}{{/list}}

Если у нас есть следующий контекст:

{
  people: [
    {firstName: "Yehuda", lastName: "Katz"},
    {firstName: "Carl", lastName: "Lerche"},
    {firstName: "Alan", lastName: "Johnson"}
  ]
}

мы бы создали помощника с именем list для генерации нашего HTML-списка. Помощник получает people в качестве первого параметра и хеш параметров в качестве второго. Хеш параметров содержит свойство с именем fn, которое можно вызвать с контекстом так же, как вы вызывали бы обычный шаблон Handlebars.

Handlebars.registerHelper('list', function(items, options) {
  var out = "<ul>";

  for(var i=0, l=items.length; i<l; i++) {
    out = out + "<li>" + options.fn(items[i]) + "</li>";
  }

  return out + "</ul>";
});

При выполнении шаблон отобразит:

<ul>
  <li>Yehuda Katz</li>
  <li>Carl Lerche</li>
  <li>Alan Johnson</li>
</ul>

Помощники блоков обладают дополнительными функциями, такими как возможность создания раздела else (используется, например, встроенным помощником if).

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

Подробнее: Помощники блоков

Пути Handlebars

Handlebars поддерживает простые пути, как и Mustache.

<p>{{name}}</p>

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

<div class="entry">
  <h1>{{title}}</h1>
  <h2>By {{author.name}}</h2>

  <div class="body">
    {{body}}
  </div>
</div>

Этот шаблон работает с этим контекстом

var context = {
  title: "My First Blog Post!",
  author: {
    id: 47,
    name: "Yehuda Katz"
  },
  body: "My first post. Wheeeee!"
};

Это позволяет использовать шаблоны Handlebars с более сырыми объектами JSON.

Вложенные пути Handlebars также могут включать ../ сегменты, которые оценивают свои пути относительно родительского контекста.

<h1>Comments</h1>

<div id="comments">
  {{#each comments}}
  <h2><a href="/posts/{{../permalink}}#{{id}}">{{title}}</a></h2>
  <div>{{body}}</div>
  {{/each}}
</div>

Даже если ссылка выводится в контексте комментария, она все равно может вернуться к основному контексту (статья) для получения её постоянной ссылки.

Точное значение, до которого ../ будет разрешено, зависит от помощника, вызывающего блок. Использование ../ необходимо только при изменении контекста, поэтому дочерние элементы помощников, таких как each, потребуют использования ../, в то время как дочерние элементы помощников, таких как if, не потребуют этого.

{{permalink}}
{{#each comments}}
  {{../permalink}}

  {{#if title}}
    {{../permalink}}
  {{/if}}
{{/each}}

В этом примере все вышеперечисленные ссылки относятся к одному и тому же значению permalink, даже если они находятся в разных блоках. Это поведение ново с версии Handlebars 4, в примечаниях к выпуску обсуждается предыдущее поведение, а также план миграции.

Handlebars также разрешает конфликт имён между помощниками и полями данных с помощью ссылки this:

<p>{{./name}} or {{this/name}} or {{this.name}}</p>

Любое из вышеперечисленного заставит использовать поле name в текущем контексте, а не помощника с тем же именем.

Комментарии к шаблону с `{{!-- --}}` или `{{! }}`.

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

<div class="entry">
  {{!-- only output author name if an author exists --}}
  {{#if author}}
    <h1>{{author.firstName}} {{author.lastName}}</h1>
  {{/if}}
</div>

Комментарии не будут отображаться в результирующем выводе. Если вы хотите отобразить комментарии, просто используйте html-комментарии, и они будут выведены.

<div class="entry">
  {{! This comment will not be in the output }}
  <!-- This comment will be in the output -->
</div>

Любые комментарии, которые должны содержать }} или другие токены Handlebars, должны использовать синтаксис {{!-- --}}.

Помощники

К помощникам Handlebars можно получить доступ из любого контекста в шаблоне. Вы можете зарегистрировать помощника с помощью метода Handlebars.registerHelper.

<div class="post">
  <h1>By {{fullName author}}</h1>
  <div class="body">{{body}}</div>

  <h1>Comments</h1>

  {{#each comments}}
  <h2>By {{fullName author}}</h2>
  <div class="body">{{body}}</div>
  {{/each}}
</div>

при использовании этого контекста и помощников:

var context = {
  author: {firstName: "Alan", lastName: "Johnson"},
  body: "I Love Handlebars",
  comments: [{
    author: {firstName: "Yehuda", lastName: "Katz"},
    body: "Me too!"
  }]
};

Handlebars.registerHelper('fullName', function(person) {
  return person.firstName + " " + person.lastName;
});

приводит к:

<div class="post">
  <h1>By Alan Johnson</h1>
  <div class="body">I Love Handlebars</div>

  <h1>Comments</h1>

  <h2>By Yehuda Katz</h2>
  <div class="body">Me Too!</div>
</div>

Помощники получают текущий контекст в качестве this контекста функции.

<ul>
  {{#each items}}
  <li>{{agree_button}}</li>
  {{/each}}
</ul>

при использовании этого контекста и помощников:

var context = {
  items: [
    {name: "Handlebars", emotion: "love"},
    {name: "Mustache", emotion: "enjoy"},
    {name: "Ember", emotion: "want to learn"}
  ]
};

Handlebars.registerHelper('agree_button', function() {
  var emotion = Handlebars.escapeExpression(this.emotion),
      name = Handlebars.escapeExpression(this.name);

  return new Handlebars.SafeString(
    "<button>I agree. I " + emotion + " " + name + "</button>"
  );
});

приводит к:

<ul>
  <li><button>I agree. I love Handlebars</button></li>
  <li><button>I agree. I enjoy Mustache</button></li>
  <li><button>I agree. I want to learn Ember</button></li>
</ul>

Если ваш помощник возвращает HTML, который вы не хотите экранировать, убедитесь, что возвращаете новый Handlebars.SafeString.

Литералы

Вызовы помощников также могут иметь передаваемые им литеральные значения, либо в качестве аргументов параметров, либо в качестве аргументов хеша. Поддерживаемые литералы включают числа, строки, true, false, null и undefined.

{{agree_button "My Text" class="my-class" visible=true counter=4}}

Частичные шаблоны

Частичные шаблоны Handlebars позволяют повторно использовать код путём создания общих шаблонов. При рендеринге этого шаблона

<div class="post">
  {{> userMessage tagName="h1" }}

  <h1>Comments</h1>

  {{#each comments}}
    {{> userMessage tagName="h2" }}
  {{/each}}
</div>

при использовании этого частичного шаблона и контекста:

Handlebars.registerPartial('userMessage',
    '<{{tagName}}>By {{author.firstName}} {{author.lastName}}</{{tagName}}>'
    + '<div class="body">{{body}}</div>');

var context = {
  author: {firstName: "Alan", lastName: "Johnson"},
  body: "I Love Handlebars",
  comments: [{
    author: {firstName: "Yehuda", lastName: "Katz"},
    body: "Me too!"
  }]
};

приводит к:

<div class="post">
  <h1>By Alan Johnson</h1>
  <div class="body">I Love Handlebars</div>

  <h1>Comments</h1>

  <h2>By Yehuda Katz</h2>
  <div class="body">Me Too!</div>
</div>

Подробнее: Частичные шаблоны

Встроенные помощники

Handlebars предлагает различные встроенные помощники, такие как if условный и each итератор.

Подробнее: Встроенные помощники

Справочник API

Handlebars предоставляет различные API и методы для приложений и помощников.

Подробнее: Справочник API

Handlebars.js

Начало работы

Выражения

Предварительная компиляция

Выполнение

Вывод HTML

Блочные выражения

Пути Handlebars

Комментарии к шаблону с {{!-- --}} или {{! }}.

Помощники

Литералы

Частичные шаблоны

Встроенные помощники

Справочник API

Комментарии к шаблону с `{{!-- --}}` или `{{! }}`.