Fest
Fest — это шаблонизатор общего назначения, компилирующий XML шаблоны в самодостаточные JavaScript функции. Для установки требуется Node.js >= 0.8.
Установка
npm install fest
Введение
Шаблоны представляют собой XML документы, содержащие HTML, текстовые данные и управляющие конструкции. Шаблон задается парным элементом <fest:template>
(с указанием пространства имен http://fest.mail.ru
). Например:
Hello!
Данные передаваемые в шаблон, доступны через переменную с именем, указанным в атрибуте context_name
элемента fest:template
:
Hello, json.name!
Чтобы посмотреть результат работы, приведенных выше шаблонов, необходимо воспользоваться встроенной утилитой fest-render или API библиотеки.
fest-render
Утилита fest-render
используется для компиляции и последующего запуска скомпилированного шаблона из командной строки. В таком случае, для передачи данных в шаблон используется JSON-файл.
hello.json
hello.xml
Hello, json.name!
$ ./node_modules/.bin/fest-render --json=hello.json hello.xml
Hello,John!
Замечание: начальные и конечные пробелы в текстовых узлах удаляются при компиляции. Если необходимо вывести символ пробела, можно вопспользоваться fest:space
.
render()
Функция render()
API компилирует и исполняет шаблон с заданными параметрами.
hello.js
var fest = ;console;
$ node ./hello.js
Hello,John!
Данные и вывод
fest:value
Служит для вывода значения JavaScript выражения. Поддерживаем 4 режима вывода: html (по умолчанию), text, js и json.
<![CDATA[ var value = '"<script/>"';]]>value<!-- "<script/>" -->value<!-- "<script/>" -->value<!-- \"\u003Cscript\/\u003E\" -->value<!-- "\"\u003Cscript/\u003E\"" -->
fest:var
Устаналивает локальную JavaScript переменную.
Ultimate Question of Life, The Universe, and Everythingquestion<!-- Ultimate Question of Life, The Universe, and Everything -->answer<!-- 42 -->
fest:text
Выводит неформатированный текст.
"Hello"<!-- "Hello" -->
fest:space
Служит для вывода пробела. Необходим в тех случаях, когда пробел в тектовом узле удаляется при компиляции, например:
Hello,json.name!<!-- Hello, John! -->
fest:set
Объявляет именованный подшаблон. Содержимое fest:set
не будет выполнено до тех пор, пока не будет вызван блок с таким же имененем с помощью fest:get
.
John
F. Kennedy
Для fest:set
можно использовать атрибут test
. Операция выполнится, если его значение (JavaScript выражение) истинно.
should not be set
Внутри fest:set
доступен контекст params
, передаваемый через fest:get
.
Hello,params.username!{username: "John"}<!-- Hello, John! -->
fest:get
Выводит содержимое блока, объявленного через fest:set
.
{'some': 'data'}
С помощью fest:param
можно передавать в блок XML-данные.
html { title: json.title } json.title params.doctype params.title params.content
Внутри атрибута name
можно использовать JavaScript выражения для вычисления имени блока во время выполнения. Значения выражений, заключенных в фигурные скобки, объединяются с примыкающим текстом. Помимо этого, можно использовать атрибут select
.
var name = 'foo'<!-- foo -->foobar<!-- bar -->
fest:element
Выводит HTML элемент с переменным именем.
var variable = 'table'; fest code fest code
Результат:
fest codefest code
fest:attributes, fest:attribute
Добавляет атрибуты к родительскому элементы. Все fest:attribute
должны быть внутри блока fest:attributes
, который должен идти первым внутри элемента.
json.href Some link
Существует быстрый способ вывести значение в атрибут:
Some link
Имена атрибутов можно вычислять в момент исполнения шаблона:
Управляющие конструкции
fest:each
Предоставляет механизм итерации по объекту.
var obj = {"foo": "bar"} i=obj[i]<!-- foo=bar --> i=v<!-- foo=bar -->
fest:for
Выполняет итерацию по массиву или числовому ряду.
json.items = ['a', 'b', 'c'] json.items[i]<!-- abc --> v<!-- abc --> i<!-- 12345 -->
fest:if
Условный оператор.
It's true!
fest:choose, fest:when, fest:otherwise
Ветвление. Если ни у одного fest:when
условие не выполнено, будет выбрана ветвь fest:otherwise
.
one two More than 2
Остальные конструкции
fest:cdata
Служит для вывода блока CDATA.
<![CDATA[alert ("2" < 3);]]>
fest:comment
Выводит HTML комментарий.
comment
fest:doctype
Задает DOCTYPE генерируемой страницы.
html
fest:script
Служит для выполнения произвольного JavaScript.
<![CDATA[ json.script = 2 < 3; ]]>
Содержимое fest:script
можно загрузить из файла, указав в атрибуте src
путь к нему.
fest:include
Вставляет содержимое другого шаблона с заданным контекстом.
json.list = ['a', 'b', 'c'];
fest:insert
Выводит содержимое файла:
Примеры
Использование
Компиляция с помощью compile():
var fest = ; var data = name: 'Jack "The Ripper"' template = './templates/basic.xml'; var compiled = fest template = 'return ' + compiled; console;
Компиляция с последующей отрисовкой с помощью render():
var fest = ; var data = name: 'Jack "The Ripper"' template = './templates/basic.xml'; console;
basic.xml
Hello,json.name <!-- По умолчанию все значения fest:value экранируются --> <!-- Необходимо использовать fest:space или fest:text для явного указания строк с пробелами -->
Результат:
Hello, Jack "The Ripper"
Вложенные шаблоны
Данные на вход:
var data = people: name: 'John' age: 20 name: 'Mary' age: 21 name: 'Gary' age: 55 append: '>>'
foreach.xml (основной шаблон):
<!-- Контекст можно передавать во вложенные шаблоны --> <!-- Значением iterate может быть любое js-выражение --> <!-- Передаваемые значения будут доступны в контексте params --> json.people[i]
person.xml:
<!-- Используем set для объявления блока, который используем в родительском шаблоне --> <![CDATA[ var first = params.name[0], other = params.name.slice(1); ]]> json.append first other
Результат:
>>Gary>>Mary>>John
Использование set и get
http://e.mail.ru msglist sentmsg?compose / / <!-- fest:attribute добавляет параметр к родительскому тегу --> Все сообщения Написать письмо
Результат:
Все сообщения Написать письмо
Интернационализация
fest:plural
По умолчанию доступна поддержка плюрализации для русского и английского языка. В параметрах fest.compile
можно передать любую другую функцию плюрализации.
один рубль|%s рубля|%s рублей
Или англоязычный вариант:
one ruble|%s rubles
Чтобы вывести символ “%” внутри тега fest:plural
используйте “%%”:
…1%%…|…%s%%…|…%s%%…
fest:message и fest:msg
Позволяет указать границы фразы для перевода и контекст для снятия многозначности. Например,
ЛукЛук
Для каждого fest:message
, fest:msg
, обычного текста, заключенного между XML тегами (опция auto_message
), или текстового значения некоторых атрибутов компилятор вызывает функцию events.message
(если такая была указана в параметрах). Данный механизм используется в fest-build
утилите для построения оригинального PO-файла.
Пример вызова fest-build
для создания PO-файла:
$ fest-build --dir=fest --po=ru_RU.po --compile.auto_message=true
Пример компиляции локализованных шаблонов:
$ fest-build --dir=fest --translate=en_US.po
Пример компиляции одного шаблона:
$ fest-compile path/to/template.xml
$ fest-compile --out=path/to/compiled.js path/to/template.xml
$ fest-compile --out=path/to/compiled.js --translate=path/to/en_US.po path/to/template.xml
Contribution
Необходимо установить Grunt:
$ git clone git@github.com:mailru/fest.git
$ cd fest
$ sudo npm install -g grunt-cli
$ npm install
$ grunt
Grunt используется для валидации JS (тестов) и запуска тестов. Перед отправкой пулл-риквеста убедись, что успешно выполнены git rebase master
и grunt
.
Если необходимо пересобрать шаблоны spec/expected, то выполните:
$ ./bin/fest-build --dir=spec/templates --exclude='*error*' --compile.beautify=true --out=spec/expected/build/initial
$ ./bin/fest-build --dir=spec/templates --exclude='*error*' --compile.beautify=true --out=spec/expected/build/translated --translate=spec/templates/en_US.po