mirror of https://github.com/fenom-template/fenom.git synced 2023-08-10 21:13:07 +03:00

bzick 295ad63cf1 Done ru docs [beta]

2014-08-08 15:58:50 +04:00

24 KiB

Raw Blame History

Синтаксис

По синтаксису шаблона Fenom похож на Smarty, но обладает рядом улучшений. Все теги шаблонизатора заключаются в фигрные скобки: { — открытие тега и } — закрытие тега.

Замечание Хоть Fenom и позаимствовал синтаксис Smarty, но он не заимствовал теги Smarty как есть. Однако некоторые теги очень похожи. Но не все так плохо, Fenom имеет набор дополнений которые могут сделать Fenom более похожим на Smarty что бы переход был мягче.

Переменные

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

Использование переменных

Следующий пример использует простые переменные $user_id и $user_name для формирования приветственного сообщения.

<div class="user">Hello, <a href="/users/{$user_id}">{$user_name}</a>.</div>

Пример выведет следующий HTML код:

<div class="user">Hello, <a href="/users/17">Bzick</a>.</div>

Переменные могут быть массивом. В этом случае обращение по ключу происходит через опертор . или, как в PHP, через операторы [ и ]

<div class="user">Hello, <a href="/users/{$user.id}">{$user.name}</a>.</div>

{$user.id} and {$user['id']} are same:

<div class="user">Hello, <a href="/users/{$user['id']}">{$user['name']}</a>.</div>

В случае объекта, доступ к его свойствам осущесвляется так как и в PHP — через оператор ->:

<div class="user">Hello, <a href="/users/{$user->id}">{$user->name}</a>.</div>

Методы, как и свойства можно вызвать через оператор ->, передав в метод любые рагументы:

<div class="user">Hello, <a href="/users/{$user->getId()}">{$user->getName()}</a>.</div>

Note Будте осторожны, Fenom не проверяет наличие метода в классе перед вызовом. Что бы избежать фатальной ошибки определите метод __call у класса объекта. Вызов методов в шаблоне можно вообще выключить в настройках.

Ниже приведены комбинированые примеры работы с переменными:

{$foo.bar.baz}
{$foo.$bar.$baz}
{$foo[5].baz}
{$foo[5].$baz}
{$foo.bar.baz[4]}
{$foo[ $bar.baz ]}
{$foo[5]}
{$foo.5}
{$foo.bar}
{$foo.'bar'}
{$foo."bar"}
{$foo['bar']}
{$foo["bar"]}
{$foo.$bar}
{$foo[$bar]}
{$foo->bar}
{$foo->bar.buz}
{$foo->bar.buz[ $bar->getId("user") ]}
{$foo->bar(5)->buz(5.5)}

Системная переменная

Безименная системная переменная начинается с $. и предоставляет доступ к глобальным системным переменным и системной информации:

$.get — $_GET.
$.post — $_POST.
$.cookie — $_COOKIE.
$.session — $_SESSION.
$.globals — $GLOBALS.
$.request — $_REQUEST.
$.files — $_FILES.
$.server — $_SERVER.
$.env — $_ENV.
$.tpl.name возвращает текущее название шаблона.
$.tpl.schema возвращает код провайдера шаблона.
$.version возвращает версию Fenom.
$.const обращение к PHP константе: $.const.PHP_EOL .

{if $.get.debug? && $.const.DEBUG}
   ...
{/if}

Скалярные значения

Строки

Строка может быть определена двумя различными способами: двойные кавычки ("string") и одинарные кавычки ('string').

Двойные кавычки

Если строка заключена в двойные кавычки ", Fenom распознает большее количество управляющих последовательностей для специальных символов: \n, \r, \t, \v, \e, \f, \\, \$, \", \[0-7]{1,3}, \x[0-9A-Fa-f]{1,2}. Но самым важным свойством строк в двойных кавычках является обработка переменных. Существует два типа синтаксиса: простой и сложный. Простой синтаксис более легок и удобен. Он дает возможность обработки переменной, значения массива или свойства объекта с минимумом усилий. Сложный синтаксис может быть определен по фигурным скобкам, окружающим выражение.

Простой синтаксис

Если Fenom встречает знак доллара ($), он захватывает так много символов, сколько возможно, чтобы сформировать правильное имя переменной. Если вы хотите точно определить конец имени, заключайте имя переменной в фигурные скобки.

{"Hi, $username!"}   выведет "Hi, Username!"

Для чего-либо более сложного, используйте сложный синтаксис.

Сложный синтаксис

Он называется сложным не потому, что труден в понимании, а потому что позволяет использовать сложные выражения. Любая скалярная переменная, элемент массива или свойство объекта, отображаемое в строку, может быть представлена в строке этим синтаксисом. Просто запишите выражение так же, как и вне строки, а затем заключите его в { и }. Поскольку { не может быть экранирован, этот синтаксис будет распознаваться только когда $ следует непосредственно за {. Используйте {\$, чтобы напечатать {$. Несколько поясняющих примеров:

{"Hi, {$user.name}!"}        выводит: Hi, Username!
{"Hi, {$user->name}!"}       выводит: Hi, Username!
{"Hi, {$user->getName()}!"}  выводит: Hi, Username!
{"Hi, {\$user->name}!"}      выводит: Hi, {\$user->name}!

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

{"Hi, {$user.name|up}!"}                  выводит: Hi, USERNAME!
{"Hi, {$user.name|up ~ " (admin)"}!"}     выводит: Hi, USERNAME (admin)!

Одинарные кавычки

Простейший способ определить строку - это заключить ее в одинарные кавычки (символ ').

Чтобы использовать одинарную кавычку внутри строки, проэкранируйте ее обратной косой чертой \. Если необходимо написать саму обратную косую черту, продублируйте ее \\. Все остальные случаи применения обратной косой черты будут интерпретированы как обычные символы: это означает, что если вы попытаетесь использовать другие управляющие последовательности, такие как \r или \n, они будут выведены как есть вместо какого-либо особого поведения.

{'Hi, $foo'}            выводит 'Hi, $foo'
{'Hi, {$foo}'}          выводит 'Hi, {$foo}'
{'Hi, {$user.name}'}    выводит 'Hi, {$user.name}'
{'Hi, {$user.name|up}'} выводит "Hi, {$user.name|up}"

Целые числа

Целые числа могут быть указаны в десятичной (основание 10), шестнадцатеричной (основание 16), восьмеричной (основание 8) или двоичной (основание 2) системе счисления, с необязательным предшествующим знаком (- или +).

Для записи в восьмеричной системе счисления, необходимо поставить пред числом 0 (ноль). Для записи в шестнадцатеричной системе счисления, необходимо поставить перед числом 0x. Для записи в двоичной системе счисления, необходимо поставить перед числом 0b

{var $a = 1234} // десятичное число
{var $a = -123} // отрицательное число
{var $a = 0123} // восьмеричное число (эквивалентно 83 в десятичной системе)
{var $a = 0x1A} // шестнадцатеричное число (эквивалентно 26 в десятичной системе)
{var $a = 0b11111111} // двоичное число (эквивалентно 255 в десятичной системе)

Замечение Двоичная запись числа (0b1011011) не доступна на старых версиях PHP — 5.3 или ниже. Попытка исользовать на старых версия PHP приведет к исключению при компиляциях.

Замечение Размер целого числа зависит от платформы, хотя, как правило, максимальное значение примерно равно 2 миллиардам (это 32-битное знаковое). 64-битные платформы обычно имеют максимальное значение около 9223372036854775807.

Предупреждение Если в восьмеричном целом числе будет обнаружена неверная цифра (например, 8 или 9), оставшаяся часть числа будет проигнорирована.

Числа с плавающей точкой

Числа с плавающей точкой (также известные как "float", "double", или "real") могут быть определены следующими синтаксисами:

{var $a = 1.234}
{var $b = 1.2e3}
{var $c = 7E-10}

Булев

Это простейший тип. Булевое выражает истинность значения. Он может быть либо TRUE либо FALSE. Для указания булевого значения, используйте ключевое слово TRUE или FALSE. Оба регистро-независимы.

{set $a = true}

NULL

Специальное значение NULL представляет собой переменную без значения. NULL - это единственно возможное значение типа null.

Обычно возникают путаницы между NULL и FALSE, так как по роли они похожи, но разлицаются по принципу: NULL - это отсутствие присутствия, а FALSE - присутвие отсутствия.

Операции

Как и любой другой язык программирования/шаблонизации Fenom поддерживает множество различных операторов:

Арифметические операторы — +, -, *, /, %
Логические операторы — ||, &&, !$var, and, or, xor
Операторы сравнения — >, >=, <, <=, ==, !=, !==, <>
Битовые операторы — |, &, ^, ~$var, >>, <<
Операторы присвоения — =, +=, -=, *=, /=, %=, &=, |=, ^=, >>=, <<=
Строковый оператор — $str1 ~ $str2
Тернарные операторы — $a ? $b : $c, $a ! $b : $c, $a ?: $c, $a !: $c
Проверяющие операторы — $var?, $var!
Оператор тестирование — is, is not
Оператор содержания — in, not in

Подробнее об операторах.

Массивы

Массив (тип array) может быть создан конструкцией []. В качестве параметров она принимает любое количество разделенных запятыми пар key => value (ключ => значение).

[
    key  => value,
    key2 => value2,
    key3 => value3,
    ...
]

Запятая после последнего элемента массива необязательна и может быть опущена. Обычно это делается для однострочных массивов, т.е. [1, 2] предпочтительней [1, 2, ]. Для многострочных массивов с другой стороны обычно используется завершающая запятая, так как позволяет легче добавлять новые элементы в конец массива.

{set $array = [
    "foo" => "bar",
    "bar" => "foo",
]}

key может быть либо целым числом, либо строкой. value может быть любого типа.

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

Строки, содержащие целое число будут преобразованы к числу. Например, ключ со значением "8" будет в действительности сохранен со значением 8. С другой стороны, значение "08" не будет преобразовано, так как оно не является корректным десятичным целым.
Числа с плавающей точкой также будут преобразованы к числу, т.е. дробная часть будет отброшена. Например, ключ со значением 8.7 будет в действительности сохранен со значением 8.
Булев также преобразовываются к целому числу. Например, ключ со значением true будет сохранен со значением 1 и ключ со значением false будет сохранен со значением 0.
NULL будет преобразован к пустой строке. Например, ключ со значением null будет в действительности сохранен со значением "".
Массивы (тип array) и объекты (тип object) не могут использоваться в качестве ключей. При подобном использовании будет генерироваться предупреждение: Недопустимый тип смещения (Illegal offset type).

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

Параметр key является необязательным. Если он не указан, Fenom будет использовать предыдущее наибольшее значение целочисленного ключа, увеличенное на 1.

Существующий массив может быть изменен явной установкой значений в нем. Это выполняется присвоением значений массиву с указанием в скобках ключа или после точки. Кроме того, используя скобки, вы можете опустить ключ.

{set $arr.key = value}
{set $arr[] = value} {* будет взят максимальный целочисленый ключ, увеличенный на 1 *}

Если массив $arr еще не существует, он будет создан. Таким образом, это еще один способ определить массив. Однако такой способ применять не рекомендуется, так как если переменная $arr уже содержит некоторое значение (например, строку), то это значение останется на месте и [] может на самом деле означать доступ к символу в строке. Лучше инициализировать переменную путем явного присваивания значения.

Модификаторы

Модификаторы переменных могут быть прмменены к переменным, пользовательским функциям или строкам. Для их применения надо после модифицируемого значения указать символ | (вертикальная черта) и название модификатора. Так же модификаторы могут принимать параметры, которые влияют на их поведение. Эти параметры следуют за названием модификатора и разделяются : (двоеточием). Кроме того, по умолчанию все функции PHP могут быть использованы в качестве модификаторов (что можно отключить в настройках) и модификаторы можно комбинировать.

{var $foo="User"}
{$foo|upper}            выведет "USER"
{$foo|lower}            выведет "user"
{"{$foo|lower}"}        выведет "user"
{"User"|lower}}         выведет "user"
{$looong_text|truncate:80:"..."}  обрежет текст до 80 символов и добавит символы "..."
{$looong_text|lower|truncate:$settings.count:$settings.etc}
{set $foo="Ivan"|upper}    значение переменной $foo будет "USER"

заполнитель (placeholder) — вывод переменной в шаблоне, например {$name}
тег — конструкция выполняющаяя некоторые действия, выглядит как именованный заполнитель (placeholder), например {include $name}

Теги так же можно разделить на две группы:

Функии. Тег функции вызывает пользовательскую во время выполнения шаблона, результат функции будет выведен вместо тега. Пользовательские функции являются дополнительными и могут быть индивидуальными. Они могут быть изменены по вашему желанию, также вы можете создать новые.
Компиляторы. В отличии от функций компиляторы вызываются во время компиляции шаблона и возвращают PHP код, который описывает некоторое действие. Компиляторы и формируют основные конструкции типа if, foreach и т.д.

Игнорирование кода

В шаблонизаторе Fenom используются фигурные скобки для отделения HTML от кода Fenom. Если требуется вывести текст, содержащий фигурные скобки, то есть следующие варианты это сделать:

Использование блочного тега {ignore}{/ignore}. Текст внутри этого тега текст не компилируется шаблонизатором и выводится как есть.
Если после открывающей фигурной скобки есть пробельный символ (пробел или \t) или перенос строки (\r или \n), то она не воспринимается как разделитель кода Fenom и код после неё выводится как есть.
Установить опцию :ignore у блочного тега. Все Fenom теги внутри блока будут проигнорированны

Example:

{ignore}
<style>
	h1 {font-size: 24px; color: #F00;}
</style>
{/ignore}
<script>
	(function (text) {
		var e = document.createElement('P');
		e.innerHTML = text;
		document.body.appendChild(e);
	})('test');
{if:ignore $cdn.yandex}
    var item = {cdn: "//yandex.st/"};
{/if}
</script>

Outputs

<style>
	h1 {font-size: 24px; color: #F00;}
</style>
<script>
	(function (text) {
		var e = document.createElement('P');
		e.innerHTML = text;
		document.body.appendChild(e);
	})('test');
	var item = {cdn: "//yandex.st/"};
</script>

Пробелы

Шаблонизатор допускает любое количество пробелов или переносов строк в своём коде

{include 'control.tpl'
    $options = $list
    $name    = $cp.name
    $type    = 'select'
    isolate  = true
    disable_static = true
}

{foreach [
    "one"   => 1,
    "two"   => 2,
    "three" => 3
] as $key   => $val}

    {$key}: {$val}

{/foreach}

Параметры тегов

имя	код	тип тега	описание
strip	s	блокоый	активирует удаление лишних пробелов на подобии модфикатора `strip`
ignore	i	блокоый	парсер будет игнорировать любой Fenom синтаксис на контент блокового тега
raw	a	любой	отключает экранирование
escape	e	любой	принудительно активирует экранирование

{script:ignore} ... {/script}
{foreach:ignore:strip ...} ... {/foreach}

24 KiB Raw Blame History Unescape Escape