Merge pull request #227 from fenom-template/develop

2.9.0
fenom-template · May 7, 2016 · 48f42c8 · 48f42c8
2 parents 279459b + 0d1e7e5
commit 48f42c8
Show file tree

Hide file tree

Showing 30 changed files with 673 additions and 320 deletions.
diff --git a/README.md b/README.md
@@ -1,31 +1,69 @@
 Fenom - Template Engine for PHP
 ===============================
 
-> Composer [package](https://packagist.org/packages/fenom/fenom): `{"fenom/fenom": "2.*"}`. <br />
-> For old version: `{"fenom/fenom": "1.*"}`. <br />
-> [List](https://github.com/fenom-template/fenom/wiki/Migrate-from-1.4.9-to-2.0) of incompatibilities between **1** and **2** versions.
+**Fenóm**  - lightweight and fast template engine for PHP.
 
-[![Latest Stable Version](https://poser.pugx.org/fenom/fenom/v/stable.png)](https://packagist.org/packages/fenom/fenom)
-[![Build Status](https://travis-ci.org/fenom-template/fenom.svg?branch=master)](https://travis-ci.org/fenom-template/fenom)
-[![Coverage Status](https://coveralls.io/repos/fenom-template/fenom/badge.svg?branch=master)](https://coveralls.io/r/fenom-template/fenom?branch=master)
-[![Total Downloads](https://poser.pugx.org/fenom/fenom/downloads.png)](https://packagist.org/packages/fenom/fenom)
+* **Subject:** Template engine
+* **Syntax:** Smarty-like
+* **Documentation:** **[English](./docs/en/readme.md)**, **[Russian](./docs/ru/readme.md)**
+* **PHP version:** 5.3+
+* **State:** [![Build Status](https://travis-ci.org/fenom-template/fenom.svg?branch=master)](https://travis-ci.org/fenom-template/fenom) [![Coverage Status](https://coveralls.io/repos/fenom-template/fenom/badge.svg?branch=master)](https://coveralls.io/r/fenom-template/fenom?branch=master)
+* **Version:** [![Latest Stable Version](https://poser.pugx.org/fenom/fenom/v/stable.png)](https://packagist.org/packages/fenom/fenom)
+* **Packagist:** [fenom/fenom](https://packagist.org/packages/fenom/fenom) [![Total Downloads](https://poser.pugx.org/fenom/fenom/downloads.png)](https://packagist.org/packages/fenom/fenom)
+* **Composer:** `composer require fenom/fenom`
+* **Discussion:** [Fenom Forum](https://groups.google.com/forum/#!forum/php-ion)
+* **Versioning:** [semver2](http://semver.org/)
+* **Performance:** see [benchmark](./docs/en/benchmark.md)
 
-## [Quick start](./docs/en/start.md) :: [Documentation](./docs/readme.md) [[en](./docs/en/readme.md)|[ru](./docs/ru/readme.md)] :: [Benchmark](./docs/en/benchmark.md)
-<!-- :: [Articles](./docs/articles.md) -->
+***
 
-### What is it
+## Quick Start
 
-**Fenóm**  — lightweight template engine for PHP.
+### Install
 
-It means:
+If you use composer in your project then you can to install Fenom as package.
+However, if you are not using composer you have to configure _autoloader_ to work with Fenom.
+Fenom implements the `PSR-0` PHP standard to load classes which are located in the `src/` directory.
+Templater already has own autoload-function, to register call method `Fenom::registerAutoload`:
+```php
+Fenom::registerAutoload();
+```
 
-* Known Smarty-like [syntax](./docs/en/syntax.md) with improvements.
-* Very [fast](./docs/en/benchmark.md).
-* [Lightweight](./docs/en/benchmark.md).
-* Very [flexible](./docs/en/configuration.md#extends).
-* Progressive parser without regular expressions.
-* High [code coverage](https://coveralls.io/r/bzick/fenom?branch=master).
-* Easy to understand [how it works](./docs/en/dev/readme.md).
-* Easy to [use](./docs/en/start.md).
-* Maximum [protection](./docs/en/configuration.md#configure).
+### Setup
 
+There is two way to create Fenom instance:
+
+* Long way: use operator `new`
+* Shot way: use static factory-method
+
+**Long way.** Create you own template provider or default provider `Fenom\Provider` (that is provider read [there](./)).
+Using provider instance create Fenom instance:
+
+```php
+$fenom = new Fenom(new Fenom\Provider($template_dir));
+```
+
+After that, set compile directory:
+
+```php
+$fenom->setCompileDir($template_cache_dir);
+```
+
+This directory will be used for storing compiled templates, therefore it should be writable for Fenom.
+Now Fenom is ready to work and now you can to configure it:
+
+```php
+$fenom->setOptions($options);
+```
+
+**Short way.** Creating an object via factory method with arguments from long way.
+
+```php
+$fenom = Fenom::factory($template_dir, $template_cache_dir, $options);
+```
+
+Now Fenom is ready to work.
+
+### Usage
+
+### Example
diff --git a/docs/en/operators.md b/docs/en/operators.md
@@ -55,7 +55,7 @@ Operators
 {if $a & 1} {var $b = 4 | $flags} {/if}
 ```
 
-### Assignment Operators
+### Assignment operators
 
 * `$a = $b` - assignment
 * `$a += $b` - assignment with addition
@@ -81,9 +81,11 @@ Operators
 * `--$a` - decrement the variable and use it
 * `$a--` - use the variable and decrement it
 
-### String operator
+### String operators
 
-* `$a ~ $b` - return concatenation of variables `$a` and `$b`
+* `$a ~ $b`  - return concatenation of variables `$a` and `$b`
+* `$a ~~ $b` - return concatenation of variables `$a` and `$b` separated by a space
+* `$a ~= $b` - assignment with concatenation
 
 ### Ternary operators
 

diff --git a/docs/en/readme.md b/docs/en/readme.md
@@ -23,22 +23,26 @@ Documentation
 
 [Usage](./syntax.md#tags)
 
-* [set](./tags/var.md), `add` and `var` — define variables
-* [if](./tags/if.md), `elseif` and `else` — conditional statement
-* [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — traversing items in an array or object
-* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
-* [switch](./tags/switch.md), `case`, `default` —
+* [set](./tags/set.md), [add](./tags/set.md#add) and `var` — define variables
+* [if](./tags/if.md), [elseif](./tags/if.md#elseif) and [else](./tags/if.md#else) — conditional statement
+* [foreach](./tags/foreach.md), [foreaelse](./tags/foreach.md#foreaelse),
+  [break](./tags/foreach.md#break) and [continue](./tags/foreach.md#continue) — traversing items in an array or object
+* [switch](./tags/switch.md), [case](./tags/switch.md#case) — complex condition statement
 * [cycle](./tags/cycle.md) — cycles on an array of values
-* [include](./tags/include.md), `insert` —  includes and evaluates the specified template
-* [extends](./tags/extends.md), `use`, `block` and `parent` — template inheritance
+* [include](./tags/include.md), [insert](./tags/include.md#insert) —  includes and evaluates the specified template
+* [extends](./tags/extends.md), [use](./tags/extends.md#use),
+  [block](./tags/extends.md#block), [parent](./tags/extends.md#parent) and [paste](./tags/extends.md#paste) — template inheritance
 * [filter](./tags/filter.md) — apply modifier on a block of template data
 * [ignore](./tags/ignore.md) — ignore Fenom syntax
-* [macro](./tags/macro.md) and `import` — template functions
+* [macro](./tags/macro.md) and [import](./tags/macro.md#import) — template functions
 * [autoescape](./tags/autoescape.md) — escape template fragment
 * [raw](./tags/raw.md) — unescape template fragment
 * [unset](./tags/unset.md) — unset a given variables
 * or [add](./ext/extend.md#add-tags) yours
 
+Deprecated tags
+
+* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
 
 ***
 

diff --git a/docs/en/tags/cycle.md b/docs/en/tags/cycle.md
@@ -1,13 +1,15 @@
 Tag {cycle}
 ===========
 
+`{cycle}` is used to alternate a set of values.
+
 ```smarty
-{for $i=$a.c..}
+{foreach 1..10}
     <div class="{cycle ["odd", "even"]}">
-{/for}
+{/foreach}
 
 
-{for $i=$a.c..}
+{foreach 1..10}
     <div class="{cycle ["odd", "even"] index=$i}">
-{/for}
+{/foreach}
 ```
diff --git a/docs/en/tags/extends.md b/docs/en/tags/extends.md
@@ -1,82 +1,68 @@
-Tag {extends} [RU]
-==================
+Tag {extends}
+=============
 
-Тег `{extends}` реализует наследование шаблонов, иерархия, обратная {include}. То есть шаблон сам выбирает своего родителя.
+`{extends}` tags are used in child templates in template inheritance for extending parent templates.
+The `{extends}` tag must be on before any block.
+Also if a child template extends a parent template with the `{extends}` tag it may contain only `{block}` tags. Any other template content is ignored.
 
 ### {extends}
 
-Родительский шаблон можно задать единожды и до объявления какого-либо блока.
-
 ```smarty
 {extends 'parent.tpl'}
 ```
 
-Имя родительского шаблона может быть задан динамически, в этом случае производительность отрисовки может снизиться.
-
-```smarty
-{extends $parent_tpl}
-```
-
 ### {block}
 
-Блок указывает фрагмент шаблона, который будет передан родителю. Имя блока может быть задано как явно
-
 ```smarty
-{block bk1}content 1{/block}
-...
 {block 'bk2'}content 2{/block}
 ```
 
-так и не явно, но в данном случае пострадает производительность
-
-```smarty
-{block "bk{$number}"}content {$number}{/block}
-...
-{if $condition}
-    {block "bk-if"}content, then 'if' is true{/block}
-{else}
-    {block "bk{$fail}"}content, then 'if' is false{/block}
-{/if}
-```
-
 ### {use}
 
 Что бы импортировать блоки из другого шаблона используйте тег {use}:
 
 ```smarty
-{use 'blocks.tpl'}
-```
+{use 'blocks.tpl'} merge blocks from blocks.tpl template
 
+{block 'alpha'} rewrite block alpha from blocks.tpl template, if it exists
+   ...
+{/block}
+```
 
 ### {parent}
 
-Planned. Not supported yet. Feature #5.
-
 ```smarty
-{block 'block1'}
+{extends 'parent.tpl'}
+
+{block 'header'}
   content ...
-  {parent}
+  {parent}  pase code from block 'header' from parent.tpl
   content ...
 {/block}
 ```
 
-### Performance
-
-Алгоритм реализации наследования шаблонов может работать в разных режимах, в зависимости от условий.
-Каждый режим имеет свою производительность.
-
-1. **Максимальная** производительность:
-    * Имена шаблонов в теге {extends } заданы явно, без использования переменных и условий.
-    * Имена блоков заданы явно, без использования переменных, условий и не вложены ни в какой другой тег.
-2. **Средняя** производительность:
-    * Имена шаблонов в теге {extends } заданы явно, без использования переменных и условий.
-    * Имена блоков заданы **не** явно, с использованием переменныч, условий или могут быть вложенные в другие теги.
-3. **Низкая** производительность:
-    * Имена шаблонов в теге {extends } заданы **не** явно, с использованием переменных и условий.
-    * Имена блоков заданы явно, без использования переменных, условий и не вложены ни в какой другой тег.
-4. **Минимальная** производительность:
-    * Имена шаблонов в теге {extends } заданы **не** явно, с использованием переменных и условий.
-    * Имена блоков заданы **не** явно, с использованием переменных, условий или могут быть вложенные в другие теги.
-
-Режим может идти только на понижение, при изменении условий во время прохождения по иерархии шаблонов.
-При любом режиме работы не используется буферизация данных, то есть данные выводятся сразу.
+### {paste}
+
+Paste code of any block
+
+```smarty
+{block 'b1'}
+    ...
+{/block}
+
+{block 'b2'}
+    ...
+    {paste 'b1'} paste code from b1
+{/block}
+
+```
+
+### {$.block}
+
+Checks if clock exists
+
+```smarty
+{if $.block.header}
+    block header exists
+{/if}
+```
diff --git a/docs/en/tags/filter.md b/docs/en/tags/filter.md
@@ -1,10 +1,12 @@
 Tags {filter}
 =============
 
-Позволяет применить модификаторы на фрагмент шаблона
+Apply modifier to template area.
 
 ```smarty
 {filter|strip_tags|truncate:20}
 Remove all HTML <b>tags</b> and truncate {$text} to 20 symbols
 {/filter}
-```
+```
+
+**Note**: output buffering used. May be used a lot of memory if you output a lot of data.