-
Notifications
You must be signed in to change notification settings - Fork 9
Мануал
Quicky — интерпрератор шаблонов выполненный в виде PHP-скрипта, служащий для отделения логики предоставления от бизнес-логики, иными словами — для отделения той части программы которая непосредственно генерирует HTML-код от той, которая обрабатывает и генерирует данные, что позволяет легко изменять внешний вид программы посредством шаблонов, не внося изменений в значимый исходный код. Это позволяет разделить задачи программиста и верстальщика.
Системные требования: PHP 5.2.5 или выше. Скопируйте содержимое каталога в установочную папку, установите права записи для templates_c и templates_cache.
Quicky API используется программистами.
Для работы интерпретатора необходимо подключить файл Quicky.class.php и создать объект:
require_once 'Quicky.class.php';
$tpl = new Quicky;$tpl->template_dir = './templates/'; # Путь корневой папки с шаблонами
$tpl->compile_dir = './templates_c/'; # Путь папки с компиляциями шаблонов
$tpl->config_dir = './configs/'; # Путь корневой папки конфиг-файлов.
$tpl->cache_dir = './templates_cache/'; # Путь до папки кеша.
$tpl->plugins_dir = array(); # Пути до дополнительных папок с плагинами.
$tpl->_tpl_vars = array(); # Массив переменных доступных из шаблонов.
$tpl->_tpl_config = array(); # Массив конфиг-переменных доступных из шаблонов.
$tpl->_block_props = array(); # Массив хранящий свойства блоков.
$tpl->auto_filename_prefix = ''; # Префикс добавляющийся к именам файлов компиляций и кеша.
$tpl->compilers = array(); # Компиляторы.
$tpl->prefilters = array(); # Пре-фильтры.
$tpl->postfilters = array(); # Пост-фильтры.
$tpl->outputfilters = array(); # output-фильтры.
$tpl->compile_check = TRUE; # Проверка актуальности скомпилированного шаблона.
$tpl->force_compile = FALSE; # Перекомпилировать каждый раз.
$tpl->max_recursion_depth = 10; # Максимальная глубина рекурсии.
$tpl->compiler_prefs = array(
'inline_includes' => TRUE, # Вставка текста дочернего шаблона в родительный при include.
'allow_php_native' => TRUE # Разрешение {php}.
);
$tpl->error_reporting; # Уровень показа ошибок в шаблонах.
$tpl->version = '0.4'; # Версия Quicky.
$tpl->caching = 0; # Режим кеширования.
$tpl->cache_lifetime = 60; # Время жизни кеша в секундах.
$tpl->precompiled_vars = array(); # Компиляционные переменные.
$tpl->lang = ''; # Язык (аналог $auto_filename_prefix).
$tpl->use_sub_dirs = FALSE; # разбивка временных файлов на подкаталоги.
$tpl->cache_id = ''; # id кеша.
$tpl->compile_id = ''; # id компиляции.void Quicky (void) - инициализация объекта.
void register_prefilter (string filtername, mixed callback) - загрузка пре-фильтра.
void unregister_prefilter (string filtername) - удаление пре-фильтра.
void register_postfilter (string filtername, mixed callback) - загрузка пост-фильтра.
void unregister_postfilter (string filtername) - удаление пост-фильтра.
void register_outputfilter (string filtername, mixed callback) - загрузка output-фильтра.
void unregister_outputfilter (string filtername) - удаление output-фильтра.
bool template_exists (string filename) - проверить существование шаблона.
bool confing_load (string filename, string section = '') - загрузка конфигурационного файла.
bool load_filter (string type, string name) - загрузка фильтра.
bool load_compiler (string compiler) - загрузка компилятора.
void register_object (string name, object obj) - загрузка объекта.
void unregister_object (string name) - удаление объекта.
object get_register_object (string name) - получение объекта.
mixed get_templates_vars (string name) - получение переменной из области видимости шаблонов.
bool assign (string var, mixed value = NULL) - объявить переменную в области видимости шаблонов.
bool assign_byf (string var, mixed value = NULL) - объявить переменную в области видимости шаблонов используя ссылочную переменную.
void clear_assign (mixed var) - удалить одну или несколько переменных из области видимости шаблонов.
void reset(), clear_all_assign() - сбросить область видимости шаблонов.
bool clear_cache (string path, string cache_id = NULL, string compile_id = NULL, int exp = -1) - удаление файла кеша старше exp секунд.
void clear_all_cache (int exp = -1) - очистка всего кеша старше exp секунд.
bool clear_compiled_tpl (string path, string compile_id = NULL, int exp = -1) - удаление скомпилированного шаблона старше exp секунд.
void clear_all_compiled_tpl (int exp = -1) - удаление всех скомпилированных шаблонов старше exp секунд.
bool warning (string text) - вывод ошибки.
string _get_template_path (string path) - преобразование относительного пути шаблона в абсолютный.
string _get_auto_filename (string path, string cache_id = NULL, string compile_id = NULL) - генерация имени временного файла.
bool display (string path, string cache_id = NULL, string compile_id = NULL, string compiler = 'Quicky') - вывод шаблона.
string fetch (string path, string cache_id = NULL, string compile_id = NULL, string compiler = 'Quicky') - получение вывода шаблона.
bool is_cached (string path, string cache_id = NULL, string compile_id = NULL) - проверка существование кеша.
string _get_compile_path (string path, string compile_id) - получение пути до скомпилированного шаблона.
string _get_cache_path (string path, string cache_id = NULL, string compile_id = NULL) - получение пути до кеша.
bool _is_compiled (string path, string compile_id = NULL) - проверка скомпилированного шаблона.
string _compile (string path, string compile_id = NULL, string compiler) - компиляция файла шаблона.
string _compile_string (string body, string compiler = 'Quicky') - компиляция строки шаблона.
void detect_form (string name) - интепретировать HTML-форму с заданным именем как активный объект Quicky_form.
object getFormByName (string name) - получить объект формы (Quicky_form) по имени.
string context_fetch (string name) - получить контекст.
string context_set (array value) - установить переменные контекста.
string context_iterate (string name = '') - встроить контекст.Кеширование (сохранение результата выполнения шабл_test/caching.phpона) регулируется свойством $tpl->caching, 0 - отключено, 1 - включено для следующего шаблона, 2 - включено всегда. Результат сохраняется на промежуток времени определяемый в секундах в свойстве $tpl->cache_lifetime. Для проверки актуальности кеша следует использовать $tpl->is_cached и если кеша нет, assign'нить необходимые переменные.
Пример:
# листинг файла _test/caching.php
require_once '../Quicky.class.php';
$tpl = new Quicky;
$tpl->caching = 1;
$tpl->cache_lifetime = 60; // минута
if (!$tpl->is_cached('index.tpl'))
//проверяем существует ли актуальный кеш, если нет, то передаем данные
{
$tpl->assign('var','какое-нибудь значение, например, из БД');
}
$tpl->display('index.tpl');# листинг файла index.tpl
Cached: {date('r')}<br />
Current time: {dynamic} {date('r')} {/dynamic}<br />
Var: {$var}
При обновлении страницы примера (скрипт находится в _test/caching.php), Cached будет обновляться лишь раз в минуту, а Current time будет показывать текущее время независимо от кеша.
Команды шаблонизатора делятся на блоки и на строковые вызовы. Блок записывается как:
{BLOCK}...{/BLOCK}
В закрывающем теге название можно не указывать, то бишь допустима запись:
{BLOCK}...{/}
Строковый вызов как:
{...}
В открывающем теге части блоков подразумеваются строковые параметры, например:
{if 2+2 == 5}отец банкир{/}
Блоки могут быть вложенными.
{if 2+2 == 5}отец банкир, {if $var == 5}а мать домохозяйка{/if} {/}
Комментарии записываются так:
{* комментарий *}
Строковые выражения (совокупность операторов и операндов) одни и те же, и булевые операторы можно использовать например в объялении переменных, доступен расширяемый список встроенных функций PHP, а также функции-плагины (см. примеры).
Помимо стандартных возможностей, строковые выражения позволяют использовать модификаторы, они могут записываться либо после статического значения или переменной, либо после вызова функции, либо после закрывающей группирующей скобки.
Например, {$var|escape} - вывод переменной будет фильтрован модификатором escape, {('prepend'.$var)|escape} и т.д. Параметры модификаторам передаются так: {expression|modifier:exprparam1:exprparam2...}, например {$var|escape:'url'}.
В строковых выражениях доступны регулярные переменные, конфиг-переменные, константы, и магические константы.
Объявляются из API (методом assign) и внутри шаблонов, и доступны в строковых выражениях как $variable.
При обращении к элементам псевдо-массива $quicky будут возвращены специальные значения.
Например:
$quicky.now - вернет время в секундах от начала Эпохи UNIX.
$quicky.rdelim - правый огранитель quicky-тега
$quicky.ldelim - левый огранитель quicky-тега
$quicky.request/get/post/cookie - массивы $_REQUEST, $_GET, $_POST, $_COOKIE соответственно.
$quicky.requeststring/getstring/poststring/cookiestring - псевдо-индексы при обращении к которым не нужно заботиться о типе и существовании входящей переменной, при ее отсутствии и в случае передачи массива, будет возвращена пустая строка.
$quicky.session/server/env - $_SESSION, $_SERVER, $_ENV
$quicky.capture - массив содержащий значения блоков capture
$quicky.template - путь текущего шаблона
$quicky.version - версия Quicky
$quicky.const - псевдо-массив констант PHP
$quicky.foreach/section - двумерные массивы содержащие свойства этих именновых блоков
Хранятся в подгружаемых конфигурационных файлах, и доступны в строковых выражениях как #variable#.
Доступны в строковых выражениях как CONSTANT (верхний регистр рекоммендован стилем, но не обязателен), расширяемый список доступных констант хранится в свойстве объекта компилятора allowed_php_constants, также всегда доступны M_*
Это константы значение которых зависит от места в котором они вызываются. С помощью магических констант доступны свойства блоков (поддерживается вложенность), например:
{foreach name="one" key="key" value="value" from=array('Key1' => 'value1',
'Key2' => 'value2',
'Key3' => 'Value3',
'KeyN' => 'ValueN')}
{iteration is odd?'~':'-'}{$key} = {$value}<br />
{/foreach}
Также доступны следующие магические константы:
tplpath - путь до текущего шаблона.
tplpathdir - папка текущего шаблона.
rdelim - правый ограничитель тега Quicky.
ldelim - левый ограничитель тега Quicky.
- if/elseif/else. условный оператор.
{if condition_expression}1{elseif condition}2{else}3{/}
- section/sectionelse, foreach/foreachelse. цикличный оператор.
Параметры:
(string) name - название. обязательный параметр
(mixed) loop. обязательный параметр
(int) start - начальная итерация.
(int) max - ограничение количества итераций.
(int) step - шаг последовательности индекса, может быть отрицательным числом.
Свойства именового блока:
index - текущий индекс
index_prev - предыдущий индекс
index_next - следующий индекс
iteration, rownum - порядковый номер интерации начиная с 1
first - первый индекс
last - последний индекс
show - true если цикл произведет хотя бы одну итерацию, иначе false
total - количество итераций цикла
Примеры:
{section name='mysection' loop=($arr = array('one','two','three'))}
{$arr[mysection]}<br />
{/}
{section name='mysection' loop=$n}
{iteration}<br />{sectionelse}цикл не выполнил ни одной итерации
{/section}
foreach отличается от section тем что имеет лишь свойства interation, total, first, и last, и параметры name и loop, при этом name не обязательный параметр, при его отсутствии свойства недоступны (не стоит его указывать когда они не требуются, в целях производительности).
- for. цикличный оператор.
Параметры:
(int) start - начальное значение счетчика.
(int) step - шаг последовательности счетчика.
(int) loop - предел последовательности. обязательный параметр.
(var) value - переменная для счетчика. обязательный параметр.
Пример:
{for loop=10 step=2 value=$i}{$i}{/}
- while. цикличный оператор.
Цикл выполняется пока выражение является истинным
Пример:
{?$i = 0}
{while $i++ < 5}
{sqrt($i)}
{/}
- switch/case. оператор единственного выбора.
Пример:
{switch 10*10}
{case 50}пятьдесят
{case 100}сто
{/switch}
- literal. блок игнорируемый компилятором.
Пример:
{literal}
{ мы можем использовать Quicky-теги внутри этого блока и не беспокоиться о их интепретации }
{/literal}
- capture. блок записи вывода в переменную.
Параметры:
(string) name. название. по умолчанию - 'default'
(int) ob. если 1, то для записи используются ob_* функции, если 0, то конкатенация строк вывода. по умолчанию 0. Вариант 1 менее производительный и его стоит использовать лишь в том случае когда нужно "поймать" вывод функций вызываемых в шаблоне.
- php. вставка PHP-кода.
Блок доступен если включен параметр компилятора allow_php_native. Не рекомендуется злоупотреблять этим блоком.
Пример:
{php}phpinfo();{/php}
-
strip. удаление ненужных пробелов и табуляций.
-
textformat. //...
-
dynamic. блок содержимое которого не подлежит кешированию.
-
select/option. обертка для
<select>
Параметры варьируются.
Пример:
{select name=myselect value=$quicky.request.myselect}
{optgroup text=Group}
{option value='1' text=One}
{option value='2' text=Two}
{/optgroup}
{/select}
При повторном показе формы выбранное значение будет сохраняться, что очень удобно.
- joincalculator. установка зависимости между значениями input/textarea посредством мета-языка.
Пример:
Стоимость: {input type=text id=calcfield1}<br />
Комиссия (3%): {input type=text id=calcfield2}
{joincalculator name='mycalc' fields='calcfield1 as one,calcfield2 as two'
onkeydown}
calcfield1 = calcfield2/3*100
calcfield2 = calcfield1/100*3
{/}
В данном примере сразу после изменния комиссии или стоимость моментально считается другое значение.
- helper/function. в шаблонах можно создавать хелперы, т.е. функции доступные внутри шаблона.
Они имеют общую с шаблонами область видимости переменных.
Пример:
{helper myhelper($a,$b,$c)}
{?$d = $b*$b-4*$a*$c}
{return array((-$b+sqrt($d))/(2*$a),(-$b-sqrt($d))/(2*$a))}
{/helper}
-
break. остановка цикла.
-
continue. переход к следующей итерации цикла.
-
return expr. возврат из функции/файла.
-
haltcompiler. остановка компиляции шаблона, используется для отладки, Quicky-теги ниже этой команды не воспринимаются.
-
halt expr. haltcompiler + return expr.
-
resumecompiler. вновь запустить обработку Quicky-тегов, обращаю Ваше внимание на то что команды haltcompiler/resumecompiler обрабатываются при компиляции и не могут справедливо участвовать в условных блоках и циклах.
==Строковые выражения==
Для того чтобы предотвратить вывод результата выполнения Quicky-тега на экран нужно дописать в начале '?', например:
{?$x = 2+2}
Доступные операторы:
| Оператор | Альтернативы | Пример | Описание | Эквивалент в PHP |
|---|---|---|---|---|
| == | eq | $a eq $b | equals | == |
| != | ne, neq | $a neq $b | not equals | != |
| > | gt | $a gt $b | greater than | > |
| < | lt | $a lt $b | less than | < |
| >= | gte, ge | $a ge $b | greater than or equal | >= |
| <= | lte, le | $a le $b | less than or equal | <= |
| === | $a === 0 | check for identity | === | |
| ! | not | not $a | negation (unary) | ! |
| % | mod | $a mod $b | modulous | % |
| is [not] div by | $a is not div by 4 | divisible by | $a % $b == 0 | |
| is [not] even | $a is not even | [not] an even number (unary) | $a % 2 == 0 | |
| is [not] even by | $a is not even by $b | grouping level [not] even | ($a / $b) % 2 == 0 | |
| is [not] odd | $a is not odd | [not] an odd number (unary) | $a % 2 != 0 | |
| is [not] odd by | $a is not odd by $b | [not] an odd grouping | ($a / $b) % 2 != 0 | |
| condition?expr:expr | $a == 2?'~':'-' | ternary operator | $a == 2?'~':'-' |
Операторы компилятора выполняются только при компиляции шаблона, они воздействуют на код скомпилированного шаблона, т.е. их результат становится статическим. На данный момент доступны два оператора: _if и _foreach, синтаксически они идентичны их обычным аналогам, но, разумеется, свойств они не имеют.
Существует отдельная область видимости переменных, из API доступны как свойства $_cpl_vars и $_cpl_configs объекта компилятора Quicky.
Строчные компиляционные теги должны иметь символ _ вначале, например
{_$var|escape}
, после _ не стоит ставить пробел, чтобы не возник конфликт с gettext'ом, если пробел все же нужен, повторите символ _ дважды, т.е.
{__ $var}
В компиляционных выражениях доступны магические константы, в том числе form, что позволяет при необходимости, используя _foreach, работать с переменным числом элементов формы, и частично или полностью абстрагивать форму от ее полей.
Внутри обычных выражений компиляционные вызовы можно делать посредством _ после '('.
Например
{if (_form->name) == 'form1'}
, правило пробела сохраняется.
Quicky_form - это механизм взаимодействия API и элементов формы, позволяющий верстать динамические формы.
Блок
{form ...}...{/form}
имеет специальные параметры:
string name - обязательный параметр - название формы, оно должно строго соответствовать созданному в API.
bool no_quicky_form - отключает механизм для данного блока.
Остальные параметры воспринимаются как атрибуты HTML-тега.
Блок {form} не может быть вложеннным в {form}.
Объект формы доступен с помощью магической константы form. Например, {form->name} выведет имя текущей формы.
Свойства объекта form:
name - название формы.
elements - элементы формы.
Остальные свойства варьируются.
При этом к элементу формы можно обратиться и так: {form->ИМЯ_ЭЛЕМЕНТА}, в случае если имя элемента не пересекается с именем свойства форма.
Доступны хелперы {input} и {select}, их можно использовать и в отдельности, но для взаимодействия с нужным элементом формы нужно указать атрибут join. Например, {input join='text1'} чтобы импортировать свойства элемента, которые можно перекрыть inline в теге.
В папке _test прилагается пример form.php.
Основной объект элемента (Quicky_form_element) содержит следующие методы:
mixed getValue() - получить текущее значение элемента
void addFilter(mixed filter, string errormsg = '') - добавить к полю фильтр.
Фильтры полей используются для упрощения задания простых проверок. Доступные встроенные фильтры: email, url, length (int min = -1, int max = -1), format (string regexp)
Примеры:
$form->text1->addFilter('email','isn\'t e-mail');
$form->text1->addFilter(array('format','~_~'),'need _');
$form->text1->addFilter(array('length',-1,20),'len > 20');Отладочная консоль представляет собой инструмент помогающий устранять неисправности в шаблонах. При вызове функции debug_console будут выведены все значения переменных. Она не показывает время исполнения шаблонов т.к. это задача профайлера (например, xdebug).
Существует два подхода. Можно использовать gettext, но большие куски текста вперемешку с управляющими конструкциями выносить из шаблона неудобно, а делать вагон и маленькую тележку условий - неудобно и непроизводительно.
Ввиду этого, компилятор Quicky имеет два механизма мультиязычности, которые используют свойство lang класса Quicky, при этом создается языкозависимая компиляция для каждого шаблона, таким образом мультиязычность не сказывается отрицательно на производительности.
Первый способ - компиляционный блок {LANG}, например:
{LANG}
{de}Цацки-пецки
{ru}Бутерброд
{default}Sandwich
{/LANG}
Второй способ - вызов callback-функции посредством конструкции
{_ название}
, например:
{_ SANDWICH}
callback-функция опеределяется свойством lang_callback и lang_callback_e (используется с тегом {e_ название} — для экранированного вывода).
Пример:
function quicky_lang_callback($m) {return gettext($m[1]);}
function quicky_lang_callback_e($m) {return addslashes(gettext($m[1]));}
$tpl->lang = 'ru'; // данное свойство должно содержать текущий язык
$tpl->lang_callback = 'quicky_lang_callback';
$tpl->lang_callback_e = 'quicky_lang_callback_e';
Будьте бдительны! Тег {LANG} имеет наибольший приоритет чем {literal}, и {LANG} обрабывается в том числе внутри {literal}.
BB-коды записываются как [блок]содержание[/блок], название блока в закрывающем теге можно опустить, т.е. можно написать [блок]содержание[/]. В зависимости от указанного блока, над содержимым производится соответствующее действие. Например, [b]полужирный[/b] выделит текст полужирным шрифтом. BB-коды могут быть вложенными. BB-коды могут иметь параметры, они записываются как [тег параметр1=значение1 параметр2=значение2..], значение единственного параметра можно передать как [тег=значение_параметра]. Например, [color=red]красный[/color], или [url src=http://host.tld/]ссылка[/].
Список встроенных тегов:
1) [b]...[/b] - полужирный текст.
2) [i]...[/i] - наклонный текст.
3) [u]...[/u] - подчеркнутый текст.
4) [s]...[/s] - зачеркнутый текст.
5) [color=green]...[/color] - цвет текста.
6) [size=15]...[/size] - размер текста.
7) [font=arial]...[/font] - шрифт текста.
8) [img]http://site.tld/image.jpg][/img] - картинка.
9) [link=http://site.tld/]текст ссылки[/link] - ссылка.
10) [g]запрос[/g] - ссылка на Google.
11) [m]запрос[/m] - ссылка на PHP Manual.
12) [list=a][*]первый[*]второй...[/list], [list=0][*]первый[*]второй...[/list] - маркированный список..
13) [quote=Автор]...[/quote] - цитата.
14) [php]...[/php] - подсветка PHP-кода.
15) [code]...[/code] - подсветка кода.
16) [email=admin@host.tld]почта[/email] - ссылка на электронную почту.
17) [literal]...[/literal], [plain]...[/plain] - BB-коды внутри блока не воспринимаются.
18) [p]...[/p] - параграф.
Смайлики записываются как :название:, например 😉 .