- Finalizing the documentation before tagging 1.0 release

docs/02-control-structure-extends-section.md

@@ -0,0 +1,122 @@
+# Control structure - `extends` / `section`
+
+A nice feature of most robust templating engine is the ability to inherit from other view.
+
+Picea follows a similar train of tought, since it's also possible create a chain of inheritance 
+using `extends` which have definable parts you can declare using `section`. 
+
+## Basic `extends` (string $path)
+
+You must provide a valid `$path` from which the template will be inherited. 
+
+**[PICEA]** So, using this code:
+
+*path/base/layout.phtml*
+```html
+<!DOCTYPE html>
+<html>
+    <head>
+        {% section "head" %}
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>{{ title() }} - AnExampleApp</title>
+        {% section %}
+    </head>
+    <body>
+        <header id="header"">
+            {% section "header" %}{% view "path/base/navigation" %}{% endsection %}
+        </header>
+        <main id="main">{% section "main" %}{% endsection %}</main>
+        <footer id="footer">
+            {% section "footer" %}
+                &copy; Copyright {{ date('Y') }}
+            {% endsection %}
+        </footer>
+    </body>
+</html>
+```
+
+*path/home.phtml*
+```html
+{% extends "path/base/layout" %}
+
+{% title "Home page" %}
+
+{% section "main" %}
+    <h1>Welcome !</h1>
+    {# @TODO integrate our new blog engine below ! #}
+    <article>
+        This is our new blog ! We hope you are gonna enjoy your stay on our new platform !
+    </article>
+{% endsection %}
+```
+
+**[HTML]** Would render as such :
+```html
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>Home page - AnExampleApp</title>
+    </head>
+    <body>
+        <header id="header"">
+            <nav>
+                <a href="#home">Home</a>
+                <a href="#login">Login</a>
+            </nav>
+        </header>
+        <main id="main">
+            <h1>Welcome !</h1>
+            
+            <article>
+                This is our new blog ! We hope you are gonna enjoy your stay on our new platform !
+            </article>
+        </main>
+        <footer id="footer">
+            &copy; Copyright 2022
+        </footer>
+    </body>
+</html>
+```
+
+### Inherit an already extended view
+
+We could use the previous file `path/home` and generate, let's say, the same page, but without a navigation menu.
+
+**[PICEA]** So, using this code:
+
+*path/home-navless.phtml*
+```html
+{% extends "path/home" %}
+
+{% section "header" %}{% endsection %}
+```
+
+**[HTML]** Would render as such :
+```html
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>Home page - AnExampleApp</title>
+    </head>
+    <body>
+        <header id="header""></header>
+        <main id="main">
+            <h1>Welcome !</h1>
+            
+            <article>
+                This is our new blog ! We hope you are gonna enjoy your stay on our new platform !
+            </article>
+        </main>
+        <footer id="footer">
+            &copy; Copyright 2022
+        </footer>
+    </body>
+</html>
+```
+
+Notice that the `<header>` tag is now empty, since we've redeclared it in our navless view.