From 0ca0d180deab8daa5830bdf9e2487666f60a9a24 Mon Sep 17 00:00:00 2001
From: Giuseppe Mazzapica <giuseppe.mazzapica@gmail.com>
Date: Thu, 2 Jul 2015 23:00:12 +0200
Subject: [PATCH] Update documentation for v0.6

---
 README.md                            |  12 ++
 docs/EXTENDING/CUSTOM-BLOCKS.md      |  95 +++++++++
 docs/EXTENDING/CUSTOM-EXTENSIONS.md  |  58 +----
 docs/FUNCTIONS/BLOCKS.md             |  81 +++++++
 docs/FUNCTIONS/HTML-HELPERS.md       |   2 +-
 docs/FUNCTIONS/LINK-HELPERS.md       |   2 +-
 docs/FUNCTIONS/LOOP-HELPERS.md       |   2 +-
 docs/FUNCTIONS/URI-HELPERS.md        |   2 +-
 docs/GETTING-STARTED/ALIAS.md        |  46 ++++
 docs/GETTING-STARTED/ENGINE.md       |  43 +++-
 docs/GETTING-STARTED/FOLDERS.md      | 152 +++++++++++--
 docs/GETTING-STARTED/INSTALLATION.md |   2 +-
 docs/INTEGRATE/API.md                | 305 +++++----------------------
 docs/INTEGRATE/OVERVIEW.md           |  53 +----
 docs/TEMPLATES/OVERVIEW.md           |   6 +
 docs/TEMPLATES/SECTIONS-RENDERING.md | 107 ++++++++++
 16 files changed, 589 insertions(+), 379 deletions(-)
 create mode 100644 docs/EXTENDING/CUSTOM-BLOCKS.md
 create mode 100644 docs/FUNCTIONS/BLOCKS.md
 create mode 100644 docs/GETTING-STARTED/ALIAS.md
 create mode 100644 docs/TEMPLATES/SECTIONS-RENDERING.md

diff --git a/README.md b/README.md
index d17e76c..7b7672b 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ FOIL
 
 ...and many more
 
+
 # Why?
 
 Templates engines like Twig, or Blade are a great thing, really.
@@ -47,6 +48,17 @@ I wrote [a blog post](http://gm.zoomlab.it/2015/template-engines-i-moved-from-lo
 
 Foil is framework agnostic, only thing needed is PHP 5.4+ and Composer to add Foil to you PHP project.
 
+---
+
+# Backward Incompatibility Notice
+
+Foil version **0.6** introduced backward incompatibility changes. Internal objects mechanism changed a lot, but
+core features and especially template functions were not affected.
+
+Please see v0.6 release notes to know more on the topic.
+
+---
+
 # License
 
 Foil is open source and released under MIT license. See LICENSE file for more info.
diff --git a/docs/EXTENDING/CUSTOM-BLOCKS.md b/docs/EXTENDING/CUSTOM-BLOCKS.md
new file mode 100644
index 0000000..deedb1d
--- /dev/null
+++ b/docs/EXTENDING/CUSTOM-BLOCKS.md
@@ -0,0 +1,95 @@
+<!--
+currentMenu: "customblocks"
+currentSection: "Extending Foil"
+title: "Custom Blocks"
+-->
+
+# Custom Blocks
+
+Custom blocks are callback that perform operations on a block of HTML that is delimited in templates using
+`block()` and `endblock()` template methods.
+
+Please have a look at the section "*Blocks & Helpers / Blocks*" to know more about blocks.
+
+## Add a custom block
+
+Adding a block callback is as easy as pass a block name and a block callback to the `Engine::registerBlock()` method.
+
+For example, let's write a callback that takes a block of text, and output every new line in a separate `<li>` tag, all wrapped in a `<ul>` tag.
+
+```php
+$engine->registerBlock(
+   'eol2ul',
+   function($html) {
+      // remove white space at boundaries an normalize end of lines
+      $trim = trim(str_replace("\r\n", "\n", $html));
+      // explode by end of lines
+      $exploded = explode("\n", $trim);
+      // implode lines into a list
+      return '<ul><li>'.implode('</li><li>', $exploded).'</li></ul>';
+   }
+);
+```
+
+After that, in a template:
+
+```php
+<?php $this->block('eol2ul') ?>
+
+a
+b
+c
+
+<?php $this->endblock() ?>
+```
+
+Will output:
+
+```html
+<ul>
+    <li>a</li>
+    <li>b</li>
+    <li>c</li>
+</ul>
+```
+
+## Blocks with arguments
+
+Blocks callbacks may accept a variadic number of arguments that can be passed to `block()` function right after block name.
+
+A simple example that will covert given words in a block of text to links to the Google search url for that word:
+
+```php
+$engine->registerBlock(
+   'googleize',
+   function() {
+      $args = func_get_args();
+      $html = array_shift($args); // block of HTMl is first argument
+      $words = $args; // all the words passed ot open() are now in $args array
+      $format = '<a href="https://www.google.com#q=%s" target="_blank">%s</a>';
+      foreach($words as $word) {
+        $html = str_replace($word, sprintf($format, urlencode($word), $word), $html);
+      }
+      return $html;
+   }
+);
+```
+
+In template...
+
+```php
+<?php $this->block('googleize', 'Lorem', 'adipiscing') ?>
+
+Lorem ipsum dolor sit amet,
+consectetur adipiscing elit.
+
+<?php $this->endblock() ?>
+```
+
+The output will be:
+
+```html
+<a href="https://www.google.com#q=Lorem" target="_blank">Lorem</a> ipsum dolor sit amet,
+consectetur <a href="https://www.google.com#q=adipiscing" target="_blank">adipiscing</a> elit.
+```
+
diff --git a/docs/EXTENDING/CUSTOM-EXTENSIONS.md b/docs/EXTENDING/CUSTOM-EXTENSIONS.md
index 911a392..d636e19 100644
--- a/docs/EXTENDING/CUSTOM-EXTENSIONS.md
+++ b/docs/EXTENDING/CUSTOM-EXTENSIONS.md
@@ -168,60 +168,4 @@ class FooExtension implements ExtensionInterface, FinderAwareInterface
 ```
 
 In a finder-aware extension, like the one above, is possible to use **`$this->find($template)`** to find templates by their names,
-in the exact same way you can call `$engine->find($template)` when you have access to engine object.
-
-
-## API Aware Extensions
-
-Foil ships with a powerful tool: an API object that helps to integrate Foil in any system, giving access to **all** Foil features.
-
-If you need to develop an extension that interacts very deep with Foil internal objects,
-you can build an extension that is aware of that API object, obtaining access to all Foil features.
-
-To do that you need to implement the `Foil\Contracts\APIAwareInterface` and implement its methods.
-
-The simplest way to to that is to use the `Foil\Traits\APIAwareTrait`.
-
-The *skeleton* of an API-aware extension looks like so:
-
-```php
-namespace MyApp;
-
-use Foil\Contracts\ExtensionInterface;
-use Foil\Contracts\APIAwareInterface;
-use Foil\Traits\APIAwareTrait;
-
-class FooExtension implements ExtensionInterface, APIAwareInterface
-{
-    use APIAwareTrait;
-
-    public function setup(array $args){
-    }
-
-    public function provideFilters(){
-    }
-
-    public function provideFunctions()
-    {
-    }
-
-}
-```
-
-In an API-aware extension, like the one above, is possible to use **`$this->api()`** to get the API object and call on it all supported methods,
-see *"Integrate Foil"* docs section to know which they are what they do.
-
-## The Base Extension Class
-
-To speed-up extension development, instead of implementing one or more _*Aware_ interfaces, is possible to extend the `Foil\Extensions\Base` abstract class.
-
-That class:
-
- - is API aware, so you can use API object in it to access all Foil features
- - implements all the 3 methods of `ExtensionInterface`:
-   - `setup()` is implemented just saving the arguments received in the `$args` object property
-   - `provideFilters()` is implemented by returning an empty array
-   - `provideFunctions()` is implemented by returning an empty array
-
-  In this way is possible to write extensions that provide only filters (or only functions) overriding only the related method
- - has a method `option()` that lets you access to Engine options, e.g. current setting for autoescape, template folders, default file extension and so on
+in the exact same way you can call `$engine->find($template)` when you have access to engine object.
\ No newline at end of file
diff --git a/docs/FUNCTIONS/BLOCKS.md b/docs/FUNCTIONS/BLOCKS.md
new file mode 100644
index 0000000..180aaf9
--- /dev/null
+++ b/docs/FUNCTIONS/BLOCKS.md
@@ -0,0 +1,81 @@
+<!--
+currentMenu: "blocks"
+currentSection: "Blocks & Helpers"
+title: "Blocks"
+-->
+
+# Blocks
+
+Blocks are parts of a template that before being outputted pass through a callback.
+
+Blocks were added in version 0.6.
+
+## Blocks characteristics
+
+ - a block is opened with `block()` and closed with `endblock()`
+ - `block()` takes as 1st argument the name fo the block, and a variadic number of arguments that are then passed to block callback
+ - blocks can be nested
+ - `endblock()` may *optionally* take as 1st argument the name of the block to close. When given, Foil checks that it is the last opened block
+   and throws an exception if not. This is useful for nested blocks.
+
+## Shipped Blocks
+
+At the moment there are 2 blocks shipped with Foil:
+
+ - `"spaceless"`
+ - `"repeat"`
+
+## Repeat
+
+The most simple block is "repeat". This is an  example of how it works:
+
+```php
+<?php $this->block('repeat', 3) ?>
+
+<p>say again</p>
+
+<?php $this->endblock() ?>
+```
+
+The code above will output:
+
+```html
+<p>say again</p>
+<p>say again</p>
+<p>say again</p>
+```
+
+In short, it is very similar to a `for` loop, and if fact it was added mainly to easily explain how blocks work.
+
+## Spaceless
+
+Inspired by [`spaceless` Twig tag](http://twig.sensiolabs.org/doc/tags/spaceless.html), it removes whitespaces from a block of HTML.
+
+May be useful in some situations, e.g. with some CSS frameworks that requires no space between certain elements.
+
+Example:
+
+```php
+<?php $this->block('spaceless') ?>
+
+    <div>
+        <strong>foo</strong>
+    </div>
+
+<?php $this->endblock() ?>
+```
+
+Will output:
+
+```html
+<div><strong>foo</strong></div>
+```
+
+## Custom Blocks
+
+In next versions of Foil is possible that more blocks will be added, but the real power of blocks resides in the
+possibility to write custom blocks that are no more than callbacks that perform operations on a block of HTML.
+
+It is an easy and straightforward way to write functions that accept even big blocks of HTML without but using a nice looking and easily readable syntax in templates.
+
+How to write custom blocks is documented in *"Extending Foil / Custom Blocks"* section.
\ No newline at end of file
diff --git a/docs/FUNCTIONS/HTML-HELPERS.md b/docs/FUNCTIONS/HTML-HELPERS.md
index e3ef5d3..46b8287 100644
--- a/docs/FUNCTIONS/HTML-HELPERS.md
+++ b/docs/FUNCTIONS/HTML-HELPERS.md
@@ -1,6 +1,6 @@
 <!--
 currentMenu: "htmlhelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "HTML & Form Helpers"
 -->
 
diff --git a/docs/FUNCTIONS/LINK-HELPERS.md b/docs/FUNCTIONS/LINK-HELPERS.md
index 0cb79c1..6499458 100644
--- a/docs/FUNCTIONS/LINK-HELPERS.md
+++ b/docs/FUNCTIONS/LINK-HELPERS.md
@@ -1,6 +1,6 @@
 <!--
 currentMenu: "linkhelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "Link Helpers"
 -->
 
diff --git a/docs/FUNCTIONS/LOOP-HELPERS.md b/docs/FUNCTIONS/LOOP-HELPERS.md
index cb30581..7fba34e 100644
--- a/docs/FUNCTIONS/LOOP-HELPERS.md
+++ b/docs/FUNCTIONS/LOOP-HELPERS.md
@@ -1,6 +1,6 @@
 <!--
 currentMenu: "loophelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "Loop Helpers"
 -->
 
diff --git a/docs/FUNCTIONS/URI-HELPERS.md b/docs/FUNCTIONS/URI-HELPERS.md
index 81681db..bfa0387 100644
--- a/docs/FUNCTIONS/URI-HELPERS.md
+++ b/docs/FUNCTIONS/URI-HELPERS.md
@@ -1,6 +1,6 @@
 <!--
 currentMenu: "urihelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "URI Helpers"
 -->
 
diff --git a/docs/GETTING-STARTED/ALIAS.md b/docs/GETTING-STARTED/ALIAS.md
new file mode 100644
index 0000000..335b7c9
--- /dev/null
+++ b/docs/GETTING-STARTED/ALIAS.md
@@ -0,0 +1,46 @@
+<!--
+currentMenu: "alias"
+currentSection: "Getting Started"
+title: "Alias"
+-->
+
+# Alias
+
+Inside templates, all the Foil features are accessed via the `$this` variable,
+e.g. template variables are accessed like `$this->varName` and template function like `$this->functionName()`.
+
+Even if the word *"this"* is made by just 4 letters, being typed more and more times in a template requires a lot of typing.
+
+For example, accessing a variable like `$variable` is pretty shorter than `$this->variable`.
+
+I am strongly convinced that benefits coming from Foil approach completely worth the additional 6 letters needed to access a variable.
+
+However, starting from version 0.6, Foil provides a way to shorten its syntax.
+
+## Introducing Alias Variable
+
+Alias variable is a global variable available in templates that aliases `$this`.
+
+E.g. using the variable `$T` as alias, a template variable can be accessed using `$T->variable`
+as well as a template function using `$T->functionName()`.
+
+The alias must be set, using the `'alias'` option, when Foil Engine is instantiated:
+
+
+```php
+$engine = Foil\engine([
+  'folders' => ['path/to/templates'],
+  'alias'   => 'T',
+]);
+```
+
+the only constraint is that the alias must be a valid variable name. E.g. something like:
+
+```php
+$engine = Foil\engine([
+  'folders' => ['path/to/templates'],
+  'alias'   => 'Foil',
+]);
+```
+
+is totally fine, and allows to access Foil features in templates using `$Foil->` syntax.
diff --git a/docs/GETTING-STARTED/ENGINE.md b/docs/GETTING-STARTED/ENGINE.md
index fed94a3..0e4dc96 100644
--- a/docs/GETTING-STARTED/ENGINE.md
+++ b/docs/GETTING-STARTED/ENGINE.md
@@ -6,24 +6,57 @@ title: "Engine"
 
 # Engine
 
-There are very few components in Foil you should interact with.
+There are very few components in Foil you should interact with. The most important is the Foil **Engine**.
 
-The most important is the Foil **Engine**. An instance of that class can be obtained using **`Foil\engine()`** function.
+## Obtaining an Engine instance
 
-You need to pass (only first time you call it) an array of arguments that let you configure how Foil engine will work.
+An instance of that class can be obtained using:
+
+ - **`Foil\engine()`** function..
+ - **`Foil\Foil::boot()`** method. It returns an instance of `Foil\Foil` class. That class has a method `engine()` that returns an instance of the engine.
+
+You need to pass to both an array of arguments that let you configure how Foil engine will work.
+
+The two methods works in same way, the `Foil\Foil::boot()` method was introduced in version `v0.6`.
+
+### With Engine Function
 
 ```php
 $engine = Foil\engine([
   'folders' => ['path/to/templates']
 ]);
+```
+
+### With `boot()` Method (since v0.6)
+
+```php
+$foil = Foil\Foil::boot([
+    'folders' => ['path/to/templates']
+]);
+$engine = $foil->engine();
+```
 
+## Render a template file with some data
+
+Having an instance of the engine, render a template with some data is just a matter of:
+
+```
 echo $engine->render('a-template', $some_data);
 ```
 
 The code above is a very simple (and working) example on how to instantiate Foil engine and use it to render a template with some data.
 
-Please note:
-
 - `render()` method here takes just template name (no file extension, no folder): engine will search for the template in registered template folders. Foil engine will also add default extension, that is `.php`, to file name. This behavior can be customized using engine options.
 
 - `$some_data` must be an associative array. Array keys will be variable names in the template. There are powerful tools in Foil to interact with template data inside template file. Moreover, directly passing data to `render()` is not the only way to add context for templates, Foil comes with a context API that lets you pre-assign data to templates under specific conditions.
+
+
+
+## Warning
+
+The function `engine()` in versions older than `v0.6` used to return the *same* instance of the engine when called more times during same request.
+
+This was changed in version `v0.6`, and now every time `Foil\engine()` is called it returns a *"fresh"* instance of the engine, that has nothing
+shared with any previously got instance.
+
+Create an instance of the engine may consume some resources, so re-using the same instance can be a good idea, however, that task is now left to implementers that are free to do that as they prefer.
diff --git a/docs/GETTING-STARTED/FOLDERS.md b/docs/GETTING-STARTED/FOLDERS.md
index 4568e0c..5a81810 100644
--- a/docs/GETTING-STARTED/FOLDERS.md
+++ b/docs/GETTING-STARTED/FOLDERS.md
@@ -6,43 +6,87 @@ title: "Folders"
 
 # Folders
 
-When a template is required, Foil will search for it inside registered template folders. There are two ways to add folders to the engine:
+When a template is required, Foil will search for it inside registered template folders.
 
- 1. to use `"folders"` option for `Foil\engine()`
- 2. to call `addFolder()` method on the engine instance that `Foil\engine()` returns
-
-Both methods can be used in combination:
+An array of folders where to search for templates can be passed to `Foil\engine()` method (or to `Foil::boot()` method) as part of the options array, using the key `"folders"`:
 
 ```php
 $engine = Foil\engine([
-  'folders' => ['path/to/templates']
+  'folders' => ['/path/to/templates']
 ]);
 
-$engine->addFolder('another/path/to/templates');
-
 $engine->render('a-template', $some_data);
 ```
 
-In the example above a file named `a-template.php` is first searched in `'path/to/templates'` folder and if not found there, Foil will search for it in `'another/path/to/templates'` folder.
-
-There is no limit in the number of folders can be added, but note that a large number may slow down template find process, because Foil have to search any folder until it founds the required template.
+The code above looks for the file `/path/to/templates/a-template.php`.
 
 It is possible to keep templates *in order* and at same time register just a few folders by using **subfolders**.
 
-For example, if you registered the path `'path/to/templates'` and you have a template named `'article'` inside the folder `'path/to/templates/blog'`,
+For example, if you registered the path `'/path/to/templates'` and you have a template named `'article'` inside the folder `'/path/to/templates/blog'`,
 you don't need to register this subdirectory, but just to pass subfolder name to `render()`:
 
 ```php
 $engine->render('blog/article', $some_data);
 ```
 
+## Change Engine folders after initialization
+
+After `Engine` class have been instantiated, there is still possibility to change the folders where it looks for template files:
+
+ - using `Engine::addFolder()` method
+ - using `Engine::setFolders()` method
+ - using `Finder::in()` method
+
+### Engine::addFolder()
+
+The easiest way is to use `Engine::addFolder()` method. As its name suggests, this method adds a folder where engine looks for templates, without touching the others.
+
+```php
+$engine = Foil\engine([
+  'folders' => ['/path/to/templates']
+]);
+
+$engine->addFolder('/another/path/to/templates');
+
+$engine->render('a-template', $some_data);
+```
+
+In the example above, the file `a-template.php` is first searched in `'/path/to/templates'` folder and if not found there, Foil will search for it in `'/another/path/to/templates'` folder.
+
+There is no limit in the number of folders can be added, but note that a large number may slow down template finding process, because Foil have to search any folder until it founds the required template.
+
+### Engine::setFolders()
+
+This method accepts an array of folders and can be used to completely replace any already added folder.
+
+### Finder::in()
+
+This method directly acts on the `Finder` class that is used by Foil to find templates in filesystem.
+
+To obtain the instance of `Finder` where to call the method you need to call the `$engine->finder()` method.
+
+`Finder::in()` method takes 2 arguments, an array of folders (just like `Engine::setFolder()`) and a boolean value `$reset`.
+
+When `$reset` is true, `Finder::in()` is exactly equivalent to call `Engine::setFolders()`, so you may prefer to use the latter, as more easily accessible.
+
+When `$reset` is false, all the passed folders are:
+
+ - added if the ID associated to them is not yet registered (a sort of *batch* `Engine::addFolder()`)
+ - updated if the ID associated to them is already registered
+
+To understand what *"the ID associated to folders"* means read next section.
+
 ## Target specific folders
 
-What said above means that if two or more files with same name exist in different folders, only the first found (where folder are searched in registration order) is used. This behavior may not be desirable, e.g. if you want to render a template in a specific folder. Foil allows to target specific folders by assigning ID to folders.
+When two or more files with same name exist in different registered folders, only the first found (where folder are searched in registration order) is used.
+
+This behavior may not be desirable, e.g. if you want to render a template in a specific folder.
 
-Both folders registration methods support folder IDs:
+Foil allows to target specific folders by assigning **ID** to folders.
 
- - when folders are passed as `"folders"` argument for `Foil\engine()` is possible assign IDs to folders using an associative array, where each key is the folder ID.
+All folders registration methods support folder IDs:
+
+ - when using methods that accept folders as array, IDs are the array keys
  - when using `addFolder` method, the second argument can be a folder ID
 
 Example:
@@ -57,8 +101,84 @@ $engine = Foil\engine([
 $engine->addFolder('another/path/to/templates', 'secondary');
 ```
 
-Once folders are registered with IDs, is possible to target a specific folder inside `render()` method (and in all the methods that accepts template names) using folder ID and a double column before template name:
+Once folders are registered with IDs, is possible to target a specific folder inside `render()` method (and in all the methods that accept template names) using folder ID and a double column before template name:
 
 ```php
 $engine->render('secondary::template-name', $some_data);
 ```
+
+### Finder::in() and folders names
+
+As said above, `Finder::in()` method accepts an array of folders and its behaviour, when `$reset` argument is `false`, depends on the registered folders IDs.
+
+An example should clarify how it works:
+
+```php
+$engine = Foil\engine([
+  'folders' => [
+     'one' => 'path/to/templates/one',
+     'two' => 'path/to/templates/two',
+   ]
+]);
+```
+
+And somewhere after that
+
+```php
+$finder = $engine->finder();
+
+$finder->in([
+  'three' => 'path/to/templates/three',
+  'one'   => 'path/to/templates/alternative/one',
+]);
+```
+
+After that, the registered folders will be:
+
+```php
+[
+  'one'   => 'path/to/templates/alternative/one', // this have been edited
+  'two'   => 'path/to/templates/two'
+  'three' => 'path/to/templates/three'            // this have been added
+]
+```
+
+So
+
+ - the folder with ID `'one'` has been updated, because its ID was already registered
+ - the folder with ID `'three'` has been added, because its ID was not registered
+
+Please note how `Finder::in()` was not able to change the order of folders.
+
+In fact, after `Finder::in()` was called, the folder with ID `'one'` is still the first folder
+where Foil will look to templates, even if it points to a different folder.
+
+If you need to change the order of folders, you need to set `$reset` argument to `true` or use `Engine::setFolders` method.
+
+Those methods can be used in combination with `Finder::dirs()` method that return the array of all folders currently in use.
+
+**Please note**: `$reset` argument was introduced in version `0.6`.
+
+
+## All folders have IDs
+
+When registering folders (no matter the method) the folders "ID" is always optional: methods that accepts an array of folders
+do not complain if the array is not an *associative* array, and when using `Engine::addFolder()` method, the second argument is optional.
+
+However, Foil **always assign an ID to a folder** if is not *manually* assigned.
+
+The automatically assigned ID is made by the folder name and its direct folder parent name joined with a dot.
+
+E.g. the ID assigned to the folder `/path/to/templates` would be `to.templates`.
+
+This may brings some problems, e.g. the two paths:
+
+ - `/one/path/to/templates`
+ - `/another/path/to/templates`
+
+are assigned to same ID, and Foil will be not capable to distinguish between the two.
+
+This may appear an awful behavior, however it make pretty easy to access a specific folder by ID in a predictable way
+even when folders are registered with no IDs.
+
+If you are afraid of (or you are experimenting) such conflicts, always register folders using unique IDs.
\ No newline at end of file
diff --git a/docs/GETTING-STARTED/INSTALLATION.md b/docs/GETTING-STARTED/INSTALLATION.md
index 87718a1..c310f6e 100644
--- a/docs/GETTING-STARTED/INSTALLATION.md
+++ b/docs/GETTING-STARTED/INSTALLATION.md
@@ -24,7 +24,7 @@ As alternative you can directly edit your `composer.json` by adding:
 ```json
 {
   "require": {
-    "foil/foil": "~0.4"
+    "foil/foil": "~0.6"
   }
 }
 ```
diff --git a/docs/INTEGRATE/API.md b/docs/INTEGRATE/API.md
index c46ac04..05c7274 100644
--- a/docs/INTEGRATE/API.md
+++ b/docs/INTEGRATE/API.md
@@ -1,289 +1,90 @@
 <!--
-currentMenu: "api"
+currentMenu: "apifunctions"
 currentSection: "Integrate Foil"
-title: "API Functions"
+title: "API"
 -->
 
-# API Functions
+# API
 
-### Note On Function Names
+## Warning
 
-API functions can be called as namespaced functions, e.g. `Foil\engine()` or as methods of Foil API object.
+Foil versions older than 0.6 used to have more API functions.
 
-Function names with more than one word are written using snake_case and you can call them in that way as API object methods,
-but for consistence with PSR-1 coding style you can also call them using camelCase.
+With v0.6 number of functions decreased and now are available the only available functions are listed below.
 
-For example, the function `Foil\render_template()` can also be ran with `$api->renderTemplate()`.
+Moreover, in older versions, there was available an `API` object that worked as a *proxy* to API functions.
+That object **is no more available** starting from version 0.6.
 
----
+## Available functions
 
-# `foil()`
+All the API functions are available under the `Foil` namespace.
 
-```php
-/**
- * @param  string|void $which            Service id
- * @param  array       $options          Engine options
- * @param  array       $custom_providers Custom service provider classes
- *
- * @return mixed       The container or the service whose id has been passed in $which
- */
-
-function foil($which = null, array $options = [], array $custom_providers = [])
-```
-
-You should very rarely (close to never) use this function directly. In fact, it is used by all the functions to access
-Foil DI container, that is a [Pimple](http://pimple.sensiolabs.org/) instance or any service registered in it.
-
-The only case in which you need to use this function is when you want to add additional service providers to be registered
-in Foil container.
-
-That can be done by passing to the function an array of service provider class names as 3rd argument.
-Note that in that way you can also override default Foil service providers, but it implies you know what you are doing or sky will fall on your head.
-
-Only in such case, you can get a Foil engine instance with `$engine = Foil\foil('engine', $options, $custom_providers)` instead of using the
-`engine()` function.
-
----
-
-# `engine()`
-
-```php
-/**
- * @param  array        $options Options: autoescape, default extension, folders...
- *
- * @return \Foil\Engine
- */
-
-function engine(array $options = [])
-```
-
-This function is the preferred way to obtain an instance of Foil engine that can be used to render templates and access to most of Foil features.
-
-`$options` argument is used to configure Foil behavior, see *"Getting Started"* section to know more.
-
-When called more than once the function returns always the same instance of the engine. Also note that you need to pass engine options only first time the function is called.
-
----
-
-# `render_template()`
-
-```php
-/**
- * @param  string $path    Full path for the template
- * @param  array  $data    Template context
- * @param  array  $options Options for the engine
- *
- * @return string
- */
-
-function render_template($path, array $data = [], array $options = [])
-```
-
-This is an alternative to call `render()` method on Foil engine instance, but there is a difference:
-this function needs a template full file path, whereas `render()` needs just template name.
-
-Using this function is possible to quickly render a template and you don't need to set any template folder for the engine.
-
-If in your application you have a custom method to retrieve template file paths, this function will be handy.
-
-It worth noting that `renderTemplate()` can be called on a Foil engine instance too.
-
----
-
-# `option()`
-
-```php
-/**
- * @param  string $which Option name
- *
- * @return mixed
- */
-
-function option($which = null)
-```
-
-This function can be used to retrieve any option that was passed when Foil engine was instantiated.
-
-It is pretty useful in API-aware extensions (see *"Extending Foil / Custom Extensions"*) to create configurable custom functions and filters.
-
----
-
-# `add_context()`
-
-```php
-/**
- * @param array   $data     Data to be passed to matching templates
- * @param string  $needle   String to compare template name to
- * @param boolean $is_regex If true template name will be compared using $needle as a regex
- */
-
-function add_context(array $data, $needle, $is_regex = false)
-```
-
-This function is equivalent to `$engine->useContext()` method when used to pass data to groups of templates based on a string search (optionally regex) against their names.
-
-See *"Data / Context API"* for more information.
-
----
-
-# `add_global_context()`
+The available functions are:
 
-```php
-/**
- * @param array $data Data to be passed to **all** templates
- */
-
-function add_global_context(array $data)
-```
-
-Adds some data to all templates. Is equivalent to `$engine->useData()`.
-
-See *"Data / Context API"* for more information.
-
----
-
-# `add_context_using()`
-
-```php
-/**
- * @param ContextInterface $context Context class to add
- */
-
-function add_context_using(Foil\Contracts\ContextInterface $context)
-```
-
-This function is equivalent to `$engine->useContext()` when used to pass data to groups of templates using a **custom context class**.
-
-See *"Data / Context API"* for more information.
-
----
-
-# `run()`
-
-```php
-/**
- * @param string $function Function name
- *
- * @return mixed
- */
-
-function run($function)
-```
-
-Custom functions registered to extends Foil features can be ran inside template files as methods of template object (accessed via `$this`).
-
-This function allows to run any registered custom function outside template files.
-
-Additional arguments that the registered function might take can be passed as additional arguments to this function, e.g. `Foil\run('func_name', $arg1, $arg2)`
+ - `Foil\engine()`
+ - `Foil\render()`
+ - `Foil\arraize()`
 
----
-
-# `entities()`
-
-```php
-/**
- * @param mixed $data Data to encode
- * @param string $strategy Target for escaping, can be 'html', 'js', 'css', 'attr'
- * @param string $encoding Character encoding used for escaping, default 'utf-8'
- *
- * @return mixed
- */
-
-function entities($data, $strategy = 'html', $encoding = 'utf-8')
-```
-
-This function allows to perform on any data, and outside of template files, the same routine Foil uses to escape content with automatic escape or with escape helpers.
-
-This function is capable to HTML-encode strings and arrays (even deeply nested) that contain strings. Any other data type will be returned unchanged.
-
-The routine applied is based on [AuraPhp/HTML](https://github.com/auraphp/Aura.Html) library.
-
-By default the given data is HTML-encoded using UTF-8, is possible to change the behavior using `$strategy` and `$encoding` arguments.
-
- - with `$strategy = 'js'` is possible to escape strings to be safely placed inside JavaScript scripts
- - with `$strategy = 'css'` is possible to escape strings to be safely placed inside CSS code
- - with `$strategy = 'attr'` is possible to escape strings to be safely inside HTML attributes. This is the only strategy that can be used passing an array,
-   where array keys are attribute names, e.g. `class` and array values are attribute values.
-
----
-
-# `decode()`
+## `Foil\engine()`
 
 ```php
-/**
-* @param mixed  $data Data to HTML-decode
-* @param string $encoding Character encoding used for escaping, default 'utf-8'
-*
-* @return mixed
-*/
-
-function decode($data, $encoding = 'utf-8')
+    /**
+     * @param  array        $options   Options: autoescape, default and allowed extensions, folders...
+     * @param  array        $providers Custom service provider classes
+     * @return \Foil\Engine
+     */
+    function engine(array $options = [], array $providers = [])
 ```
 
-This function is the counterpart for `entities()`. It is capable to HTML-decode strings and arrays (even deeply nested) that contain strings.
-Any other data type will be returned unchanged.
-
-This is 100% affordable ony if data were HTML encoded using same character encoding of decoding and, in case data comes from Foil `entities()` function (see above)
-if the strategy used was `'html'`. This is always true if data was escaped by Foil autoescape routine.
+Available since very first release, this function can be used to obtain an instance of Foil `Engine`
+that can be used to render templates and access to most of Foil features.
 
----
+`$options` argument is used to configure Foil behavior, see "Getting Started" section to know more.
 
-# `arraize()`
+In versions older than 0.6, when called more than once, this function used to return always the same instance of Foil Engine class.
 
-```php
-/**
-* @param  mixed $data         Data to convert
-* @param  bool  $escape       Should strings in data be HTML-encoded?
-* @param  array $transformers Transformers: full qualified class names, objects or callables
-* @param  bool  $tostring     Should all scalar items be casted to strings?
-* @return array
-*/
-
-function arraize($data = [], $escape = false, array $transformers = [], $tostring = false)
-```
+Starting from v0.6, it always return a "fresh" instance of Engine.
 
-This function allow to recursively convert to array any kind of data. It is a powerful tool, and there is an entire doc page that explain how it work and how to use it.
+Also note that in v0.6+, there's another method to obtain an instance of Foil Engine. It is the `engine()` method of the `Foil\Foil` class, whose instance
+can be obtained via `Foil\Foil::boot()` static method. See *"Getting Started / Engine"* to know more on the topic.
 
-See *"Data / Arraization"*.
 
----
-
-# `fire()`
+## `Foil\render()`
 
 ```php
-/**
- * @param string $event Event name
- */
-
-function fire($event)
+    /**
+     * @param  string $path    Full path or just name (requires folders option) for the template
+     * @param  array  $data    Template context
+     * @param  array  $options Options for the engine
+     * @param  array  $providers
+     * @return string
+     */
+    function render($path, array $data = [], array $options = [], array $providers = [])
 ```
 
-Internally Foil uses an events emit / subscribe system to implements most of its features.
-
-Foil uses the awesome [Evenement](https://github.com/igorw/evenement) package to implement it.
+Introduced in v0.6, this function can be used to quickly render a template with a given set of data.
 
-This function allows to emit a custom event, and to do that you only need to pass the event name as 1st argument.
+It very similar to obtain an instance of the engine via `engine()` function, and then call `render()` method on it.
 
-Additional arguments passed to function will be passed in same order to subscribing callbacks.
+First argument, `$path` may be the full absolute path of a template file, or just a template file name, in this latter case it requires a set of folders
+to be set using `$options`.
 
-This function can be used in API-aware extensions to emit custom events that can be subscribed by yourself or by 3rd parties.
 
----
-
-# `on()`
+## `Foil\arraize()`
 
 ```php
-/**
- * @param string   $event    Event name
- * @param callable $callback Callback called when event is emitted
- * @param boolean  $once     Should the callback run only once?
- */
-
-function on($event, callable $callback, $once = false)
+    /**
+     * @param  array $data
+     * @param  bool  $escape
+     * @param  array $transformers
+     * @param  bool  $toString
+     * @return mixed
+     */
+    function arraize($data = [], $escape = false, array $transformers = [], $toString = false)
 ```
 
-This function is part of the events emit / subscribe system used by Foil and allows to subscribe an event using a callback.
+This function allow to recursively convert kind of data to an array.
 
-This function can be used in API-aware extensions to subscribe events emitted by Foil (there are quite a lot), or by code you or a 3rd party wrote.
+It is a powerful tool, and there is an entire doc page that explain how it work and how to use it.
 
----
+See "Data / Arraization".
\ No newline at end of file
diff --git a/docs/INTEGRATE/OVERVIEW.md b/docs/INTEGRATE/OVERVIEW.md
index 92d8391..8301c82 100644
--- a/docs/INTEGRATE/OVERVIEW.md
+++ b/docs/INTEGRATE/OVERVIEW.md
@@ -10,9 +10,7 @@ title: "Overview"
 
 For the great majority of the use cases, the only Foil component your code needs to interact with is the Foil engine object.
 
-That object can be obtained using **`Foil\engine()`** function that may receives an array of options to configure Foil behavior. See *"Getting Started / Engine"* for more details.
-
-Best way to integrate Foil in your OOP project is to *inject* an instance of the engine into your application objects (controllers most of the times).
+So the best way to integrate Foil in your OOP project is to *inject* an instance of the engine into your application objects (controllers most of the times).
 
 This is an example:
 
@@ -35,6 +33,8 @@ class MyController
 }
 ```
 
+To know hot to obtain an instance of `Foil\Engine` to pass to controller, see *"Getting Started / Engine"*.
+
 In any class that has access to Foil engine object, you can make use of pretty all Foil features:
 
  - render templates (of course)
@@ -42,47 +42,12 @@ In any class that has access to Foil engine object, you can make use of pretty a
  - extend Foil features with extensions, functions and filters
  - pass data via Context API
 
-## Functional API Approach
-
-Object oriented design is not the only way to write PHP code.
-
-Functional programming is becoming increasingly popular nowadays, and even if surely PHP is not the best language to build functional code,
-it can be used for the scope, and more and more PHP packages and extensions are released for that purpose.
-
-Foil is **not** built using functional code, but is designed to be easily integrated in application that are.
-
-First of all note how you don't instantiate Foil engine using standard OOP approach (`$engine = new Foil\engine()`), but you use a function instead.
-
-Engine initialization is just one of the things that can be done using functions in Foil, in fact, there is an entire set of API functions (all under `Foil` namespace)
-that can be used to use all Foil features. (Full list available at *"Integrate Foil / API functions"*)
-
-Even better, using API functions is possible to do, very easily, things that using OOP would require a tight coupling between Foil and consumer code, and a deep knowledge of internal used Foil objects.
-
-So, is functional programming the preferred way to use Foil? Not really, thanks to the **Foil API object**.
-
-## Foil API object
-
-Foil API object is a class on which you call all the API functions, just like they are class methods.
-
-You will probably be surprised that the this sentence, that explain what API object is, contains almost same characters of the entire [class code](https://github.com/Giuseppe-Mazzapica/Foil/blob/master/src/API.php).
-
-If you followed the link to class code, you've seen that the only thing that API class do is to run namespaced functions that have the same name of any method you call on it.
-
-For example let's take a Foil API function we already seen, `Foil\engine()`:
-
-```php
-// functional API
-$engine = Foil\engine($options);
-
-// OOP API
-$api = new Foil\API();
-$engine = $api->engine($options);
-```
-
-The 2 ways to obtain Foil engine instance used in code above are equivalent and interchangeable.
+## Warning
 
-So, the net effect of using the API object is that the Foil API functions can be *ported* to OOP applications seamlessly.
+Version v0.6 completely changed how Foil internally works, **introducing backward compatibility breaks**, the main are:
 
-In fact, passing around API object with dependency injection is possible to write well designed and testable OOP code that integrates perfectly with Foil.
+ - most of the functions under `Foil` namespaces have been removed
+ - the `Foil\API` object has been removed (as a consequence the `APIAware` interface has been removed as well)
+ - `Foil\engine()` function that used to return same instance of Engine (~ singleton), now returns a *"fresh"* instance on any call.
 
-In the page *"Integrate Foil / API functions"* there is the complete list of available Foil API functions.
+These changes mostly affected the writing of custom extensions, in fact, Foil **core features and template methods are unchanged**.
diff --git a/docs/TEMPLATES/OVERVIEW.md b/docs/TEMPLATES/OVERVIEW.md
index 0205130..ac0d638 100644
--- a/docs/TEMPLATES/OVERVIEW.md
+++ b/docs/TEMPLATES/OVERVIEW.md
@@ -71,6 +71,12 @@ Same method can be used to check if a template file exists: it returns `false` i
 
 See  *"Getting Started / File Extensions"* to know more about default extension and  *"Getting Started / Folders"* to know more about folder IDs.
 
+### Search multiple templates
+
+Since version 0.6, is possible to pass to `find()` method, an array of template names. The first found among them will be returned.
+
+Note that `Engine::render()` method internally uses `find()`, so it is possible to pass an array of templates to `render()` method as well.
+
 
 ## Custom Template Classes
 
diff --git a/docs/TEMPLATES/SECTIONS-RENDERING.md b/docs/TEMPLATES/SECTIONS-RENDERING.md
new file mode 100644
index 0000000..94349b5
--- /dev/null
+++ b/docs/TEMPLATES/SECTIONS-RENDERING.md
@@ -0,0 +1,107 @@
+<!--
+currentMenu: "rendersections"
+currentSection: "Templates"
+title: "Sections Rendering"
+-->
+
+# Sections Rendering
+
+Sometimes may be desirable being able to render just one (or more) section of a template instead of
+just getting the rendering result of whole template.
+
+Since version 0.6, Foil allows to do that.
+
+(See *"Template Inheritance"* to know more about sections.)
+
+There are two Engine methods dedicated to this task:
+
+ - `renderSection()`
+ - `renderSections()`
+
+## `Engine::renderSection()`
+
+This method can be used to render one or more given sections of a template.
+
+For example, let's take a simple template like the following:
+
+
+```php
+<?php $this->section('who') ?>
+
+    <?= $this->username ?> is the current user.
+
+<?php $this->stop() ?>
+
+
+<?php $this->section('what') ?>
+
+    Current page is <?= $this->page ?>.
+
+<?php $this->stop() ?>
+```
+
+and let's assume it is saved in a `foo.php` template file.
+
+Doing:
+
+```php
+$data = ['username' => 'Giuseppe', 'page' => 'Sections Rendering' ];
+
+$who_section = $engine->renderSection('foo', 'who', $data);
+```
+
+`$who_section` will be equal to: **`"Giuseppe is the current user."`**.
+
+So the signature of `renderSection()` is:
+
+ - first argument is the template name
+ - second argument is the section name(s) to render
+ - third argument the data to pass to templates
+
+Passing as second argument a section name, like done above, it will return a string, that is the result of section rendering.
+
+Passing  as second argument an array of section names, the method returns an associative array where keys
+are section names and values are result of related section rendering.
+
+E.g. by doing:
+
+```php
+$data = ['username' => 'Giuseppe', 'page' => 'Sections Rendering' ];
+
+$sections = $engine->renderSection('foo', ['who', 'what'], $data);
+```
+
+the value of `$sections` will be:
+
+```php
+[
+    'who'  => 'Giuseppe is the current user.',
+    'what' => ' Current page is Sections Rendering.'
+]
+```
+
+## `Engine::renderSections()`
+
+This method is very similar to `renderSection()` when used passing an array of sections.
+
+However, it does not accepts any section name and returns an array of **all** the sections rendered.
+
+E.g., assuming same template as above, the code:
+
+```php
+$data = ['username' => 'Giuseppe', 'page' => 'Sections Rendering' ];
+
+$sections = $engine->renderSections('foo', $data);
+```
+
+the value of `$sections` will be:
+
+```php
+[
+    'who'  => 'Giuseppe is the current user.',
+    'what' => ' Current page is Sections Rendering.'
+]
+```
+
+So, the signature of `renderSections()` is the same of the `render()` method, but returns the array of
+rendered sections instead of the string that is the result of the whole template rendering.
\ No newline at end of file