Update documentation for v0.6

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.

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.
+```
+

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.

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.

docs/FUNCTIONS/HTML-HELPERS.md

@@ -1,6 +1,6 @@
 <!--
 currentMenu: "htmlhelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "HTML & Form Helpers"
 -->
 

docs/FUNCTIONS/LINK-HELPERS.md

@@ -1,6 +1,6 @@
 <!--
 currentMenu: "linkhelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "Link Helpers"
 -->
 

docs/FUNCTIONS/LOOP-HELPERS.md

@@ -1,6 +1,6 @@
 <!--
 currentMenu: "loophelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "Loop Helpers"
 -->
 

docs/FUNCTIONS/URI-HELPERS.md

@@ -1,6 +1,6 @@
 <!--
 currentMenu: "urihelpers"
-currentSection: "Functions"
+currentSection: "Blocks & Helpers"
 title: "URI Helpers"
 -->
 

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.