From e15df612671c1b3b9f8f9df529221c742e084cde Mon Sep 17 00:00:00 2001 From: bzick Date: Sat, 9 Feb 2013 10:59:08 +0400 Subject: [PATCH] Add docs drafts --- docs/about.md | 8 ++++++++ docs/main.md | 22 ++++++++++++-------- docs/mods/date_format.md | 23 +++++++++++++++++++++ docs/mods/lower.md | 13 ++++++++++++ docs/mods/truncate.md | 22 ++++++++++++++++++++ docs/mods/upper.md | 10 +++++++++ docs/syntax.md | 44 ++++++++++++++++++---------------------- docs/tags/include.md | 2 +- 8 files changed, 111 insertions(+), 33 deletions(-) create mode 100644 docs/mods/date_format.md create mode 100644 docs/mods/lower.md create mode 100644 docs/mods/truncate.md diff --git a/docs/about.md b/docs/about.md index 4310767..6b87c1d 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,3 +1,11 @@ About Aspect ============ +Aspect - самый быстрый, гибкий и тонкий шаблонизатор для PHP, унаследовавший синтаксис от Smarty3 и улучшив его. +Пожалуй это единственный шаблонизатор, который не использет ни регулярные выражения, как Twig, ни лексер от BISON, как Smarty3. +Вы не найдёте ни одного регулярного выражения в ядре Aspect, но тем не менее ядро простое, компактное и очень быстрое. + +* Скорость. Разбор шаблонов постоен на основе нативного [токенайзера](http://docs.php.net/tokenizer). Шаблон преобразуется в исполняемый PHP код, + который может быть закеширован на файловой системе. +* Безопасность. Разборщик шаблон кроптоливо проверяет каждый токен, тем самым не пропуская возможные уязвимоти и фатальные ошибки при исполнении шпблона. +* Гибкость. Любой компонент можно переопределить, по желанию. \ No newline at end of file diff --git a/docs/main.md b/docs/main.md index 24e2b35..49754bc 100644 --- a/docs/main.md +++ b/docs/main.md @@ -11,31 +11,37 @@ Documentation **Modifiers** -* [upper](./mods/upper.md) -* [lower](./mods/lower.md) +Conversation about [modifiers](./modifiers.md) + +* [upper](./mods/upper.md) aka `up` +* [lower](./mods/lower.md) aka `low` * [date_format](./mods/date_format.md) * [date](./mods/date.md) * [truncate](./mods/truncate.md) -* [escape](./mods/escape.md) +* [escape](./mods/escape.md) aka `e`, `url` * [unescape](./mods/unescape.md) * [strip](./mods/strip.md) -Also see [allowed functions](./mods/allowed_functions.md). +* allowed functions: `json_encode`, `json_decode`, `count`, `is_string`, `is_array`, `is_numeric`, `is_int`, `is_object`, +`strtotime`, `gettype`, `is_double`, `ip2long`, `long2ip`, `strip_tags`, `nl2br` -**Internal tags** +**Tags** + +Conversation about [tags](./tags.md) * [var](./tags/var.md) * [if](./tags/if.md), `elseif` and `else` * [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` -* [for](./tags/for.md), `break` and `continue` +* [for](./tags/for.md), `forelse`, `break` and `continue` * [while](./tags/while.md), `break` and `continue` * [switch](./tags/switch.md), `case`, `default` and `break` +* [cycle](./tags/cycle.md) * [include](./tags/include.md) -* [extends](./tags/extends.md), `use` and `block` +* [extends](./tags/extends.md), `use`, `block` and `parent` * [capture](./tags/capture.md) * [filter](./tags/filter.md) * [ignore](./tags/ignore.md) -**Extend Aspect** +**Extends** * [Add tags](./ext/tags.md) * [Add modificators](./ext/mods.md) diff --git a/docs/mods/date_format.md b/docs/mods/date_format.md new file mode 100644 index 0000000..bbd5a71 --- /dev/null +++ b/docs/mods/date_format.md @@ -0,0 +1,23 @@ +Modifier |date_format +===================== + +**draft** + +Модификатор позволят вывести дату в произвольном формате, согласно форматированию [strftime()](http://docs.php.net/strftime). +Модификатор принимает timestamp или строку, которую можно преобразовать через [strtotime()](http://docs.php.net/strtotime). +Формат по умолчанию: `%b %e, %Y`. + + +**[Допустимые квантификаторы формата](http://docs.php.net/strftime#refsect1-function.strftime-parameters)** + + +```smarty +{var $ts = time()} + +{$ts|date_format:"%Y/%m/%d %H:%M:%s"} output like 2013/02/08 21:01:43 +{$ts|date_format:"-1 day"} output like 2013/02/07 21:01:43 + +{var $date = "2008-12-08"} + +{$ts|date_format:"%Y/%m/%d %H:%M:%s"} output like 2008/12/08 00:00:00 +``` \ No newline at end of file diff --git a/docs/mods/lower.md b/docs/mods/lower.md new file mode 100644 index 0000000..86ff225 --- /dev/null +++ b/docs/mods/lower.md @@ -0,0 +1,13 @@ +Modifier |lower +=============== + +Modifier is used to lowercase a variable or string. Have short alias `low` +This is equivalent to the PHP [strtolower()](http://docs.php.net/lower) function. + +```smarty +{var $name = "Bzick"} + +{$name} output Bzick +{$name|upper} output bzick +{$name|up} output bzick too +``` \ No newline at end of file diff --git a/docs/mods/truncate.md b/docs/mods/truncate.md new file mode 100644 index 0000000..6f0d836 --- /dev/null +++ b/docs/mods/truncate.md @@ -0,0 +1,22 @@ +Modifier |truncate +================== + +**draft** + +Обрезает строку до указанной длины. Может обрезать как ровно по символу так и завершивемогуся слову, где итоговоя строка не привыет указанной длины. + +```smarty +{$long_string|truncate:$length:$etc:$break_words:$middle} +``` + +* `$length` обязательный параметр, указывающий максимальную длину выводимой сроки +* `$etc`, по умолчанию `...`, содержащий строку которой будет заменены "лишние" символы. +* `$break_word`, по умолчанию **FALSE**. Включенный флаг, который указывает модификатору не разбивать слово, а найти ближайший пробельный символ, после которого строка буде обрезана +* `$middle`, по умочанию **FALSE**. Включенный флаг, который указывает, что "лишние" данные нужно вырезать из середины строки, а не из конца. + +```smarty +{var $str = "very very long string"} + +{$str|truncate:10:" read more..."} output: very very read more... +{$str|truncate:5:" ... ":true:true} output: very ... string +``` \ No newline at end of file diff --git a/docs/mods/upper.md b/docs/mods/upper.md index 9ab6256..4d64ac6 100644 --- a/docs/mods/upper.md +++ b/docs/mods/upper.md @@ -1,3 +1,13 @@ Modifier |upper =============== +Modifier is used to uppercase a variable or string. Have short alias `up` +This is equivalent to the PHP [strtoupper()](http://docs.php.net/strtoupper) function. + +```smarty +{var $name = "Bzick"} + +{$name} output Bzick +{$name|upper} output BZICK +{$name|up} output BZICK too +``` \ No newline at end of file diff --git a/docs/syntax.md b/docs/syntax.md index d51d6c2..b446242 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -1,31 +1,27 @@ Синтаксис ========= -Базовый синтаксис, по бОльшей части, унаследован от Smarty3. - -### Переменные - -#### Вывод переменной +### Вывод переменной Вывод значений переменных в шаблонизаторе Aspect идентичен правилам вывода шаблонизатора Smarty ```smarty -{$foo} <-- displaying a simple variable (non array/object) -{$foo[4]} <-- display the 5th element of a zero-indexed array +{$foo} +{$foo[4]} {$foo.4} -{$foo.bar} <-- display the "bar" key value of an array, similar to PHP $foo['bar'] +{$foo.bar} {$foo.'bar'} {$foo."bar"} {$foo[bar]} {$foo['bar']} {$foo["bar"]} -{$foo.$bar} <-- display variable key value of an array, similar to PHP $foo[$bar] +{$foo.$bar} {$foo[$bar]} -{$foo->bar} <-- display the object property "bar" -{$foo->bar()} <-- display the return value of object method "bar" +{$foo->bar} +{$foo->bar()} ``` -#### Комбинированные варианты +Комбинированные варианты ```smarty {$foo.bar.baz} @@ -33,11 +29,11 @@ {$foo[4].baz} {$foo[4].$baz} {$foo.bar.baz[4]} -{$foo->bar($baz, 2, $bar)} <-- passing parameters -{"foo"} <-- static values are allowed +{$foo->bar($baz, 2, $bar)} +{"foo"} ``` -#### Математические операции +### Математические операции ```smarty {$x+$y} // will output the sum of x and y. @@ -45,7 +41,7 @@ {$foo[$x+3]*$x+3*$y % 3} ``` -#### Объявление переменных +### Объявление переменных ```smarty {var $foo = $x + $y} @@ -63,7 +59,7 @@ {var $foo=[1,[9,8],3]} // can be nested ``` -#### Работа с объектами +### Работа с объектами ```smarty {$object->method1($x)->method2($y)} @@ -71,7 +67,7 @@ ``` -#### Работа со строками +### Работа со строками Строки в Aspect обрабатываются идентично правилам подстановки переменных в строки в PHP, т.е. в двойных кавычках переменная заменяется на её значение, в одинарных замены не происходит. В отличие от Smarty в строках не обрабатываются управляющие конструкции, например "if", но работают модификаторы. @@ -104,7 +100,7 @@ {var $foo="Ivan"|upper} переменная $foo будет содержать "IVAN" ``` -Подробнее модификаторы описаны в разделе [модификаторы](docs/modifiers.md) +Подробнее модификаторы описаны в разделе [модификаторы](./docs/modifiers.md) ### Функции @@ -128,7 +124,7 @@ {/if} ``` -#### Аргументы +Аргументы Аргументы принимают любой формат переменных, в том числе результаты арифметических операций и модификаторов. @@ -156,18 +152,18 @@ -### Вставка JS +### Как и в Smarty, в шаблонизаторе Aspect используются фигурные скобки для отделения HTML от кода Aspect. Если требуется вывести текст, содержащий фигурные скобки помните о следующих возможностях: -1. Использование блочного тега `{literal}{/literal}`. Текст внутри этого тега не компилируется шаблонизатором и выводится "как есть". +1. Использование блочного тега `{ignore}{/ignore}`. Текст внутри этого тега не компилируется шаблонизатором и выводится "как есть". 2. Если после открывающей фигурной скобки есть пробельный символ, то она не воспринимается как разделитель Aspect и код после неё выводится "как есть". Пример: ```smarty -{literal} +{ignore} @@ -178,7 +174,7 @@ e.innerHTML = text; document.body.appendChild(e); })('test'); - + ``` Выведет diff --git a/docs/tags/include.md b/docs/tags/include.md index 490575f..ea34096 100644 --- a/docs/tags/include.md +++ b/docs/tags/include.md @@ -7,7 +7,7 @@ Tag {include} {include "about.tpl"} ``` -Переменные для подключаемого шаблона можно переопределить +Переменные для подключаемого шаблона можно переопределить, задавая их аргументами тега. ```smarty {include "about.tpl" page=$item limit=50}