• Directives
• Creating templates

namespace

Директива декларирует пространство имён для файла в котором оно используется, т.е. все декларируемые в этом файле шаблоны будут частью заданного пространства имён.

Synopsis

Description

Пространства имён Snakeskin служат для экспорта шаблонов из файла, поэтому перед тем как начать создавать сами шаблоны нужно предварительно объявить пространство имён, а уже после они будут экспортироваться по схеме exports.namespace.template. В рамках одного файла может быть только одно пространство имён.

For example:

- namespace demo

/// Шаблон экспортируется как exports.demo.index
- template index()
	Hello world!

{namespace demo}

/// Шаблон экспортируется как exports.demo.index
{template index()}
	Hello world!
{/template}

Пространство имён может состоять из множества частей (свойств объекта), причём Snakeskin проверяет существование заданного пути и создаёт только те части, которые отсутствуют.

- namespace demo.helloWorld

/// exports.demo.helloWorld.index
- template index()
	Hello world!

/// exports.demo.helloWorld.bar
- template bar()
	Hello people!

{namespace demo.helloWorld}

/// exports.demo.helloWorld.index
{template index()}
	Hello world!
{/template}

/// exports.demo.helloWorld.bar
{template bar()}
	Hello people!
{/template}

Т.к. пространство имён превращается в JS объект, то на декларируемое имя накладываются те же ограничения, что и на свойство объекта, однако можно использовать декларацию через квадратные скобки ([ ... ]), которая позволяет применять любые символы и сложные выражения, например:

- namespace ['@demo']['hello' + 'World']

/// exports['@demo']['helloWorld'].index
- template index()
	Hello world!

{namespace ['@demo']['hello' + 'World']}

/// exports['@demo']['helloWorld'].index
{template index()}
	Hello world!
{/template}

Если первая часть имени использует синтаксис без квадратных скобок, то будет создана глобальная (для Snakeskin) переменная с таким же именем:

/// var demo = exports.demo['helloWorld']
- namespace demo['hello' + 'World']

- template index()
	Hello world!

/// var demo = exports.demo['helloWorld']
{namespace ['@demo']['hello' + 'World']}

{template index()}
	Hello world!
{/template}

Пространство имён создаёт with биндинг, который можно использовать для удобного вызова шаблонов в рамках файла.

- namespace demo
- template parent()
	Hello world!

/// Тоже самое, что и extends exports.demo.parent
- template child() extends @parent

{namespace demo}
{template parent()}
	Hello world!
{/template}

/// Тоже самое, что и extends exports.demo.parent
{template child() extends @parent}
{/template}

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

Плейсхолдеры имени

При декларации пространства имён можно использовать специальные плейсхолдеры, которые заменяются при трансляции на некоторое статическое значение в рамках своего контекста.

%dirName%

Плейсхолдер %dirName% заменяется на имя директории, в которой лежит исходный файл Snakeskin, например:

foo/index.ss

- namespace %dirName%.bar

/// exports.foo.bar.index
- template index()
	Hello world!

{namespace %dirName%.bar}

/// exports.foo.bar.index
{template index()}
	Hello world!
{/template}

Т.к. в названии директории могут встречаться “запрещённые” символы, то лучше использовать синтаксис с квадратными скобками:

- namespace [%dirName%].bar
- template index()
	Hello world!

{namespace [%dirName%].bar}
{template index()}
	Hello world!
{/template}

%fileName%

Плейсхолдер %fileName% заменяется на имя исходного файла-шаблона (без расширения), например:

foo/index.ss

- namespace %fileName%.bar

/// exports.index.bar.index
- template index()
	Hello world!

{namespace %fileName%.bar}

/// exports.index.bar.index
{template index()}
	Hello world!
{/template}

Т.к. в названии файла могут встречаться “запрещённые” символы, то лучше использовать синтаксис с квадратными скобками:

- namespace [%fileName%].bar
- template index()
	Hello world!

{namespace [%fileName%].bar}
{template index()}
	Hello world!
{/template}

• Directives
• Creating templates

template

This directive declares a template with specified name and input parameters.

Synopsis

Description

Snakeskin template is just a JavaScript function, that can be used inside regular code after being transpiled. Every template returns a string by default. You can adjust this behaviour by specifying a custom renderMode or explicit return of a value.

A template’s name matches name of function in JavaScript, so it should comply the same rules. template declaration should be preceeded by namespace declaration and should have a unique name. Besides, a template can be declared only within global scope. Nesting is not allowed - use blocks for this.

The directive is very similar to declaration of functions in JavaScript, for instance:

- namespace demo
- template index(name = 'world')
	Hello {name}!

{namespace demo}
{template index(name = 'world')}
	Hello {name}!
{/template}

You can find more advanced ways of parameters declaring here.

Nested namespaces

При декларации шаблона можно использовать пространства имён, подобно тому, как это делается в namespace, например:

foo/index.ss

- namespace demo
- template %fileName%.index(name = 'world')
	Hello {name}!

{namespace demo}
{template %fileName%.index(name = 'world')}
	Hello {name}!
{/template}

Механика здесь точно такая же, как и у namespace, поэтому рассматриваться отдельно не будет, однако, есть небольшой дополнительный нюанс: если последняя часть имени декларируется без квадратных скобок, то она будет установлена как свойство name полученной функции JavaScript, т.е.

- namespace demo
- template index(name = 'world')
	Hello {name}!

{namespace demo}
{template index(name = 'world')}
	Hello {name}!
{/template}

Превратится в:

exports.demo.index = function index(name) {
	name = name != null ? name : 'world';
	return 'Hello ' + name + '!';
};

Predefined variables

There are a couple of predefined constants and functions that can be used inside templates.

TPL_NAME - a string containing a full template’s name along with name of namespace as it was at the moment of declaration.

PARENT_TPL_NAME - a string containing a full name of a template’s parent along with its namespace as it was at the moment of declaration.

callee - link to a running template (i.e. function).

self - link to a callee.Blocks object, containing blocks (methods) of a running template.

$0 - link to current DOM node (only if renderMode equals 'dom').

$tagName - имя созданного через директиву тега (.getVar('$tagName'));

$attrKey - ключ атрибута тега созданного через директиву;

$attrs - объект атрибутов тега созданного через директиву (.getVar('$attrs'));

$class - значение липкой ссылки.

getTplResult - a function returning a template’s result. Accepts a boolean argument, pointing whether the result should be reseted after the function calling.

clearTplResult - a function that resets a template’s result.

Modificators

Snakeskin templates support declaration modificators.

Generator template

A template will be translated into a generator function (you should use a polyfill for older browsers).

- namespace demo
- template *hello()
	- yield
		Hello world!

{namespace demo}
{template *hello()}
	{yield}
		Hello world!
	{/}
{/template}

Async template

A template will be translated into an async function (you should use a polyfill for older browsers).

- namespace demo
- async template hello()
	- var data = await db.getData()
	Hello {data.name}!

{namespace demo}
{async template hello()}
	{var data = await db.getData() /}
	Hello {data.name}!
{/template}

Decorators

Every template can be attached by decorator functions (that can also be templates). Decorator accepts a link to original function and must return a function as its result.

- namespace demo
- import Typograf from 'typograf'

- template typograf(params)
	- return
		() => target
			- return
				() =>
					- return new Typograf(params).execute(target.apply(this, arguments))

- @typograf({locale: 'ru'})
- template index()
	Sport is well!

{namespace demo}
{import Typograf from 'typograf'}

{template typograf(params)}
	{return}
		{() => target}
			{return}
				{() =>}
					{return new Typograf(params).execute(target.apply(this, arguments)) /}
				{/}
			{/}
		{/}
	{/}
{/template}

{@typograf({locale: 'ru'})}
{template index()}
	Sport is well!
{/template}

Local translation options

When declaring a template you can attach specific translation rules by using @= operator.

- namespace demo
- template index() @= literalBounds ['<?php', '?>']
	{{ Hello }}

{namespace demo}
{template index() @= literalBounds ['<?php', '?>']}
	{{ Hello }}
{/template}

Template inheritance

Snakeskin templates are similar to classes in other programming languages, it means they have methods, properties and can inherit from others. Keyword extends is used to setup inheritance.

- namespace demo
- template index() extends anotherTemplate
	...

{namespace demo}
{template index() extends anotherTemplate
	...
{/template}

More about inheritance.

Explicit call of a template inside other template

Since Snakeskin templates are just functions, they can be called inside each other via the call directive.

- namespace demo

- template hello()
	Hello world!

- template index()
	/// Because "hello" and "index" are declared in the same
	/// namespace, we can use brief form of call
	/// (full form {+= demo.hello() /} is also avaliable though).
	+= @hello()

{namespace demo}

{template hello()}
	Hello world!
{/template}

{template index()}
	/// Because "hello" and "index" are declared in the same
	/// namespace, we can use brief form of call
	/// (full form {+= demo.hello() /} is also avaliable though).
	{+= @hello() /}
{/template}

• Directives
• Creating templates

interface

Директива декларирует шаблон-интерфейс c заданным именем и входными параметрами.

Synopsis

Description

Шаблон-интерфейс отличается от простого шаблона тем, что после трансляции в JS будет получена пустая функция с входными параметрами, например:

- namespace demo
- interface index(name = 'world')
	Hello {name}!

{namespace demo}
{interface index(name = 'world')}
	Hello {name}!
{/interface}

Превратится в:

exports.demo.index = function index(name) {};

В остальном механика таких шаблонов полностью идентичная template.

• Directives
• Creating templates

placeholder

Директива декларирует шаблон-плейсхолдер c заданным именем и входными параметрами.

Synopsis

Description

Шаблон-плейсхолдер отличается от простого шаблона тем, что он существует только на этапе трансляции и не будет включён в конечный JS, например:

- namespace demo
- placeholder index(name = 'world')
	Hello {name}!

{namespace demo}
{placeholder index(name = 'world')}
	Hello {name}!
{/placeholder}

Превратится в:

В остальном механика таких шаблонов полностью идентичная template.

• Directives
• Creating templates

block

Директива декларирует статичный блок or подшаблон c заданным именем и входными параметрами.

Synopsis

Description

Директива block несёт двойную функциональность: с одной стороны она позволяет создавать статичные блоки, а с другой - вызываемые. Блоки являются фундаментальной ячейкой Snakeskin, т.к. играют ключевую роль при наследовании, но если статичный блок - это просто выделение фрагмента текста, чтобы в дальнейшем иметь возможность его переопределить в дочернем шаблоне, то вызываемый блок - это по сути вложенная функция-шаблон, т.е. после декларации его можно неоднократно вызывать и передавать различные параметры.

Разница в декларации статичного блока от динамического заключается в наличии скобок для параметров, например:

- namespace demo
- template index()
	/// Статичный блок
	- block hello
		Hello world!

	/// Вызываемый блок
	- block helloWithName(name)
		Hello {name}!

{namespace demo}
{template index()}
	/// Статичный блок
	{block hello}
		Hello world!
	{/}

	/// Вызываемый блок
	{block helloWithName(name)}
		Hello {name}!
	{/}
{/template}

Параметров у блока может быть неограниченное количество, а т.к. директива block является функциональной, то она реализует стандартный механизм декларации параметров. По умолчанию вызываемые блоки возвращают строки, однако это поведение можно поменять задав специальный renderMode or явно вернув значение через директиву return.

Название блока соответствует названию функции в JavaScript, поэтому оно подчиняется тем же правилам, причём статичные блоки и вызываемые лежат в одном пространстве имён. В рамках шаблона не может быть 2-х блоков с одинаковым названием.

Блок как метод шаблона

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

При создании вызываемого блока он ставиться как свойство .Blocks.названиеБлока исходного шаблона, и, как правило, вызывается с помощью директивы call и указателя self, например:

- namespace demo
- template index()
	- block hello(name)
		Hello {name}!

	+= self.hello('kobezzza')

{namespace demo}
{template index()}
	{block hello(name)}
		Hello {name}!
	{/}

	{+= self.hello('kobezzza') /}
{/template}

Примечание: this внутри блока ссылается на this шаблона.

Стандартные переменные блока

Каждый вызываемый блок определяет ряд функций, которые можно использовать в нём:

getTplResult - функция, которая возвращает результат работы блока, также может принимать один логический входной параметр, при задании которого после вызова функции результат работы блока будет обнуляться;

clearTplResult - функция, которая обнуляет результат работы блока.

Внешние блоки

Любые блоки могут декларироваться как внутри шаблона or другого блока, так и в глобальной области, но при такой декларации есть ряд дополнительных правил: блок должен декларироваться до шаблона, методом которого он является; блок должен явно указывать к какому шаблону он принадлежит (для этого используется оператор ->), например:

- namespace demo

- block index->hello(name)
	Hello {name}!

- template index()
	+= self.hello('kobezzza')

{namespace demo}

{block index->hello(name)}
	Hello {name}!
{/block}

{template index()}
	{+= self.hello('kobezzza') /}
{/template}

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

Самовызываемые блоки

Вызываемый блок можно вызвать немедленно после декларации: для этого используется специальный оператор =>, например:

- namespace demo

- template index()
	- block hello(name) => 'kobezzza'
		Hello {name}!

{namespace demo}

{template index()}
	{block hello(name) => 'kobezzza'}
		Hello {name}!
	{/}
{/template}

Такой же синтаксис можно использовать и для внешних блоков:

- namespace demo

- block index->hello(name) => 'kobezzza'
	Hello {name}!

- template index()

{namespace demo}

{block index->hello(name) => 'kobezzza'}
	Hello {name}!
{/block}

{template index()}
{/template}

Ссылка & для удобного рекурсивного вызова блока

При использовании call для вызова блока можно использовать специальный указать &, который ссылается на блок внутри которого он используется - это удобно для организации рекурсий, например:

- namespace demo

- template index()
	- block iterate(i)
		{i}

		- if i
			+= &(--i)

	+= self.iterate(5)

{namespace demo}

{template index()}
	{block iterate(i)}
		{i}

		{if i}
			{+= &(--i) /}
		{/}
	{/}

	{+= self.iterate(5) /}
{/template}

• Directives
• Creating templates

set

The directive sets the value to the specified option.

Synopsis

Supported options

• renderMode
• renderAs
• localization
• i18nFn
• i18nFnOptions
• literalBounds
• bemFilter
• filters
• language
• ignore
• tolerateWhitespaces
• doctype

• Directives
• Creating templates

end

Директива декларирует завершение блочной директивы.

Synopsis

Description

Директива используется для завершения блочной директивы в классическом синтаксисе Snakeskin (в jade-like) она ставиться автоматически). У директивы есть 4-ре формы использования:

/// Полная форма
{if 1 > 2}
	...
{end if}

/// Сокращённая форма
{if 1 > 2}
	...
{end}

/// Альтернативная полная форма
{if 1 > 2}
	...
{/if}

/// Альтернативная сокращённая форма
{if 1 > 2}
	...
{/}

Какую форму использовать решает сам разработчик, но следует отметить, что при использовании форм с указанием имени закрываемой директивы Snakeskin будет проверять правильность, т.е.:

{if 1 > 2}
	...
{/else} /// Ошибка

• Directives
• Execution / output

output

Директива выполняет заданное выражение и выводит результат в шаблон (на выводимое выражение по умолчанию накладываются фильтры html и undef).

Synopsis

Description

Директива output используется когда нам нужно вывести в текст шаблона значение переменной or выражения.

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

- namespace demo
- template calc(a, b)
	a + b = {a + b}

{namespace demo}
{template calc(a, b)}
	a + b = {a + b}
{/template}

Однако нужно следить, чтобы первое слово выводимого выражения не было равно имени другой директивы Snakeskin, иначе возникнет ошибка:

- namespace demo
- template index(link)
	{link} /// Ошибка

{namespace demo}
{template index(link)}
	{link} /// Ошибка
{/template}

Для того чтобы пример выше отработал корректно достаточно просто взять наше выражение в круглые скобки:

- namespace demo
- template index(link)
	{(link)}

{namespace demo}
{template index(link)}
	{(link)}
{/template}

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

- namespace demo
- template calc(a, b)
	{a > 1 ? --a * b : Math.random() * b}

{namespace demo}
{template calc(a, b)}
	{a > 1 ? --a * b : Math.random() * b}
{/template}

На всё выводимое выражение по умолчанию накладывается специальный фильтр html, который экранирует html сущности, а также фильтр undef на каждый отдельный чанк выражения, который преобразует значение undefined в ''. Чтобы отменить это поведение нужно использовать фильтры !html и !undef or задать глобальное через параметр трансляции filters.

- namespace demo
- template index(val1, val2)
	{(val1|!undef) + (val2|!undef) |!html}

{namespace demo}
{template index(val1, val2)}
	{(val1|!undef) + (val2|!undef) |!html}
{/template}

Директива может использоваться только внутри шаблонов or внешних блоков.

• Directives
• Execution / output

call

Директива выполняет заданное выражение и выводит результат в шаблон (на выводимое выражение по умолчанию накладываются фильтр undef).

Synopsis

Description

Директива call похожа на output, т.е. она тоже вставляет результат выражения в шаблон, однако, она не накладывает по умолчанию на выводимые данные фильтр html, т.е. выводимое выражение не экранируется и это является аналогом использования фильтра !html.

Директива начинается с ключевого слова call (или символов +=), которое должно сопровождаться ссылкой на выводимое значение или выражение (заключать выражение в скобки не обязательно), например:

- namespace demo
- template index()
	+= 1 + 2

{namespace demo}
{template index()}
	{+= 1 + 2 /}
{/template}

Для удобства использования call в классическом синтаксисе существует короткая форма закрытия директивы, например:

/// Обычное закрытие
{+= 1 + 2}{/}

/// Короткая форма закрытия
{+= 1 + 2 /}

Главным кейзом использования call является вызов блоков и других шаблонов внутри шаблона, поэтому выводимые данные не экранируются, т.к. они уже и так экранированы, например:

- namespace demo

- template helper()
	< .foo
		Hello world!

- template index()
	/// <div class="foo">Hello world!</div>
	+= @helper()

	/// &lt;div class=&quot;foo&quot;&gt;Hello world!&lt;/div&gt;
	{@helper()}

{namespace demo}

{template helper()}
	{< .foo}
		Hello world!
	{/}
{/template}

{template index()}
	/// <div class="foo">Hello world!</div>
	{+= @helper() /}

	/// &lt;div class=&quot;foo&quot;&gt;Hello world!&lt;/div&gt;
	{@helper()}
{/template}

Директива может использоваться только внутри шаблонов or внешних блоков.

Расширенная декларация

Директива поддерживает специальную расширенную форму для передачи параметров-шаблонов в вызываемую функцию, например:

- namespace demo

- template helper(text)
	< .output
		{text}

- template index()
	/// <div class="output"><div class="foo">Hello world!</div></div>
	+= @helper()
		< .hello
			Hello world!

{namespace demo}

{template helper(text)}
	{< .output}
		{text}
	{/}
{/template}

{template index()}
	/// <div class="output"><div class="foo">Hello world!</div></div>
	{+= @helper()}
		{< .hello}
			Hello world!
		{/}
	{/}
{/template}

Внутри такой декларации можно использовать любые допустимые директивы, например, if, forEach и т.д. Если необходимо передать несколько параметров, то нужно использовать директиву putIn:

- namespace demo

- template helper(text1, text2)
	< .output1
		{text1}

	< .output2
		{text2}

- template index()
	+= @helper()
		*
			< .hello
				Hello world!
		*
			< .goodbye
				Goodbye cruel world!

{namespace demo}

{template helper(text1, text2)}
	{< .output1}
		{text1}
	{/}

	{< .output2}
		{text2}
	{/}
{/template}

{template index()
	{+= @helper()}
		{*}
			{< .hello}
				Hello world!
			{/}
		{/}
		{*}
			{< .goodbye}
				Goodbye cruel world!
			{/}
		{/}
	{/}
{/template}

Первый вызов putIn можно опустить:

- namespace demo

- template helper(text1, text2)
	< .output1
		{text1}

	< .output2
		{text2}

- template index()
	+= @helper()
			< .hello
				Hello world!
		*
			< .goodbye
				Goodbye cruel world!

{namespace demo}

{template helper(text1, text2)}
	{< .output1}
		{text1}
	{/}

	{< .output2}
		{text2}
	{/}
{/template}

{template index()
	{+= @helper()}
		{< .hello}
			Hello world!
		{/}
		{*}
			{< .goodbye}
				Goodbye cruel world!
			{/}
		{/}
	{/}
{/template}

Допускается совмещать передачу параметров в обычной и расширенной форме.

- namespace demo

- template helper(a, b, text1, text2)
	{a + b}

	< .output1
		{text1}

	< .output2
		{text2}

- template index()
	+= @helper(1, 2)
			< .hello
				Hello world!
		*
			< .goodbye
				Goodbye cruel world!

{namespace demo}

{template helper(a, b, text1, text2)}
	{a + b}

	{< .output1}
		{text1}
	{/}

	{< .output2}
		{text2}
	{/}
{/template}

{template index()
	{+= @helper(1, 2)}
		{< .hello}
			Hello world!
		{/}
		{*}
			{< .goodbye}
				Goodbye cruel world!
			{/}
		{/}
	{/}
{/template}

Examples

Передача функции-параметра с помощью func

- namespace demo

- template helper(fn)
	+= fn(1, 2)

- template index()
	+= @helper()
		() => a, b
			{a + b}

{namespace demo}

{template helper(fn)}
	{+= fn(1, 2) /}
{/template}

{template index()
	{+= @helper()}
		{() => a, b}
			{a + b}
		{/}
	{/}
{/template}

Передача объекта-параметра с помощью target

- namespace demo

- template helper(@params)
	{@data}

- template index()
	+= @helper()
		- target {}
			* data
				< .hello
					Hello world!

{namespace demo}

{template helper(@params)}
	{@data}
{/template}

{template index()
	{+= @helper()}
		{target {}}
			{* data}
				{< .hello}
					Hello world!
				{/}
			{/}
		{/}
	{/}
{/template}

• Directives
• Execution / output

void

The directive executes the specified expression, but no outputs the result to a template.

Synopsis

Description

Директива void используется когда нам нужно выполнить некоторую логику, но чтобы она никак не отобразилась в шаблоне, например, сделать инкремент переменной or вывести текст в консоль разработчика.

Директива начинается с ключевого слова void (или символа ?), которое должно сопровождаться выражением (заключать выражение в скобки не обязательно). Самая простая форма выглядит так:

- void console.log('hello')

{void console.log('hello')}

The directive can be used anywhere.

Examples

- namespace demo
? console.log('hello world')
- template index()
	: a = 0
	- void a++
	{a} /// 1

{namespace demo}
{? console.log('hello world')}
{template index()}
	{: a = 0}
	{void a++}
	{a} /// 1
{/template}

• Directives
• Execution / output

return

Директива return является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript.

Synopsis

Description

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

Директива начинается с ключевого слова return, которое может сопровождаться ссылкой на возвращаемое значение или выражение, например:

- namespace demo
- template index()
	- return 1 + 2

{namespace demo}
{template index()}
	{return 1 + 2 /}
{/template}

Для удобства использования return в классическом синтаксисе существует короткая форма закрытия директивы, например:

/// Обычное закрытие
{return 1 + 2}{/}

/// Короткая форма закрытия
{return 1 + 2 /}

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

Расширенная декларация

Директива может включать возвращаемое значение в своё тело - это удобно, когда возвращаемое значение является подшаблоном, например:

- namespace demo
- template index()
	/// Шаблон вернёт ссылку на функцию,
	/// которая складывает два числа
	- return
		() => a, b
			- return a + b

{namespace demo}
{template index()}
	/// Шаблон вернёт ссылку на функцию,
	/// которая складывает два числа
	{return}
		{() => a, b}
			{return a + b /}
		{/}
	{/}
{/template}

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

• Directives
• Global context

eval

Директива создаёт блок, который выполнится на этапе трансляции, но не войдёт в конечный JS.

Synopsis

Description

Т.к. любой код, размещённый вне тела шаблона будет выполняться как на этапе трансляции, так и войдёт в конечный JS код, то директива eval позволяет создать блок, содержимое которого будет исключаться из результирующего кода, но по прежнему будет выполняться на этапе трансляции.

- eval
	? console.log('Hello world!')

{eval}
	{? console.log('Hello world!')}
{/}

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

• Directives
• Global context

head

Директива создаёт блок, который не выполнится на этапе трансляции, но войдёт в конечный JS.

Synopsis

Description

Т.к. любой код, размещённый вне тела шаблона будет выполняться как на этапе трансляции, так и войдёт в конечный JS код, то директива head позволяет создать блок, содержимое которого по прежнему не будет исключаться из результирующего кода, но не будет выполняться на этапе трансляции, а также переменные, которые были объявлены на корневом уровне директивы, будут считаться глобальными.

- namespace demo

- head
	/// Данный forEach не выполнится на этапе трансляции,
	/// но войдёт в конечный JS
	- forEach [1, 2, 3] => el
		? console.log(el)

	/// Данная переменная глобальная,
	/// хоть и объявлена внутри блочной директивы
	: foo = 'bar'

- template index()
	? console.log(foo) /// 'bar'

{namespace demo}

{head}
	/// Данный forEach не выполнится на этапе трансляции,
	/// но войдёт в конечный JS
	{forEach [1, 2, 3] => el}
		{? console.log(el)}
	{/}

	/// Данная переменная глобальная,
	/// хоть и объявлена внутри блочной директивы
	{var a = 1 /}
{/}

{template index()}
	{? console.log(foo)} /// 'bar'
{/template}

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

• Directives
• Scope

with

Директива задаёт область видимости для поиска свойств объекта.

Synopsis

Description

Директива позволяет задать “виртуальную” область видимости для объекта, чтобы затем обращаться к его свойствам с помощью специального модификатора контекста @, например:

- var base = {child: {name: 'Moscow'}}

- with base.child
	? console.log(@name) /// Moscow

{var base = {child: {name: 'Moscow'}}}

{with base.child}
	{? console.log(@name)} /// Kobezzza
{/}

С помощью @ можно как получать, так и устанавливать свойства объекту.

- var base = {child: {name: 'Moscow'}}

- with base.child
	? @name = 'Washington'
	? @type = 'city'

? console.log(base.child.name) /// Washington
? console.log(base.child.type) /// city

{var base = {child: {name: 'Moscow'}}}

{with base.child}
	{? console.log(@name)} /// Kobezzza
	{? @name = 'Washington'}
{/}

{console.log(base.child.name)} /// Washington

Любые входные параметры функциональных директив Snakeskin (template, forEach и т.д.) поддерживают короткую запись декларации with.

- namespace demo
- template index(@params)
	{@name} /// params.name

{namespace demo}
{template index(@params)}
	{@name} /// params.name
{/template}

Такая запись эквивалентна:

- namespace demo
- template index(params)
	- with params
		{@name}

{namespace demo}
{template index(params)}
	{with params}
		{@name}
	{/}
{/template}

Можно вкладывать with-блоки друг в друга, например:

- namespace demo
- template index()
	- with params
		{@name} /// params.name
		- with @data
			{@type} /// params.data.type

{namespace demo}
{template index(params)}
	{with params}
		{@name} /// params.name
		{with params}
			{@type} /// params.data.type
		{/}
	{/}
{/template}

The directive can be used anywhere.

• Directives
• Vars

var

Директива создаёт переменную/ые с указанным именем и значением.

Synopsis

Description

Vars в Snakeskin имеют блочную область видимости и по своей семантике напоминают let из JS ES2015.

Директива var позволяет декларировать сразу несколько переменных через запятую (аналогично как это делается в JS).

Директива начинается с ключевого слова var (или символа :), которое должно сопровождаться списком имён создаваемых переменных (через запятую). Для присвоения значений созданной переменной необходимо поставить символ = после имени.

Самая простая форма выглядит так:

- var a = 1

{var a = 1 /}

Для удобства использования var в классическом синтаксисе существует короткая форма закрытия директивы, например:

/// Обычное закрытие
{var a = 1}{/}

/// Короткая форма закрытия
{var b = 2 /}

В отличии от JS переменные в Snakeskin декларируются только после места декларации.

: a = 2
- if true
	? console.log(a) /// 2
	: a = 1
	? console.log(a) /// 1

{: a = 2 /}
{if true}
	{? console.log(a)} /// 2
	{: a = 1 /}
	{? console.log(a)} /// 1
{/}

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

: a = 2
? console.log(a) /// 2
: a = 1
? console.log(a) /// 1

{: a = 2 /}
{? console.log(a)} /// 2
{: a = 1 /}
{? console.log(a)} /// 1

The directive can be used anywhere.

putIn декларация

С помощью ключевого слова putIn можно присвоить переменной подшаблон Snakeskin, однако при такой декларации допускается создавать только одну переменную за раз, например:

- namespace demo
- template index(value)
	: putIn tpl
		- if value !== 404
			< .hello
				Hello world!

		- else
			< .error
				404

{namespace demo}
{template index(value)}
	{: putIn tpl}
		{if value !== 404}
			{< .hello}
				Hello world!

		{else}
			{< .error}
				404
			{/}
		{/}
	{/}
{/template}

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

Examples

- namespace demo
- template index(value)
	- if true
		: a = 1
		{a}

	{a} /// Error, a is not defined

	: b = 1, c = 2
	- if true
		{b} /// 1
		{c} /// 2

	{b} /// 1

{namespace demo}
{template index(value)}
	{if true}
		{: a = 1 /}
		{a}
	{/}

	{a} /// Error, a is not defined

	{: b = 1, c = 2 /}
	{if true}
		{b} /// 1
		{c} /// 2
	{/}

	{b} /// 1
{/template}

• Directives
• Vars

const

Директива создаёт константу с указанным именем и значением.

Synopsis

Description

Константы Snakeskin не имеют ничего общего с константами из JS ES2015 и служат для других целей. Константы глобальны в рамках своего шаблона, поэтому не может быть 2-х констант с одинаковым именем. Значение константы может меняться по ходу выполнения шаблона.

При декларации константы не требуется специального ключевого слова (хотя допускается), например:

- namespace demo
- template index()
	- val = 'hello'
	{val}

{namespace demo}
{template calc(a, b)}
	{val = 'hello'}
	{val}
{/template}

С логической точки зрения константы Snakeskin - это свойства класса (шаблона), т.е. они доступны в любом месте шаблона и их можно переопределять в дочернем шаблоне. Константа может быть свойством объекта (включая свойство другой константы), например:

- namespace demo
- template index()
	- val = {}
	- val.name = 'Kobezzza'

{namespace demo}
{template calc(a, b)}
	{val = {}}
	{val.name = 'Kobezzza'}
{/template}

После декларации константы станет невозможным в рамках шаблона объявление переменной с таким же именем.

- namespace demo
- template index()
	- val = {}
	- var val = 1 /// Ошибка

{namespace demo}
{template calc(a, b)}
	{val = {}}
	{var val = 1 /} /// Ошибка
{/template}

Константы могут создаваться только внутри шаблонов or внешних блоков.

Распад константы

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

- namespace demo
- template index()
	- val = {}
	- forEach [1, 2] => val
		{val} /// 1, 2

{namespace demo}
{template calc(a, b)}
	{val = {}}
	{forEach [1, 2] => val}
		{val} /// 1, 2
	{/}
{/template}

Вызываемые константы

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

- namespace demo
- template index()
	< title
		- title = 'Главная страница' ?

{namespace demo}
{template calc(a, b)}
	{< title}
		{title = 'Главная страница' ?}
	{/}
{/template}

• Directives
• Vars

global

Директива создаёт супер-глобальную переменную с указанным именем и значением.

Synopsis

Description

Супер-глобальная переменная Snakeskin - это свойство объекта Snakeskin.Vars, т.е. такая переменная доступна как из JavaScript, так и во всех файлах шаблонов. Устанавливать такие переменные можно из JS (причём можно до трансляции) или из шаблонов. Основной use-case супер-глобальных переменных - это прокидывание конфига, т.е. некоторый аналог переменных среды в операционной системе.

Задание из JS

Чтобы задать значение супер-глобальной переменной перед непосредственной трансляцией можно использовать параметр vars, а также в любой момент времени допускается вносить изменения напрямую в объект Snakeskin.Vars, например:

Snakeskin.Vars.server = 'localhost';
Snakeskin.Vars.port = '1989';

Задание и чтение из SS

Для задания супер-глобальной переменной из SS можно использовать несколько способов:

1. Использование директивы global, например:

- global server = 'localhost'
- global port = '1989'

{global server = 'localhost'}
{global port = '1989'}

Вне тела шаблонов можно опустить ключевое слово global:

- server = 'localhost'
- port = '1989'

{server = 'localhost'}
{port = '1989'}

При задании имение допускается использовать скобочную нотацию:

- ['server'] = 'localhost'
- ['port'] = '1989'

{['server'] = 'localhost'}
{['port'] = '1989'}

2. Использование литеральной формы через модификатор @@, например:

- @@server = 'localhost'
- @@port = '1989'

{@@server = 'localhost'}
{@@port = '1989'}

Такой вариант можно использовать как вне шаблонов, так и внутри их. Литеральная форма также поддерживает скобочную нотацию:

- @@['server'] = 'localhost'
- @@['port'] = '1989'

{@@['server'] = 'localhost'}
{@@['port'] = '1989'}

Чтение

Для чтения супер-глобальных переменных используется модификатор @@, например:

- @@server = 'localhost'
? console.log(@@server)

{@@server = 'localhost'}
{? console.log(@@server)}

Вызываемые переменные

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

- namespace demo
- template index()
	< title
		- @@title = 'Главная страница' ?

{namespace demo}
{template calc(a, b)}
	{< title}
		{@@title = 'Главная страница' ?}
	{/}
{/template}

• Directives
• Logic directives

if

Директива if является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript.

Synopsis

Description

Директива позволяет вашему шаблону в зависимости от условий выполнить некоторую логику или сгенерировать фрагмент шаблона, основываясь на значении переменной or выражения.

Директива начинается с ключевого слова if, которое должно сопровождаться выражением (заключать выражение в скобки не обязательно).

Самая простая форма выглядит так:

- if true
	Hello world!

{if true}
	Hello world!
{/if}

The directive can be used anywhere. Вместе с основной директивой можно использовать дополнительные:

1. else - аналог else в JS;
2. else if - аналог else if в JS;
3. else unless - аналог else if (!(...)) в JS.

Examples

- namespace demo
- template index(value)
	< .result
		- if val > 3
			< .success
				Значение больше чем 3.

		- else if val < 3
			< .fail
				Значение меньше чем 3.

		- else
			< .error
				Значение рано 3.

{namespace demo}
{template index(value)}
	{< .result}
		{if val > 3}
			{< .success}
				Значение больше чем 3.
			{/}

		{else if val < 3}
			{< .fail}
				Значение меньше чем 3.
			{/}

		{else}
			{< .error}
				Значение рано 3.
			{/}
		{/}
	{/}
{/template}

• Directives
• Logic directives

unless

Директива unless является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в CoffeeScript.

Synopsis

Description

Директива является инвертной формой if, т.е. если if блок выполнится только в том случае когда условное выражение будет приведено к true, то unless выполнится в случае false.

Директива позволяет вашему шаблону в зависимости от условий выполнить некоторую логику или сгенерировать фрагмент шаблона, основываясь на значении переменной or выражения.

Директива начинается с ключевого слова unless, которое должно сопровождаться выражением (заключать выражение в скобки не обязательно).

Самая простая форма выглядит так:

- unless false
	Hello world!

{unless false}
	Hello world!
{/}

The directive can be used anywhere. Вместе с основной директивой можно использовать дополнительные:

1. else - аналог else в JS;
2. else if - аналог else if в JS;
3. else unless - аналог else if (!(...)) в JS.

Examples

- namespace demo
- template index(value)
	< .result
		- unless val >= 3
			< .success
				Значение меньше чем 3.

		- else unless val <= 3
			< .fail
				Значение больше чем 3.

		- else
			< .error
				Значение рано 3.

{namespace demo}
{template index(value)}
	{< .result}
		{unless val >= 3}
			{< .success}
				Значение меньше чем 3.

		{else unless val <= 3}
			{< .fail}
				Значение больше чем 3.

		{else}
			{< .error}
				Значение рано 3.
		{/}
	{/}
{/template}

• Directives
• Logic directives

switch

Директива switch является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript (break ставится автоматически после каждого блока case).

Synopsis

Description

Подобно if or unless директива позволяет вашему шаблону в зависимости от условий выполнить некоторую логику или сгенерировать фрагмент шаблона, основываясь на значении переменной or выражения, но предоставляет более удобный синтаксис когда нужно сравнить выражение сразу с несколькими вариантами.

Директива начинается с ключевого слова switch, которое должно сопровождаться выражением (заключать выражение в скобки не обязательно), а внутри директивы должны использоваться вспомогательные директивы case и/или default. The directive can be used anywhere.

Директива case начинается с ключевого слова case (или символа >), а после должно следовать выражение выражение для сравнения со switch. В отличии от реализации case в JS - оператор break ставиться автоматически после каждого блока.

Декларация default полностью идентичная аналогичной в JS.

Examples

- namespace demo
- template index(value)
	< .result
		- switch value
			- case 1
				< .value-1
					value == 1

			- case 2
				< .value-2
					value == 2

			> 3
				< .value-3
					value == 3

			- default
				Условие, которое выполнится по умолчанию.

{namespace demo}
{template index(value)}
	{< .result}
		{switch value}
			{case 1}
				{< .value-1}
					value == 1
				{/}
			{/}

			{case 2}
				{< .value-2}
					value == 2
				{/}
			{/}

			{> 3}
				{< .value-3}
					value == 3
				{/}
			{/}

			{default}
				Условие, которое выполнится по умолчанию.
			{/}
		{/}
	{/}
{/template}

• Directives
• Циклы

for

Директива for является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript.

Synopsis

Description

Директива создаёт цикл, т.е. блок цикла будет выполняется до тех пор, пока управляющее логическое выражение не станет ложным or пока цикл не будет сброшен вручную. Директива проводит инициализацию перед первым шагом цикла. Затем выполняется проверка условия цикла, и в конце каждой итерации происходит изменение управляющей переменной.

for инициализация; логическое выражение (условие); шаг (итерация)
	команда

Самая простая форма выглядит так:

- for var i = 0; i < 3; i++
	Итерация - {i}

{for var i = 0; i < 3; i++}
	Итерация - {i}
{/for}

The directive can be used anywhere. Для управления циклом внутри блока можно использовать директивы:

1. break - полностью прерывает выполнение цикла;
2. continue - прерывает текущую итерацию и переходит к следующей.

Examples

Простой перебор массива

- namespace demo
- template index()
	- var arr = [1, 2, 3]

	/// Т.к. переменные Snakeskin имеют блочную область видимости,
	/// то i будет доступен только внутри for
	- for var i = 0; i < arr.length; i++
		{arr[i]}

{namespace demo}
{template index()}
	{var arr = [1, 2, 3] /}

	/// Т.к. переменные Snakeskin имеют блочную область видимости,
	/// то i будет доступен только внутри for
	{for var i = 0; i < arr.length; i++}
		{arr[i]}
	{/}
{/template}

Простой перебор объекта

- namespace demo
- template index()
	- var obj = {a: 1, b: 2}

	/// Т.к. переменные Snakeskin имеют блочную область видимости,
	/// то key будет доступен только внутри for
	- for var key in obj
		{key}

{namespace demo}
{template index()}
	{var obj = {a: 1, b: 2} /}

	/// Т.к. переменные Snakeskin имеют блочную область видимости,
	/// то key будет доступен только внутри for
	{for var key in obj}
		{key}
	{/}
{/template}

Сброс итераций

- namespace demo
- template index()
	- var obj = {a: 1, b: 2}
	- for var key in obj
		- if !obj.hasOwnProperty(key)
			- continue

		{key}
		- break

{namespace demo}
{template index()}
	{var obj = {a: 1, b: 2} /}
	{for var key in obj}
		{if !obj.hasOwnProperty(key)}
			{continue}
		{/}

		{key}
		{break}
	{/}
{/template}

• Directives
• Циклы

while

Директива while является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript.

Synopsis

Description

Директива создаёт цикл, т.е. блок цикла будет выполняется до тех пор, пока управляющее логическое выражение не станет ложным or пока цикл не будет сброшен вручную.

Директива начинается с ключевого слова while, которое должно сопровождаться выражением (заключать выражение в скобки не обязательно).

Самая простая форма выглядит так:

- var i = 3
- while i--
	{i}

{var i = 3 /}
{while i--}
	{i}
{/while}

The directive can be used anywhere. Для управления циклом внутри блока можно использовать директивы:

1. break - полностью прерывает выполнение цикла;
2. continue - прерывает текущую итерацию и переходит к следующей.

Examples

Перебор массива

- namespace demo
- template index()
	- var arr = [1, 2, 3]
	- while arr.length
		{arr[0]}
		? arr.shift()

{namespace demo}
{template index()}
	{var arr = [1, 2, 3] /}
	{while arr.length}
		{arr[0]}
		{? arr.shift()}
	{/}
{/template}

Сброс итераций

- namespace demo
- template index()
	- var i = 3
	- while i--
		{i}
		- break

{namespace demo}
{template index()}
	{var i = 3 /}
	{while i--}
		{i}
		{break}
	{/}
{/template}

• Directives
• Циклы

do

Директива do является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript.

Synopsis

Description

Директива создаёт цикл, т.е. блок цикла будет выполняется до тех пор, пока управляющее логическое выражение не станет ложным or пока цикл не будет сброшен вручную. Отличие do от while состоит в том, что цикл do-while выполняется по крайней мере один раз, даже если условие изначально ложно.

Директива начинается с ключевого слова do, а выражение для проверки идёт после вложенного блока цикла вместе с директивой while (заключать выражение в скобки не обязательно).

Самая простая форма выглядит так:

- var i = 3
- do
	{i}
- while i--

{var i = 3 /}
{do}
	{i}
{while i--}

The directive can be used anywhere. Для управления циклом внутри блока можно использовать директивы:

1. break - полностью прерывает выполнение цикла;
2. continue - прерывает текущую итерацию и переходит к следующей.

Examples

Перебор массива

- namespace demo
- template index()
	- var arr = [1, 2, 3]
	- do
		{arr[0]}
		? arr.shift()
	- while arr.length

{namespace demo}
{template index()}
	{var arr = [1, 2, 3] /}
	{do}
		{arr[0]}
		{? arr.shift()}
	{while arr.length}
{/template}

Бесконечный цикл

- namespace demo
- template index()
	- var i = 0
	- do
		{i}
		? i++

{namespace demo}
{template index()}
	{var i = 0 /}
	{do}
		{i}
		{? i++}
	{/}
{/template}

Сброс итераций

- namespace demo
- template index()
	- var i = 3
	- do
		{i}
		- break
	- while i--

{namespace demo}
{template index()}
	{var i = 3 /}
	{do}
		{i}
		{break}
	{while i--}
{/template}

• Directives
• Iterators

forEach

Директива итерирует заданный объект (с учётом hasOwnProperty) or массив.

Synopsis

Description

Директива итерирует заданное значение с помощью функции Snakeskin.forEach и может работать как с объектами, так и с массивами.

Общая форма директивы следующая:

forEach ссылка на объект or сам объект => параметры функции через запятую
	команда

For example:

- forEach [1, 2, 3] => el
	{el}

{forEach [1, 2, 3] => el}
	{el}
{/forEach}

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

Для управления обходом внутри итератора можно использовать директивы:

1. break - полностью прерывает выполнение итератора;
2. continue - прерывает текущую итерацию и переходит к следующей.

Параметры для массива

1. Значение элемента;
2. Номер итерации;
3. Ссылка на итерируемый массив;
4. Объект:
   • isFirst - является ли элемент первым;
   • isLast - является ли элемент последним;
   • length - длина массива.

Параметры для таблицы

1. Значение элемента;
2. Ключ;
3. Ссылка на итерируемый объект;
4. Объект:
   • i - номер итерации;
   • isFirst - является ли элемент первым;
   • isLast - является ли элемент последним;
   • length - длина массива.

forEach и return

Несмотря на то что forEach использует функцию при обходе объекта, поведение директивы приближено к поведению цикла, т.е. внутри можно использовать директивы break, continue и return, принцип работы которых не будет отличаться, например:

- namespace demo

/// Шаблон вернёт 1
- template index()
	- forEach [1, 2, 3] => el
		- return el
	Hello world

{namespace demo

/// Шаблон вернёт 1
{template index()}
	{forEach [1, 2, 3] => el}
		{return el /}
	Hello world

Examples

Простой перебор массива

- namespace demo
- template index()
	- var arr = [1, 2, 3]
	- forEach arr => el
		{el}

{namespace demo}
{template index()}
	{var arr = [1, 2, 3] /}
	{forEach arr => el}
		{el}
	{/}
{/template}

Перебор массива с заданием with в списке входных параметров

- namespace demo
- template index()
	- var arr = [{name: 'Koba'}, {name: 'Over'}]
	- forEach arr => @el
		{@name}

{namespace demo}
{template index()}
	{var arr = [{name: 'Koba'}, {name: 'Over'}] /}
	{forEach arr => @el}
		{@name}
	{/}
{/template}

Простой перебор объекта

- namespace demo
- template index()
	- var obj = {a: 1, b: 2}
	- forEach obj => el, key
		{el} {key}

{namespace demo}
{template index()}
	{var obj = {a: 1, b: 2} /}
	{forEach obj => el, key}
		{el} {key}
	{/}
{/template}

Сброс итераций

- namespace demo
- template index()
	- forEach [1, 2, 3] => el
		{el}
		- break

{namespace demo}
{template index()}
	{forEach [1, 2, 3] => el}
		{el}
		{break}
	{/}
{/template}

• Directives
• Iterators

forIn

Директива итерирует заданный объект (без учёта hasOwnProperty).

Synopsis

Description

Директива итерирует заданный объект с помощью функции Snakeskin.forIn.

Общая форма директивы следующая:

forIn ссылка на объект or сам объект => параметры функции через запятую
	команда

For example:

- forIn {a: 1, b: 2} => el
	{el}

{forIn {a: 1, b: 2} => el}
	{el}
{/forIn}

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

Для управления обходом внутри итератора можно использовать директивы:

1. break - полностью прерывает выполнение итератора;
2. continue - прерывает текущую итерацию и переходит к следующей.

Параметры функции итератора

1. Значение элемента;
2. Ключ;
3. Ссылка на итерируемый объект;
4. Объект:
   • i - номер итерации;
   • isFirst - является ли элемент первым;
   • isLast - является ли элемент последним;
   • length - длина массива.

forIn и return

Несмотря на то что forIn использует функцию при обходе объекта, поведение директивы приближено к поведению цикла, т.е. внутри можно использовать директивы break, continue и return, принцип работы которых не будет отличаться, например:

- namespace demo

/// Шаблон вернёт 1
- template index()
	- forIn {a: 1, b: 2} => el
		- return el
	Hello world

{namespace demo

/// Шаблон вернёт 1
{template index()}
	{forIn {a: 1, b: 2} => el}
		{return el /}
	Hello world

Examples

Простой перебор

- namespace demo
- template index()
	- var obj = {a: 1, b: 2}
	- forIn obj => el, key
		{el} {key}

{namespace demo}
{template index()}
	{var obj = {a: 1, b: 2} /}
	{forIn obj => el, key}
		{el} {key}
	{/}
{/template}

Перебор с заданием with в списке входных параметров

- namespace demo
- template index()
	- var obj = {a: {name: 'Koba'}, b: {name: 'Over'}}
	- forIn obj => @el
		{@name}

{namespace demo}
{template index()}
	{var obj = {a: {name: 'Koba'}, b: {name: 'Over'}} /}
	{forEach obj => @el}
		{@name}
	{/}
{/template}

Сброс итераций

- namespace demo
- template index()
	- forEach {a: 1, b: 2, c: 3} => el
		{el}
		- break

{namespace demo}
{template index()}
	{forEach {a: 1, b: 2, c: 3} => el}
		{el}
		{break}
	{/}
{/template}

• Directives
• Working with exceptions

try

Директива try является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript.

Synopsis

Description

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

Самая простая форма выглядит так:

- try
	? 1 2

{try}
	{1 2}
{/try}

The directive can be used anywhere. Вместе с основной директивой можно использовать дополнительные:

1. catch - аналог catch в JS (функциональная директива);
2. finally - аналог finally в JS.

Examples

- namespace demo
- template index(value)
	< .result
		- try
			? value = JSON.parse(value)

		- catch err
			? console.error(err)

		- finally
			Hello world!

{namespace demo}
{template index(value)}
	{< .result}
		{try}
			{? value = JSON.parse(value)}

		{catch err}
			{? console.error(err)}

		{finally}
			Hello world!
		{/}
	{/}
{/template}

• Directives
• Working with exceptions

throw

Директива throw является эквивалентом одноименного оператора в различных языках программирования и по своей семантике близка к реализации в JavaScript.

Synopsis

Description

Директива генерирует заданное исключение и начинается с ключевого слова throw, которое должно сопровождаться выражением. Самая простая форма выглядит так:

- throw new Error('Ошибка')

{throw new Error('Ошибка')}

The directive can be used anywhere.

Examples

- namespace demo
- template index(value)
	< .result
		- if value > 1
			- throw new Error('Invalid value')

{namespace demo}
{template index(value)}
	{< .result}
		{if value > 1}
			{throw new Error('Invalid value')}
		{/}
	{/}
{/template}

• Directives
• Working with whitespace

ignoreWhitespaces

The directive declares that all subsequent whitespace characters until first non-whitespace should be ignored.

Synopsis

Examples

- namespace demo
- template index(value, area)
	Hello{&}             World Bar

{namespace demo}
{template index(value, area)}
	Hello{&}             World Bar
{/template}

Output:

HelloWorld Bar

• Directives
• Working with whitespace

ignoreAllWhitespaces

The directive declares that all nested whitespace characters should be ignored.

Synopsis

Examples

- namespace demo
- template index(value, area)
	&+
		Hello             World Bar

{namespace demo}
{template index(value, area)}
	{&+}
		Hello             World Bar
	{/}
{/template}

Output:

HelloWorldBar

• Directives
• Working with whitespace

unIgnoreAllWhitespaces

The directive declares that all nested whitespace characters should not be ignored (usually used in conjunction with ignoreAllWhitespaces).

Synopsis

Examples

- namespace demo
- template index(value, area)
	&+
		Hello             World Bar
		&-
			Hello             World Bar

{namespace demo}
{template index(value, area)}
	{&+}
		Hello             World Bar
		{&-}
			Hello             World Bar
		{/}
	{/}
{/template}

Output:

HelloWorldBarHello World Bar

• Directives
• Working with whitespace

sp

The directive puts in a template the space character (only relevant for Jade-Like).

Synopsis

Examples

- namespace demo
- template index(value, area)
	< .foo
	\
	< .bar

Output:

<div class="foo"></div> <div class="bar"></div>

• Directives
• Working with HTML/XML

doctype

Директива вставляет в шаблон код декларации заданного doctype, а также определяет правила форматирования для тегов и атрибутов.

Synopsis

Description

Директива предназначена для указания типа текущего документа - DTD (document type definition, описание типа документа). Это необходимо, чтобы клиент/парсер понимал, как следует интерпретировать текущую страницу, а также указывает Snakeskin какие правила он должен применять при генерации кода тегов и атрибутов.

Директива может использоваться только внутри шаблонов or внешних блоков.

Таблица обозначений

html

<!DOCTYPE html>

xml

<?xml version="1.0" encoding="utf-8" ?>

transitional

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

strict

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

frameset

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">

1.1

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

basic

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">

mobile

<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">

mathml 1.0

<!DOCTYPE math SYSTEM "http://www.w3.org/Math/DTD/mathml1/mathml.dtd">

mathml 2.0

<!DOCTYPE math PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd">

svg 1.0

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">

svg 1.1 full

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">

svg 1.1 basic

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd">

svg 1.1 tiny

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Tiny//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-tiny.dtd">

Examples

Использование значения по умолчанию (html5)

- namespace demo
- template index(value)
	- doctype

{namespace demo}
{template index(value)}
	{doctype}
{/template}

Явное указание типа

- namespace demo
- template index(value)
	- doctype xml

{namespace demo}
{template index(value)}
	{doctype xml}
{/template}

• Directives
• Working with HTML/XML

attr

Директива вставляет в шаблон код декларации HTML/XML атрибута по заданным параметрам.

Synopsis

Description

Директива attr обычно используется для задания атрибутов вместе с директивой tag. Общая форма директивы следующая:

attr название атрибута = значение атрибута

For example:

- attr foo = bar

{attr foo = bar}

Обратите внимание, что крайние пробелы у символа = важны, иначе он трактуется как простой текст. Директива может использоваться только внутри шаблонов or внешних блоков.

Множественное задание атрибутов

Если необходимо задать несколько атрибутов, то нужно использовать специальный разделитель |, например:

- attr foo = bar | baz = bla

{attr foo = bar | baz = bla}

Обратите внимание, что крайние пробелы у символа | важны, иначе он трактуется как простой текст.

- attr foo = bar|baz=bla

{attr foo = bar|baz=bla}

Атрибуты с пустым значением

Если нужно задать атрибут с пустым значением, то достаточно просто ничего не писать после знака присвоения, например:

- attr alt =

{attr alt =}

Отрендерится как:

alt=""

Инлайновые атрибуты

Для задания “инлайновых” HTML атрибутов, например, <input disabled> нужно просто опустить знак присвоения.

- attr disabled

{attr disabled}

Задание data- атрибутов

Для декларации data- атрибутов поддерживается короткий синтаксис:

- attr -title = bla | -desc-field = bar

{attr -title = bla | -desc-field = bar}

Однако можно писать и полную форму:

- attr data-title = bla

{attr data-title = bla}

Группы атрибутов

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

attr опциональный префикс(( название атрибута = значение атрибута ))

For example:

- attr ng-(( repeat = el in data | bind = bla ))

{attr ng-(( repeat = el in data | bind = bla ))}

Отрендерится как:

ng-repeat="el in data" ng-bind="bla"

Обратите внимание, что крайние пробелы у символов (( и )) важны, иначе они трактуется как простой текст. Также следует отметить, что при комбинировании групп атрибутов с другими группами не нужно ставить специальный разделитель, например:

- attr ng-(( repeat = foo of bla )) (( baz = bar )) hello = world | foo = bar

{attr ng-(( repeat = foo of bla )) (( baz = bar )) hello = world | foo = bar}

Интерполяция

Для передачи значений Snakeskin внутрь директивы используется стандартный механизм интерполяции, например:

- var name = 'foo'
- attr ${name} = ${1 + 2}

{var name = 'foo' /}
{attr ${name} = ${1 + 2}}

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

- var name = 'foo'
- attr ${name}-bar = ${1 + 2} hello

{var name = 'foo' /}
{attr ${name}-bar = ${1 + 2} hello}

Интерполяция объекта

Snakeskin позволяет используя механизм интерполяции задать атрибуты с помощью объекта, где ключом является название атрибута or группы.

- var attrs = {foo: 'bar', 'ng-': {repeat: 'el in data'}}
- attr ${attrs}

{var attrs = {foo: 'bar', 'ng-': {repeat: 'el in data'}} /}
{attr ${attrs}}

Чтобы сделать атрибут “инлайновым” нужно использовать специальную константу TRUE:

- var attrs = {disabled: TRUE}
- attr ${attrs}

{var attrs = {disabled: TRUE} /}
{attr ${attrs}}

Отрендерится как:

disabled

А чтобы исключить, то нужно использовать константу FALSE:

- var attrs = {disabled: FALSE}
- attr ${attrs}

{var attrs = {disabled: FALSE} /}
{attr ${attrs}}

Значение ключа автоматически переводится из camelCase в dash-style, например:

- attr ${{fooBarBla: 'baz'}}

{attr ${{fooBarBla: 'baz'}}}

Отрендерится как:

foo-bar-bla="baz"

Char escaping

Для экранирования спецсимволов директивы используется символ \, например:

- attr foo = bar \= bla

{attr foo = bar \= bla}

• Directives
• Working with HTML/XML

tag

Директива вставляет в шаблон код декларации HTML/XML тега по заданным параметрам.

Synopsis

Description

Директива tag является универсальным инструментом для генерации XML подобных структур. Общая форма директивы следующая:

tag название директивы

For example:

- tag span
< span

{tag span}{/tag}
{< span}{/}

При использовании tag в классическом синтаксисе существует короткая форма закрытия директивы, например:

/// Обычное закрытие
{tag input type = text}{/}

/// Короткая форма закрытия
{tag input type = text /}

Директива может использоваться только внутри шаблонов or внешних блоков.

Создание элемента с заданием классов и ИД

Для удобного задания классов и ИД-а в tag используется синтаксис селекторов CSS, например:

< span#baz.foo.bar
/// Если не указать имя создаваемого тега,
/// то будет использоваться div
< .bla

{< span#baz.foo.bar}{/}
/// Если не указать имя создаваемого тега,
/// то будет использоваться div
{< .bla}{/}

Задание произвольных атрибутов

Директива tag поддерживает задание атрибутов с помощью attr, например:

< input value = foo | disabled

{< input value = foo | disabled /}

Отрендерится как:

<input value="foo" disabled>

Ссылки на родительский класс

В Snakeskin существует специальный механизм получения значения родительского класса в дочернем теге, который называется “липкая ссылка”. Принцип работы следующий: если при декларации тега задать имя класса, которое начинается с символа &, то он будет заменён на ближайший родительский класс, который декларировался без этого символа, например:

< .foo
	< .&__bar
	< .&__bla

{< .foo}
	{< .&__bar}{/}
	{< .&__bla}{/}
{/}

Отрендерится как:

<div class="foo">
	<div class="foo__bar"></div>
	<div class="foo__bla"></div>
</div>

Ссылка на родительский класс в произвольном атрибуте

Альтернативным способом получения липкой ссылки является вызов внутренней переменной шаблона $class, например:

< .foo value = ${$class}

{< .foo value = ${$class}}{/}

Отрендерится как:

<div class="foo" value="foo"></div>

Локальные ссылки

Если поместить декларацию класса в специальную конструкцию [...], то классы заданные внутри такого блока не будут запоминаться как липкая ссылка, а также плейсхолдер & будет ссылаться на ближайший по иерархии вложенности класс слева.

< .b-button[.g-helper]
	< button.&__elem[.&_focused_true]

{< .b-button[.g-helper]}
	{< button.&__elem[.&_focused_true]}{/}
{/}

Отрендерится как:

<div class="b-button g-helper">
	<button class="b-button__elem b-button__elem_focused_true"></button>
</div>

Тег-плейсходер

Специальный тег ? существует только на этапе трансляции и не включается в конечный код, например:

< ?.b-button
	< button.&__elem

{< ?.b-button}
	{< button.&__elem}{/}
{/}

Отрендерится как:

<button class="b-button__elem"></button>

Интерполяция

Для передачи значений Snakeskin внутрь директивы используется стандартный механизм интерполяции, например:

- var name = 'span'
< ${name}

{var name = 'foo' /}
{< ${name}}{/}

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

- var name = 'foo'
< .${name}-bla.bar

{var name = 'foo' /}
{< .${name}-bla.bar}{/}

Для интерполяции в атрибутах используется механизмы attr.

Интерполяция и тег-плейсхолдер

< ${'?'}.b-button
	< button.&__elem

{< ${'?'}.b-button}
	{< button.&__elem}{/}
{/}

Отрендерится как:

<button class="b-button__elem"></button>

“Инлайновые” теги

В HTML ряд тегов не требуют закрывающей части (</tag>), например, input or meta, причём если в XHTML такие теги закрываются явно, например:

<input type="text" />

То в HTML это можно опустить:

<input type="text">

Snakeskin знает про такие теги, а способ их закрытия зависит от выбранного doctype. Правила декларации заданы в объекте Snakeskin.inlineTags, структура следующая:

Snakeskin.inlineTags = {
	// Название используемого doctype
	'html': {
		// Тег br ставится инлайновым
		'br': true,

		// Тег input ставится инлайновым,
		// причём если вставить содержимое в такой тег, например,
		//
		// < input
		//   Hello world!
		//
		// то оно поставится как значение атрибута value
		'input': 'value'
	}
}

Если для заданного doctype нет своей схемы тегов, то используется html.

Локальная декларация инлайновых тегов

С помощью модификатора !inline любой тег можно сделать принудительно инлайновым, например:

< textarea!inline

{< textarea!inline /}

Отрендерится как:

<textarea>

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

- var val = {textarea: true}
< div!inline=val
	< textarea

{var val = {textarea: true} /}
{< div!inline=val}
	{< textarea /}
{/}

Отрендерится как:

<div><textarea></div>

Полиморфизм тегов

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

- namespace demo
- template index(value, area)
	< ${area ? 'textarea' : 'input'}.input
		{value}

{namespace demo}
{template index(value, area)}
	{< ${area ? 'textarea' : 'input'}.input}
		{value}
	{/}
{/template}

Snakeskin поймёт такую конструкцию и в случае textarea создаст код вида:

<textarea class="input">значение</textarea>

А в случае input:

<input class="input" value="значение">

Char escaping

Для экранирования спецсимволов директивы используется символ \, например:

< .bla foo = bar \= bla

{< .bla foo = bar \= bla}{/}

• Directives
• Working with HTML/XML

script

Директива вставляет в шаблон код декларации тега <script> с заданными параметрами.

Synopsis

Description

Директива предназначена для более удобного задания тегов <script> и может использоваться только внутри шаблонов или внешних блоков.

При использовании script в классическом синтаксисе существует короткая форма закрытия директивы, например:

/// Обычное закрытие
{script js src = foo.js}{/}

/// Короткая форма закрытия
{script js src = foo.js /}

Таблица обозначений

js

text/javascript

dart

application/dart

coffee

application/coffeescript

ts

application/typescript

cljs

application/clojurescript

ls

application/livescript

json

application/json

html

text/html

ss

text/x-snakeskin-template

Examples

Использование значения по умолчанию (js)

- namespace demo
- template index()
	# script
		var a = {};

{namespace demo}
{template index()}
	#{script}
		var a = {};
	#{/}
{/template}

Явное указание типа

- namespace demo
- template index()
	# script ts
		var a = {};

{namespace demo}
{template index()}
	#{script ts}
		var a = {};
	#{/}
{/template}

Указание собственного типа

- namespace demo
- template index()
	# script application/myscript
		var a = {};

{namespace demo}
{template index()}
	#{script application/myscript}
		var a = {};
	#{/}
{/template}

Задание произвольных атрибутов

(используется синтаксис attr)

- namespace demo
- template index()
	# script js class = foo
		var a = {};