aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorIvan Enderlin <ivan.enderlin@hoa-project.net>2013-04-11 21:33:26 +0200
committerIvan Enderlin <ivan.enderlin@hoa-project.net>2013-04-11 21:33:26 +0200
commit979e0ab412f9a825490ff143a46dcbd50310ca8a (patch)
tree20f6d0234dc962f4d3fac98304ccf1e3a69ea7df
parentddd18c1696326a5225f23d9464f4ea962cd2c962 (diff)
downloadView-979e0ab412f9a825490ff143a46dcbd50310ca8a.zip
View-979e0ab412f9a825490ff143a46dcbd50310ca8a.tar.gz
View-979e0ab412f9a825490ff143a46dcbd50310ca8a.tar.bz2
Add french documentation.
-rw-r--r--Documentation/Fr/Index.xyl248
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>