- Finalizing the documentation before tagging 1.0 release

docs/02-control-structure-view-include-block.md

@@ -0,0 +1,112 @@
+# Control structure - View (or `include`) / Block
+
+There is three ways to include other views into your current view `{% view %} / {% include %}` or 
+using `{% block %}{% endblock %}`.
+
+The order of loading depends on the order given within your directory configuration; the first file found from it 
+will be used. 
+
+## Inline `view` (string $path, array|null $arguments = null)
+
+You must provide a valid `$path` from which the template will be loaded. If no `$arguments` are provided, defined 
+variables from the caller's scope will be given (from `get_defined_vars()`).
+
+**[PICEA]** So, using this code:
+
+*path/base/nav.phtml*
+```html
+<nav>
+    {% foreach $navigation as $index => $navItem %}
+        {% view "path/base/nav-item", [ 'item' => $navItem, 'index' => $index] %}
+    {% endforeach %}
+</nav>
+```
+
+*path/base/nav-item.phtml*
+```html
+<a href="{{ $item->anchor }}" tabindex="{{ $index }}">{{ $item->name }}"</a>
+```
+
+**[HTML]** Could render such as :
+```html
+<nav>
+    <a href="#top">Top</a>
+    <a href="#bottom">Bottom</a>
+    <a href="#left">Left</a>
+    <a href="#right">Right</a>
+</nav>
+```
+
+## `include` (string $path) content from external file
+
+Whenever you need to `include` a raw file from one of your view directories
+
+## Reusable `block` (string $path, ...$arguments) / `endblock`
+
+A better way to achieve this behaviour could be to create a `block` which you can define as needed.
+
+**[PICEA]** So, using this code:
+
+*path/base/nav.phtml*
+```html
+<nav>
+    {% foreach $navigation as $index => $navItem %}
+        {% block "path/base/nav-item-block", $navItem->name, $navItem->anchor, $index %}{% endblock %}
+    {% endforeach %}
+</nav>
+```
+
+*path/base/nav-item-block.phtml*
+```html
+{% arguments string $name, string $anchor, int $index = 0 %}
+
+<a href="{{ $anchor }}" tabindex="{{ $index }}">{{ $name }}"</a>
+```
+
+**[HTML]** Would render the same as the `view` example :
+```html
+<nav>
+    <a href="#top">Top</a>
+    <a href="#bottom">Bottom</a>
+    <a href="#left">Left</a>
+    <a href="#right">Right</a>
+</nav>
+```
+
+### Extending a `block` using `define` and `slot`
+
+You might need to define some custom content inside of a `block`.
+
+You can do so by using `define` and `slot`.
+
+**[PICEA]** So, using this code:
+
+*path/base/nav.phtml*
+```html
+<nav>
+    {% foreach $navigation as $index => $navItem %}
+        {% block "path/base/nav-item-block", $navItem->name, $navItem->anchor, $index %}
+            {% slot "attributes" %} class="nav-item" href="{{ $anchor }}" {% endslot %}
+        {% endblock %}
+    {% endforeach %}
+</nav>
+```
+
+*path/base/nav-item-block.phtml*
+```html
+{% arguments string $name, string $anchor, int $index = 0 %}
+
+{% define slot %}
+
+<a {% slot "attributes" %}href="{{ $anchor }}" tabindex="{{ $index }}"{% endslot %}>{{ $name }}"</a>
+```
+
+**[HTML]** Would render the same as the `view` example :
+```html
+<nav>
+    <a href="#top">Top</a>
+    <a href="#bottom">Bottom</a>
+    <a href="#left">Left</a>
+    <a href="#right">Right</a>
+</nav>
+```