528 lines
No EOL
24 KiB
Markdown
528 lines
No EOL
24 KiB
Markdown
# Шаблонизатор LoDash
|
||
|
||
В этой главе мы рассмотрим *шаблонизацию* -- удобный способ генерации HTML-структуры для виджета и её реализацию при помощи библиотеки [LoDash](http://lodash.com).
|
||
[cut]
|
||
|
||
Все виджеты можно условно разделить на три группы по генерации DOM-структуры:
|
||
<ol>
|
||
<li>**Получают готовый HTML/DOM и "оживляют" его.**
|
||
|
||
Это типичный случай в сайтах, где JavaScript -- на ролях "второго помощника". Разметка, CSS уже есть, от JavaScript, условно говоря, требуются лишь обработчики, чтобы менюшки заработали.</li>
|
||
<li>**Создают DOM для компоненты самостоятельно.**
|
||
|
||
В ряде случаев даже на простых страницах нужно генерировать DOM динамически. Например, виджет "подсказка" при наведении на элемент создаёт красивую подсказку и показывает её. Элемент генерируется в JavaScript-коде.
|
||
|
||
В более сложных интерфейсах компоненты генерируют свой DOM на основе данных, полученных с сервера или из других источников.</li>
|
||
<li>**=1+2: должны уметь как "оживить" уже готовый DOM, так и создать свой.**
|
||
|
||
Бывает и так, что виджет должен уметь и то и другое. Например, так работает Twitter, который при загрузке сразу показывает текущие сообщения (HTML генерируется на сервере), но может динамически добавлять новые.
|
||
|
||
Браузер быстро скачивает HTML и отображает его, посетитель видит текущие сообщения и рад этому. А затем уже подгружается объёмный JavaScript, который умеет загружать сообщения с сервера, создавать их и т.д.
|
||
</li>
|
||
</ol>
|
||
|
||
С первым типом виджетов -- вопросов нет. Добавляем обработчики, и дело сделано.
|
||
|
||
Интересно начинается со второго типа, и совсем интересно -- с третьим типом.
|
||
|
||
## Зачем нужны шаблоны?
|
||
|
||
Ранее мы уже видели код `Menu`, который сам создаёт свой элемент:
|
||
|
||
```js
|
||
function Menu(options) {
|
||
// ... приведены только методы для генерации DOM ...
|
||
|
||
function render() {
|
||
elem = $('<div class="menu"></div>');
|
||
elem.append( $('<span/>', { class: "title", text: options.title }))
|
||
|
||
elem.on('mousedown selectstart', false);
|
||
|
||
elem.on('click', '.title', onTitleClick);
|
||
}
|
||
|
||
function renderItems() {
|
||
var items = options.items || [];
|
||
var list = $('<ul/>');
|
||
$.each(items, function(i, item) {
|
||
list.append( $('<li>').text(item) );
|
||
})
|
||
list.appendTo(elem);
|
||
}
|
||
|
||
// ...
|
||
}
|
||
```
|
||
|
||
Понятен ли этот код? Очевидно ли, какой HTML он генерирует?
|
||
|
||
С первого взгляда -- вряд ли. Нужно как минимум внимательно посмотреть и продумать код, чтобы разобраться. Причём это -- с jQuery, если на обычном JavaScript написать, код ещё длиннее и сложнее будет.
|
||
|
||
...А что, если нужно изменить создаваемый HTML? ...А что, если эта задача досталась не программисту, который написал этот код, а верстальщику, который c HTML/CSS проекта знаком отлично, но этот JS-код видит впервые? Вероятность ошибок при этом зашкаливает за все разумные пределы.
|
||
|
||
**К счастью, генерацию HTML можно упростить. Для этого воспользуемся шаблонами.**
|
||
|
||
## Шаблон
|
||
|
||
*Шаблон* -- это заготовка, которая путём подстановки значений (текст сообщения, цена и т.п.) превращается в DOM/HTML.
|
||
|
||
Пример шаблона для меню:
|
||
|
||
```html
|
||
<div class="menu">
|
||
<span class="title"><%-title%></span>
|
||
<ul>
|
||
<% items.forEach(function(item) { %>
|
||
<li><%-item%></li>
|
||
<% }); %>
|
||
</ul>
|
||
</div>
|
||
```
|
||
|
||
Как видно, это обычный HTML, со специальными вставками `<% ... %>`. Для работы с таким шаблоном используется специальная функция `_.template`, которая предоставляется фреймворком [LoDash](http://lodash.com/docs#template), её синтаксис мы подробно посмотрим далее.
|
||
|
||
Взглянем, каким будет вывод меню с использованием шаблона:
|
||
|
||
```js
|
||
// шаблон должен быть в переменной tmpl
|
||
*!*
|
||
// сгенерировать HTML, используя шаблон tmpl с данными title и items
|
||
*/!*
|
||
var html = _.template(tmpl, {
|
||
title: "Сладости",
|
||
items: [
|
||
"Торт",
|
||
"Печенье",
|
||
"Пирожное"
|
||
]
|
||
});
|
||
```
|
||
|
||
Значение `html` в результате:
|
||
|
||
```html
|
||
<div class="menu">
|
||
<span class="title">Сладости</span>
|
||
<ul>
|
||
<li>Торт</li>
|
||
<li>Печенье</li>
|
||
<li>Сладости</li>
|
||
</ul>
|
||
</div>
|
||
```
|
||
|
||
Этот гораздо проще, чем JS-код, не правда ли? Шаблон очень наглядно показывает, что в итоге должно получиться. Шаблоны можно использовать для описания как меню целиком, так и его частей.
|
||
|
||
## Шаблонизация через _.template [#tmpl]
|
||
|
||
Далее мы подробнее познакомимся с `_.template` и синтаксисом шаблонов.
|
||
|
||
[warn header="Holy war detected!"]
|
||
Способов шаблонизации и, в особенности, синтаксисов шаблонов, примерно столько же, сколько способов [поймать льва в пустыне](http://lurkmore.to/%D0%9A%D0%B0%D0%BA_%D0%BF%D0%BE%D0%B9%D0%BC%D0%B0%D1%82%D1%8C_%D0%BB%D1%8C%D0%B2%D0%B0_%D0%B2_%D0%BF%D1%83%D1%81%D1%82%D1%8B%D0%BD%D0%B5). Иначе говоря... много.
|
||
|
||
Эта глава -- совершенно не место для священных войн на эту тему. Далее будет более полный обзор типов шаблонных систем, применяемых в JavaScript, но начнём мы с `_.template`, поскольку эта "шаблонка" проста, быстра и демонстрирует целый класс шаблонных систем, активно используемых в самых разных JS-проектах.
|
||
[/warn]
|
||
|
||
### Синтаксис шаблона
|
||
|
||
Шаблон представляет собой строку со специальными разделителями, которых всего три:
|
||
|
||
<dl>
|
||
<dt>`<% code %>` -- код</dt>
|
||
<dd>Код между разделителями `<% ... %>` будет выполнен "как есть"</dd>
|
||
<dt>`<%= expr %>` -- для вставки HTML</dt>
|
||
<dd>Переменная или выражение внутри `<%= ... %>` будет вставлено "как есть". Например: `<%=title %>` вставит значение переменной `title`, а `<%=2+2%>` вставит `4`.</dd>
|
||
<dt>`<%- expr %>` -- для вставки текста</dt>
|
||
<dd>Переменная или выражение внутри `<%- ... %>` будет вставлено "как текст", то есть с заменой символов `< > & " '` на соответствующие HTML-entities.
|
||
|
||
Например, если `expr` содержит текст `<br>`, то при `<%-expr%>` в результат попадёт (в отличие от `<%=expr%>`) не HTML-тег `<br>`, а текст `<br>`.</dd>
|
||
</dl>
|
||
|
||
### Функция _.template
|
||
|
||
Для работы с шаблоном в библиотеке [LoDash](https://github.com/bestiejs/lodash) есть функция `_.template(tmpl, data, options)`.
|
||
|
||
Её аргументы:
|
||
<dl>
|
||
<dt>`tmpl`</dt>
|
||
<dd>Шаблон.</dd>
|
||
<dt>`data`</dt>
|
||
<dd>Объект с данными.</dd>
|
||
<dt>`options`</dt>
|
||
<dd>Необязательные настройки, например можно поменять разделители.</dd>
|
||
</dl>
|
||
|
||
Эта функция запускает "сборку" шаблона с объектом `data` и возвращает результат в виде строки.
|
||
|
||
Вот так:
|
||
|
||
```js
|
||
//+ run
|
||
// Шаблон*!*
|
||
var tmpl = '<span class="title"><%=title%></span>';
|
||
|
||
// Данные*!*
|
||
var data = {
|
||
title: "Заголовок"
|
||
};
|
||
|
||
// Результат подстановки*!*
|
||
var result = _.template(tmpl, data);
|
||
alert(result); // <span class="title">Заголовок</span>
|
||
```
|
||
|
||
Этот пример похож на операцию "поиск-и-замена": функция `_.template` просто заменила `<%=title%>` в шаблоне `tmpl` на значение свойства `data.title`.
|
||
|
||
Но возможность вставки JS-кода делает шаблоны сильно мощнее.
|
||
|
||
Например, вот шаблон для генерации списка от `1` до `count`:
|
||
|
||
```js
|
||
//+ run
|
||
var tmpl = '<ul>\
|
||
<% for (var i=1; i<=count; i++) { %> \
|
||
<li><%=i%></li> \
|
||
<% } %>\
|
||
</ul>';
|
||
alert( _.template(tmpl, {count: 5}) );
|
||
```
|
||
|
||
Здесь в результат попал сначала текст `<ul>`, потом выполнился код `for`, который последовательно сгенерировал элементы списка, и затем список был закрыт `</ul>`.
|
||
|
||
Скоро мы подробнее разберём, за счёт чего работает функция `_.template`.
|
||
|
||
### Хранение шаблона в документе
|
||
|
||
Шаблон -- это многострочный HTML-текст. Объявлять его в скрипте, как сделано выше -- неудобно и некрасиво.
|
||
|
||
**Один из способов объявления шаблона -- в HTML, внутри <code><script></code> с нестандартным `type`, например `"text/template"`:**
|
||
|
||
```html
|
||
<script type="*!*text/template*/!*" id="menu-template">
|
||
<div class="menu">
|
||
<span class="title"><%-title%></span>
|
||
</div>
|
||
</script>
|
||
```
|
||
|
||
Если `type` не знаком браузеру, то содержимое такого скрипта игнорируется, однако оно доступно при помощи `innerHTML`:
|
||
|
||
```js
|
||
var template = document.getElementById('menu-template').innerHTML;
|
||
```
|
||
|
||
В данном случае выбран `type="text/template"`, однако подошёл бы и любой другой нестандартный, например `text/html`.
|
||
|
||
Полный пример HTML с подключением библиотеки и шаблоном:
|
||
|
||
```html
|
||
<!--+ run height=150 -->
|
||
<!-- библиотека LoDash -->
|
||
<script src="http://cdnjs.cloudflare.com/ajax/libs/lodash.js/2.4.1/lodash.js"></script>
|
||
|
||
<!-- шаблон для списка от 1 до count -->
|
||
<script *!*type="text/template"*/!* id="list-template">
|
||
<ul>
|
||
<% for (var i=1; i<=count; i++) { %>
|
||
<li><%=i%></li>
|
||
<% } %>
|
||
</ul>
|
||
</script>
|
||
|
||
<script>
|
||
var tmpl = document.getElementById('list-template').innerHTML;
|
||
|
||
*!*
|
||
// ..а вот и результат
|
||
var result = _.template(tmpl, {count: 5});
|
||
document.write( result );
|
||
*/!*
|
||
</script>
|
||
```
|
||
|
||
### Как работает функция _.template?
|
||
|
||
Понимание того, как работает `_.template`, очень важно для отладки ошибок в шаблонах.
|
||
|
||
Вызов `_.template(tmpl, data)` выполняется в два этапа:
|
||
<ol>
|
||
<li>Разбивает строку `tmpl` по разделителям и, при помощи `new Function` создаёт на её основе JavaScript-функцию.</li>
|
||
<li>Запускает эту функцию с данными `data`, так что она уже генерирует результат.</li>
|
||
</ol>
|
||
|
||
Эти два процесса можно разделить. Функцию из строки-шаблона можно получить в явном виде вызовом `_.template(tmpl)` (без второго аргумента).
|
||
|
||
Пример:
|
||
|
||
```js
|
||
//+ run
|
||
var compiled = _.template("<h1><%=title%></h1>");
|
||
|
||
alert( compiled( {title: "Заголовок"} ) ); // <h1>Заголовок</h1>
|
||
```
|
||
|
||
Функция `compiled`, которую вернул вызов `_template` из этого примера, выглядит примерно так:
|
||
|
||
```js
|
||
function(obj) {
|
||
obj || (obj = {});
|
||
var __t, __p = '', __e = _.escape;
|
||
with(obj) { \
|
||
__p += '<h1>' +
|
||
((__t = (title)) == null ? '' : __t) +
|
||
'</h1>';
|
||
}
|
||
return __p
|
||
}
|
||
```
|
||
|
||
Она является результатом вызова `new Function("obj", "код")`, где код динамическим образом генерируется внутри `_.template` на основе шаблона:
|
||
<ol>
|
||
<li>Вначале в коде идёт "шапка" -- стандартное начало функции, в котором объявляется переменная `__p`. В неё будет записываться результат.</li>
|
||
<li>Затем добавляется блок `with(obj) { ... }`, внутри которого в `__p` добавляются фрагменты HTML из шаблона, а также переменные из выражений `<%=...%>`. Код из `<%...%>` копируется в функцию "как есть".</li>
|
||
<li>Затем функция завершается, и `return __p` возвращает результат.</li>
|
||
</ol>
|
||
|
||
При вызове этой функции, например `compiled({title: "Заголовок"})`, она получает объект данных как `obj`, здесь это `{title: "Заголовок"}`, и если внутри `with(obj) { .. }` обратиться к `title`, то по правилам [конструкции with](/with) это свойство будет получено из объекта.
|
||
|
||
Поэтому в шаблоне мы можем обращаться к свойствам переданного объекта, напрямую.
|
||
|
||
[smart header="Можно и без `with`"]
|
||
Конструкция `with` является устаревшей, но в данном случае она полезна.
|
||
|
||
Так как функция создаётся через `new Function("obj", "код")` то:
|
||
<ul>
|
||
<li>Она работает в глобальной области видимости, не имеет доступа к внешним локальным переменным.</li>
|
||
<li>Внешний `use strict` на такую функцию не влияет, то есть даже в строгом режиме шаблон продолжит работать.</li>
|
||
</ul>
|
||
Если мы, по какой-то причине, не хотим использовать `with` -- это возможно. Для этого достаточно поставить третий параметр -- `options`, указав параметр `variable` (название переменной с данными).
|
||
|
||
Например:
|
||
|
||
```js
|
||
//+ run
|
||
alert( _.template("<h1><%=menu.title%></h1>", null, {variable: "menu"}) );
|
||
```
|
||
|
||
Результат:
|
||
|
||
```js
|
||
*!*
|
||
function(*!*menu*/!*) {
|
||
*/!*
|
||
var __t, __p = '', __e = _.escape;
|
||
__p += '<h1>' +
|
||
((__t = (menu.title)) == null ? '' : __t) +
|
||
'</h1>';
|
||
return __p
|
||
}
|
||
```
|
||
|
||
При таком подходе переменная `title` уже не будет искаться в объекте данных автоматически, поэтому нужно будет обращаться к ней как `<%=menu.title%>`.
|
||
[/smart]
|
||
|
||
[smart header="Кеширование скомпилированных шаблонов"]
|
||
Чтобы не компилировать один и тот же шаблон много раз, результаты обычно кешируют.
|
||
|
||
Например, глобальная функция `getTemplate("menu-template")` может доставать шаблон из HTML, компилировать, результат запоминать и сразу отдавать при последующих обращениях к тому же шаблону.
|
||
[/smart]
|
||
|
||
### Меню на шаблонах
|
||
|
||
Рассмотрим для наглядности полный пример меню на шаблонах.
|
||
|
||
HTML (шаблоны):
|
||
|
||
```html
|
||
<script type="text/template" id="menu-template">
|
||
<div class="menu">
|
||
<span class="title"><%-title%></span>
|
||
</div>
|
||
</script>
|
||
|
||
<script type="text/template" id="menu-list-template">
|
||
<ul>
|
||
<% items.forEach(function(item) { %>
|
||
<li><%-item%></li>
|
||
<% }); %>
|
||
</ul>
|
||
</script>
|
||
```
|
||
|
||
JS для создания меню:
|
||
|
||
```js
|
||
var menu = new Menu({
|
||
title: "Сладости",
|
||
*!*
|
||
// передаём также шаблоны
|
||
*/!*
|
||
template: _.template($('#menu-template').html()),
|
||
listTemplate: _.template($('#menu-list-template').html()),
|
||
items: [
|
||
"Торт",
|
||
"Пончик",
|
||
"Пирожное",
|
||
"Шоколадка",
|
||
"Мороженое"
|
||
]
|
||
});
|
||
|
||
$(document.body).append(menu.getElem());
|
||
```
|
||
|
||
JS код `Menu`:
|
||
|
||
```js
|
||
function Menu(options) {
|
||
var elem;
|
||
|
||
function getElem() {
|
||
if (!elem) render();
|
||
return elem;
|
||
}
|
||
|
||
function render() {
|
||
var elemHtml = options.template({title: options.title});
|
||
|
||
elem = $(elemHtml);
|
||
|
||
elem.on('mousedown selectstart', false);
|
||
|
||
elem.on('click', '.title', onTitleClick);
|
||
}
|
||
|
||
function renderItems() {
|
||
if (elem.find('ul').length) return;
|
||
|
||
var listHtml = options.listTemplate({items: options.items});
|
||
elem.append(listHtml);
|
||
}
|
||
|
||
function onTitleClick(e) {
|
||
toggle();
|
||
}
|
||
|
||
function open() {
|
||
renderItems();
|
||
elem.addClass('open');
|
||
};
|
||
|
||
function close() {
|
||
elem.removeClass('open');
|
||
};
|
||
|
||
function toggle() {
|
||
if (elem.hasClass('open')) close();
|
||
else open();
|
||
};
|
||
|
||
this.getElem = getElem;
|
||
this.toggle = toggle;
|
||
}
|
||
```
|
||
|
||
Результат:
|
||
|
||
[iframe src="menu-3-template" edit border="1" height="160"]
|
||
|
||
Здесь два шаблона. Первый, для меню, мы уже разобрали, посмотрим на список опций:
|
||
|
||
```html
|
||
<ul>
|
||
<% items.forEach(function(item) { %>
|
||
<li><%-item%></li>
|
||
<% }); %>
|
||
</ul>
|
||
```
|
||
|
||
Если разбить шаблон для списка элементов по разделителям, то он будет таким:
|
||
<ul>
|
||
<li>`<ul>` -- текст</li>
|
||
<li>`<% items.forEach(function(item) { %>` -- код</li>
|
||
<li>`<li>` -- текст</li>
|
||
<li>`<%-item%>` -- вставить значение `item` с экранированием</li>
|
||
<li>`</li>` -- текст</li>
|
||
<li>`<% }); %>` -- код</li>
|
||
<li>`</ul>` -- текст</li>
|
||
</ul>
|
||
|
||
А вот функция, которую возвратит `_.template` для этого шаблона. Она практически один-в-один содержит эти инструкции:
|
||
|
||
```js
|
||
function(obj) {
|
||
obj || (obj = {});
|
||
var __t, __p = '', __e = _.escape;
|
||
with(obj) {
|
||
*!*
|
||
__p += '\n<ul>\n ';
|
||
items.forEach(function(item) {
|
||
__p += '\n <li>' +
|
||
__e(item) + // <%-item%> экранирование функцией _.escape
|
||
'</li>\n ';
|
||
});
|
||
__p += '\n</ul>\n';
|
||
*/!*
|
||
}
|
||
return __p
|
||
}
|
||
```
|
||
|
||
Код попал в функцию "как есть", выражение в `<%-...%>` обёрнуто в вызов [_.escape](http://lodash.com/docs#escape).
|
||
|
||
### Отладка шаблонов
|
||
|
||
Что, если в шаблоне ошибка? Например, синтаксическая. Конечно, ошибки будут возникать, куда же без них.
|
||
|
||
**Шаблон компилируется в функцию, ошибка будет либо при компиляции, либо позже, в процессе её выполнения.**
|
||
|
||
Более сложным является второй случай, так как отладчик при этом останавливается где-то посередине "страшной" функции, и при этом, особенно если шаблонов много и компилируются они где-то раньше по коду -- бывает совершенно неочевидно, из какого шаблона она получена.
|
||
|
||
Попробуйте сами запустить пример с открытыми инструментами разработчика и включённой опцией "остановка при ошибке":
|
||
|
||
```html
|
||
<!--+ run src="index.html" -->
|
||
```
|
||
|
||
В шаблоне допущена ошибка, поэтому отладчик остановит выполнение.
|
||
|
||
В Chrome картина будет примерно такой:
|
||
|
||
<img src="template-debugger.png">
|
||
|
||
**LoDash пытается нам помочь. Он добавляет к шаблонам специальный идентификатор [sourceURL](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/#toc-sourceurl), который служит аналогом "имени файла". На картинке он отмечен красным.**
|
||
|
||
По умолчанию `sourceURL` имеет вид `/lodash/template/source[N]`, где `N` -- постоянно увеличивающийся номер шаблона. В данном случае мы можем понять, что эта функция получена при самой первой компиляции.
|
||
|
||
**Это, конечно, лучше чем ничего, но, как правило, его имеет смысл заменить `sourceURL` на свой.**
|
||
|
||
Это делается при компиляции дополнительным параметром `sourceURL`:
|
||
|
||
```js
|
||
...
|
||
var compiled = _.template(tmpl, null, {sourceURL: '/template/menu-template'});
|
||
...
|
||
```
|
||
|
||
Попробуйте запустить [исправленный пример](/tutorial/widgets/template-error-sourceurl/) и вы увидите в качестве имени файла `/template/menu-template`.
|
||
|
||
[warn header="Не определена переменная -- ошибка"]
|
||
Кстати говоря, а в чём же здесь ошибка?
|
||
|
||
...А в том, что переменная `items` не передана в шаблон. При доступе к неизвестной переменной JavaScript генерирует ошибку.
|
||
|
||
Самый простой способ это обойти -- обращаться к необязательным переменным через `obj`, например `<%=obj.items%>`. Тогда в случае `undefined` просто ничего не будет выведено. Но в данном случае реакция совершенно адекватна, так как для меню список опций `items` является обязательным.
|
||
[/warn]
|
||
|
||
## Итого
|
||
|
||
Шаблоны полезны для того, чтобы отделить HTML от кода. Это упрощает разработку и поддержку.
|
||
|
||
В этой главе подробно разобрана система шаблонизации из библиотеки [LoDash](https://github.com/bestiejs/lodash).
|
||
|
||
Теперь, когда мы с ней знакомы, мы можем как использовать её в своих проектах, так и перейти к более глобальному рассмотрению подходов к шаблонизации.
|
||
|
||
[libs]
|
||
lodash.js
|
||
[/libs] |