Add french documentation.

1 files changed, 248 insertions, 0 deletions

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
new file mode 100644
index 0000000..610fff1
--- /dev/null
+++ b/Documentation/Fr/Index.xyl
@@ -0,0 +1,248 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<overlay xmlns="http://hoa-project.net/xyl/xylophone">
+<yield id="chapter">
+
+  <p>Les <strong>vues</strong> sont des systèmes <strong>complexes</strong> et
+  très <strong>variés</strong>. <code>Hoa\View</code> propose une interface
+  capable de répondre à la majorité des besoins à travers un mécanisme
+  <strong>souple</strong> et <strong>extensible</strong>.</p>
+
+  <h2 id="Table_des_matieres">Table des matières</h2>
+
+  <tableofcontents id="main-toc" />
+
+  <h2 id="Introduction" for="main-toc">Introduction</h2>
+
+  <p>Une <strong>vue</strong> est un mécanisme permettant d'agencer
+  graphiquement des <strong>données</strong> à l'utilisateur. Il existe
+  plusieurs approches, assez <strong>différentes</strong> les unes des autres et
+  qui peuvent parfois être très <strong>complexes</strong>. La bibliothèque
+  <code>Hoa\View</code> propose une seule interface qui regroupe
+  l'<strong>essentiel</strong> des fonctionnalités afin de pouvoir intégrer une
+  vue à n'importe quelle autre bibliothèque.</p>
+
+  <h2 id="Une_seule_interface" for="main-toc">Une seule interface</h2>
+
+  <p>Le mécanisme principal d'une vue est presque toujours le même :</p>
+  <ul>
+    <li>nous avons des <strong>données</strong> que nous voulons
+    <strong>agencer</strong> et <strong>afficher</strong> à l'utilisateur ;</li>
+    <li>une vue utilise aussi des <strong>ressources</strong> qu'il faut être
+    capable de localiser ;</li>
+    <li>enfin, le <strong>rendu</strong> est le mécanisme permettant d'obtenir
+    un résultat (données agencées, ressources liées etc.).</li>
+  </ul>
+  <p>Nous arrivons à un total de quatre notions : des données, un « agenceur »,
+  un routeur et un canal de sortie dans lequel écrire le résultat.</p>
+  <p>La bibliothèque <code>Hoa\View</code> ne propose qu'une seule
+  <strong>interface</strong> : <code>Hoa\View\Viewable</code>. Cette dernière
+  définit une méthode pour chacune des quatres notions précédentes :</p>
+  <ul>
+    <li><code>getData</code>, les données à agencer ;</li>
+    <li><code>getRouter</code>, pour localiser des ressources et autres
+    documents.</li>
+    <li><code>render</code>, notre « agenceur », ce qui va déclencher le
+    rendu ;</li>
+    <li><code>getOutputStream</code>, le flux dans lequel écrire la vue.</li>
+  </ul>
+  <p>Et c'est tout ! Pour être plus précis, voici les retours attendus pour
+  chacune de ces méthodes :</p>
+  <ul>
+    <li><code>getData</code> doit préférablement retourner un objet
+    <code>Hoa\Core\Data</code> (voir <a href="@lh:chapter=Core">la bibliothèque
+    <code>Hoa\Core</code></a>) ; il est néanmoins possible de retourner un objet
+    quelconque ;</li>
+    <li><code>getRouter</code> doit retourner un routeur de type
+    <code>Hoa\Router</code> (voir <a href="@lh:chapter=Router">la bibliothèque
+    <code>Hoa\Router</code></a>) ;</li>
+    <li><code>render</code> ne doit rien retourner ;</li>
+    <li><code>getOutputStream</code> doit retourner un flux implémentant
+    l'interface <code>Hoa\Stream\IStream\Out</code> (voir
+    <a href="@lh:chapter=Stream">la bibliothèque <code>Hoa\Stream</code></a>) ;
+    ça peut être un fichier, une chaîne de caractères, une réponse HTTP …</li>
+  </ul>
+  <p>Même si cette approche peut sembler simpliste au premier abord, cette
+  interface couvre l'ensemble des besoins, et vous permet d'écrire la vue que
+  vous désirez avec vos propres outils ou avec des outils déjà existants.</p>
+
+  <h2 id="Exemple" for="main-toc">Exemple</h2>
+
+  <p><a href="@lh:chapter=Xyl">La bibliothèque <code>Hoa\Xyl</code></a> 
+  utilise <code>Hoa\View\Viewable</code>, mais elle est un peu complexe
+  pour servir de premier exemple (ce qui ne vous empêche pas d'aller y
+  jeter un œil !). C'est pourquoi nous allons donner un exemple plus simple et
+  plus basique.</p>
+  <p>Commençons par définir ce que nous voulons : Nous souhaitons mettre en
+  place un mécanisme de vues et de <strong>sous-vues</strong> répondant aux
+  caractéristiques suivantes :</p>
+  <ul>
+    <li>une vue principale pilote le rendu ;</li>
+    <li>cette vue principale peut inclure des <strong>sous-vues</strong> ;</li>
+    <li>les données seront <strong>isolées</strong>, ce qui veut dire qu'une vue
+    n'aura pas accès aux données d'une autre vue ;</li>
+    <li>nos données seront basées sur
+    <a href="http://php.net/reserved.classes">la classe <code>StdClass</code></a>
+    pour plus de simplicité.</li>
+  </ul>
+  <p>Commençons par écrire la classe <code>SuperView</code> :</p>
+  <pre data-line="49"><code class="language-php">from('Hoa')
+-> import('View.~able')
+-> import('Http.Response')
+-> import('Router.Http');
+
+class SuperView implements Hoa\View\Viewable {
+
+    protected $_in     = null;
+    protected $_out    = null;
+    protected $_data   = null;
+    protected $_router = null;
+
+    public function __construct (                        $in,
+                                  Hoa\Stream\IStream\Out $out,
+                                  Hoa\Router             $router = null,
+                                  StdClass               $data   = null ) {
+
+        if(null === $data)
+            $data = new StdClass();
+
+        $this->_in     = $in;
+        $this->_out    = $out;
+        $this->_data   = $data;
+        $this->_router = $router;
+
+        return;
+    }
+
+    public function getOutputStream ( ) {
+
+        return $this->_out;
+    }
+
+    public function getData ( ) {
+
+        return $this->_data;
+    }
+
+    public function render ( ) {
+
+        $data   = $this->getData();
+        $router = $this->getRouter();
+
+        ob_start();
+        require $this->_in;
+        $content = ob_get_contents();
+        ob_end_clean();
+
+        $this->getOutputStream()->writeAll($content);
+
+        return;
+    }
+
+    public function getRouter ( ) {
+
+        return $this->_router;
+    }
+}</code></pre>
+  <p>Très classique. Notre constructeur demande un fichier à lire, un flux de
+  sortie, un routeur qui est optionel, tout comme des données. Nous retrouvons
+  nos méthodes <code>getOutputStream</code>, <code>getData</code>,
+  <code>render</code> et <code>getRouter</code>. La méthode <code>render</code>
+  va inclure le fichier <code class="language-php">$in</code> en ayant
+  préalablement mis à sa disposition deux variables (en plus de
+  <code class="language-php">$this</code>), à savoir
+  <code class="language-php">$data</code> et
+  <code class="language-php">$router</code>, pour lui faciliter l'écriture.
+  Enfin, la ligne 49 utilise le flux de sortie pour écrire les données.</p>
+  <p>Testons en écrivant un fichier <code>Test.php</code> :</p>
+  <pre data-line="9,17"><code class="language-php">// Output.
+$output = new Hoa\Http\Response();
+
+// Router.
+$router = new Hoa\Router\Http();
+$router->get('a', '/Foo\.html');
+
+// View.
+$superview   = new SuperView('Out.phtml', $output, $router);
+
+// Data.
+$data        = $superview->getData();
+$data->title = 'foobar';
+$data->foo   = (object) array('bar' => 'baz', 'qux' => 'hop');
+
+// Render.
+$superview->render();</code></pre>
+  <p>Et enfin, écrivons notre fichier <code>Out.phtml</code> :</p>
+  <pre><code class="language-markup">&amp;lt;h1>&amp;lt;?php echo $data->title; ?>&amp;lt;/h1></code></pre>
+  <p>Observons maintenant le résultat de l'exécution de
+  <code>Test.php</code> :</p>
+  <pre><code class="language-shell">$ php Test.php
+&amp;lt;h1>foobar&amp;lt;/h1></code></pre>
+  <p>Excellent. Maintenant ajoutons le moyen de créer des
+  <strong>sous-vues</strong> avec la méthode <code>import</code> par exemple.
+  Ainsi, nous ajoutons dans la classe <code>SuperView</code> :</p>
+  <pre><code class="language-php">    public function import ( $in, $data = null ) {
+
+        $new = new static(
+            $in,
+            $this->getOutputStream(),
+            $this->getRouter(),
+            $data
+        );
+        $new->render();
+
+        return;
+    }</code></pre>
+  <p>Nous utilisons le mot-clé <code>static</code> pour faire une référence
+  statique à la classe elle-même ou à ses enfants (voir
+  <a href="http://php.net/lsb"><em lang="en">Late Static Bindings</em></a>).</p>
+  <p>Nous voyons apparaitre nos vues imbriquées. Modifions
+  <code>Out.phtml</code> pour qu'il utilise <code>Sub.phtml</code> qui sera une
+  nouvelle vue. À cette sous-vue, nous ne donnerons qu'une partie des données
+  (uniquement <code>foo</code>) :</p>
+  <pre><code class="language-markup">&amp;lt;h1>&amp;lt;?php echo $data->title; ?>&amp;lt;/h1>
+
+&amp;lt;?php $this->import('Sub.phtml', $data->foo); ?></code></pre>
+  <p>Et dans <code>Sub.phtml</code>, nous pouvons utiliser nos données comme bon
+  nous semble. En bonus, nous allons utiliser le routeur pour créer un lien
+  (pour rappel, notre routeur définissait la règle <code>a</code> vers
+  <code>/foo.html</code>). Ainsi :</p>
+  <pre><code class="language-markup">&amp;lt;p>Sub-view! This is a link:
+   &amp;lt;a href="&amp;lt;?php echo $router->unroute('a'); ?>">click click&amp;lt;/a>!&amp;lt;/p>
+
+&amp;lt;ul>
+&amp;lt;?php foreach($data as $key => $value): ?>
+    &amp;lt;li>&amp;lt;?php echo $key, ' => ', $value; ?>&amp;lt;/li>
+&amp;lt;?php endforeach; ?>
+&amp;lt;/ul></code></pre>
+  <p>Exécutons à nouveau <code>Test.php</code> pour voir le résultat :</p>
+  <pre><code class="language-shell">$ php Test.php
+&amp;lt;h1>foobar&amp;lt;/h1>
+
+&amp;lt;p>Sub-view! This is a link:
+   &amp;lt;a href="/Foo.html">click click&amp;lt;/a>!&amp;lt;/p>
+
+&amp;lt;ul>
+    &amp;lt;li>bar => baz&amp;lt;/li>
+    &amp;lt;li>qux => hop&amp;lt;/li>
+&amp;lt;/ul></code></pre>
+  <p>Notre sous-vue est en place, avec notre lien et nos données isolées (nous
+  itérons sur toutes les données sans pour autant avoir les données de
+  <code>title</code>, uniquement celles de <code>foo</code>).</p>
+  <p>Cette classe <code>SuperView</code> est très basique mais les
+  <strong>performances</strong> sont intéressantes car le résultat du rendu est
+  envoyé <strong>directement</strong> dans le flux de sortie, sans jamais
+  manipuler de grosse chaîne de caractères. Cela devient particulièrement
+  intéressant quand nous manipulons beaucoup de sous-vues imbriquées par
+  exemple.</p>
+
+  <h2 id="Conclusion" for="main-toc">Conclusion</h2>
+
+  <p>La bibliothèque <code>Hoa\View</code> ne définit qu'une seule
+  <strong>interface</strong> avec quatre <strong>méthodes</strong>. À l'usage,
+  nous nous rendons compte que ces méthodes sont <strong>suffisantes</strong>
+  pour décrire et manipuler plusieurs systèmes de vue qui peuvent être très
+  <strong>complexes</strong>.</p>
+
+</yield>
+</overlay>