НАЗНАЧЕНИЕ И ПРАВИЛА ИСПОЛЬЗОВАНИЯ ШАБЛОНОВ
===========================================

Определения
-----------
Шаблон — HTML-код, содержащий переменные и функции шаблона.
Назначение шаблона заключается в создании каркаса кода.
Конечный HTML-код формируется в результате парсинга шаблона.

Парсинг — процесс обработки шаблона программой парсера,
при котором происходит замена переменных и функций шаблона
на свои значения. Результатом парсинга является конечный
HTML-код, выводимый в окно браузера.

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

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


Синтаксис
---------
Шаблонные переменные определяются своим именем, которое с двух сторон
ограничивается знаком процента (%).
Шаблонные функции отличаются от шаблонных переменных наличием круглых
скобок, в которых указывается список аргументов, перечисленных через
запятую. Количество аргументов определяется назначением функции.
Имена шаблонных переменных и функций могут состоять только из латинских
букв, цифр и символа подчеркивания, длина имени может быть равна
одному символу и более.
Аргументами функций могут быть следующие данные:
- десятичные числа;
- строки;
- массивы;
- шаблонные переменные;
- шаблонные функции.
Все функции встроены в парсер и определить свою функцию нельзя.

Пример шаблонной переменой: %NAME%
Пример шаблонной функции: %input("name", "", 10, %len%)%

Типы
----
Десятичные числа - это последовательность цифр от 0 до 9.
Пример: 12345

Строка - это набор символов, ограниченный слева и справа символами
кавычек (") или апострофа (').
Пример строки: "это строка"

Если внутри строки требуется применить символ кавычек, то его надо
экранировать - перед символом поставить обратный слэш (\). Чтобы
вывести сам обратный слеш его также надо экранировать, т.е. два
обратных слэша (\\) выводятся как один.
Пример: "это \"слово\" в кавычках".

Внутри строк можно использовать шаблонные переменные и функции,
записываться они должны с символами процента по краям, при парсинге
они будут заменяться своим значением.
Пример: "Мое имя: %NAME%"

Если требуется, чтобы парсер не делал замен шаблонных переменных и
функций, символ процента надо дублировать, иными словами, два
символа процента в строке (%%) будут выводиться как один.
Пример: "в этой строке переменная %%NAME%% не будет заменена"

Массивы - набор данных, объединенных в одну переменную, элементы
массива записываются в квадратных скобках через запятую. Типы данных
элементов массива могут быть те же, что и аргументы у функций.
Пример: [1, "один", 2, "два"]
Примечание: массивы можно применять только в качестве аргументов
функций, присваивать переменным массивы нельзя.


Использование
-------------
Переменные и функции шаблона предназначены для подстановки значений
в HTML-код. Это означает, что переменные и функции шаблона после
парсинга будут заменены своим значением - последовательностью символов
(строкой), либо пустой строкой (никаких символов не содержится).

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

Самый простой способ использования переменной шаблона - просто ее написать.
Пример:

%NAME%

Если у нас была определена переменная NAME, то после парсинга она будет
заменена на свое значение.

В шаблоне можно определить свои переменные. Для этого есть два способа
определения переменных. Первый, аналогичен оператору присваивания в языках
программирования. Значением для присваивания может быть: десятичное число,
строка, другая переменная или функция.
Присваивание десятичного числа:
%NUMBER = 10%

Присваивание строки:
%NAME = "Вася Пупкин"%

Присваивание другой переменой:
%MY_VAR = %NAME%%

Присваивание функции
%INPUT = %input("name", "", 10, %len%)%%

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

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

%TEXT<<Здесь находится многострочный текст
Все встреченные шаблонные переменные и функции
обрабатываться парсером не будут.
END%

Здесь слово END (можно выбрать любое слово) является строкой-ограничителем
и определяется сразу после имени переменной (TEXT) и тройного символа
меньше (<<<). С новой строки начинается многострочный текст. Для
обозначения конца текста это же слово-ограничитель должно быть записано в
начале новой строки.

Конструкции присваивания ничего не возвращают, поэтому в конечном HTML-коде
на их месте будут пустые строки.

Есть две конструкции, выполняющие дополнительную обработку строк.
Первая имеет такую запись:

%{"строка"}%

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

%{"NAME"}%

Эта конструкция полностью эквивалента записи %NAME% и не имеет практического
смысла. Другой пример показывает гибкость этой записи:

%STATE_0 = "выключено"%
%STATE_1 = "включено"%
%{"STATE_%STATE%"}%

Теперь от значения переменной STATE зависит какой будет результат парсинга:

STATE | результат
------+----------
0 | выключено
1 | включено


Вторая конструкция предназначена для парсинга строки и записывается в
таком виде:

%(%TEXT%)%

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


Условные операторы
------------------

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

%?
шаблон_1
%:%
шаблон_2
?%

В этой конструкции выбор между шаблонами шаблон_1 и шаблон_2 зависит от
значения всех шаблонных переменных и функций из первого шаблона (шаблон_1).
Если все переменные и функции в первом шаблоне возвращают не пустые строки,
то обработан будет этот первый шаблон, второй будет проигнорирован. Если
хотя бы одна переменная или функция из первого шаблона вернет пустую
строку - обработан будет второй шаблон.
Есть упрощенный вариант записи этой конструкции, когда второго шаблона нет:

%?
шаблон
?%

Шаблон будет обработан только при условии, что все переменные и функции в
шаблоне вернули не пустую строку.

* Второй вариант записи условия.
В этом варианте используется шаблонная функция, которая определена в самом
парсере.
Есть две формы вызова этой функции:
1. %IF(%COND%, "строка_1", "строка_2")%
2. %IF("строка_1", "строка_2")%

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

Во второй форме функции %IF()% передаются два аргумента - оба строки, если
первая строка не пустая, функция вернет ее, иначе, функция вернет вторую
строку.

Для операций сравнения в парсере определены четыре функции, которые можно
использовать в качестве условия в функции %IF()%.
1. %TRUE()%
функция может принимать один и более аргументов, возвращает истинно
только если все аргументы функции имеют истинное значение.
2. %EQ()%
функция принимает два аргумента и сравнивает строки на равенство,
возвращает истинно, если обе строки равны посимвольно.
3. %LT()%
функция принимает два аргумента и сравнивает два числа, возвращает
истинно, если первое число меньше второго.
4. %GT()%
функция принимает два аргумента и сравнивает два числа, возвращает
истинно, если первое число больше второго.

Важное замечание: значения "истинно" и "ложно" в шаблонах имеет немного
иной смысл, чем в языках программирования. Так как, все шаблонные
функции возвращают строку, то результат работы функций сравнения не
должен никак отображаться в конечном HTML-коде. Для это были выбраны
следующие значения, которые возвращают функции сравнения:
истинно - одиночный символ пробела, в HTML-коде его не будет видно
ложно - пустая строка

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


Список всех шаблонных функций, встроенных в парсер
--------------------------------------------------
Функции для условного выполнения кода:
%TRUE()%
%IF()%
%EQ()%
%LT()%
%GT()%

Функции общего назначения:
%SESS()%
%CHAT()%
%CFG()%
%CFGJS()%
%PEOPLE()%
%CSS()%
%DATE()%
%TIME()%
%LONG_DAYS()%
%LONG_TIME()%
%NAVIGATION()%

Функции для получения данных:
%GET()%
%POST()%
%COOKIE()%
%AGENT()%
%SERVER()%

Функции для строк:
%TRIM()%
%UP_CASE()%
%LOW_CASE()%

Функции для форм:
%input()%
%text()%
%checkbox()%
%radio()%
%radio2()%
%select()%
%select2()%
%button()%
%submit()%