added some french doc

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@20836 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/fr/tutorials/paginator-intro.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20835 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.paginator.intro">
+    <title>Introduction</title>
+
+    <para>
+        Imaginons que vous vouliez créer un blog, rempli de billets traitant d'un sujet.
+        Fort probablement, vous n'afficherez pas tous les billets sur une seule et unique page.
+        La solution est de selectionner une petite partie des billets et de l'afficher tout en
+        permettant à l'utilisateur de naviguer dans les différentes pages, un peu comme votre
+        moteur de recherche favori présente ses résultats.
+        <classname>Zend_Paginator</classname> est étudié pour répondre à ce besoin : diviser des
+        collections de données en parties logiques plus petites, le tout facilement et dupliquant
+        peu de code.
+    </para>
+
+    <para>
+        <classname>Zend_Paginator</classname> utilises des adaptateurs pour gérer les données
+        et fournir les pages disponibles. Nous verrons dans les sections suivantes comment
+        les manipuler et comment tirer partie du meilleur de <classname>Zend_Paginator</classname>.
+    </para>
+
+    <para>
+        Avant d'aller plus loin, nous allons regarder quelques exemples simples. Puis ensuite, nous
+        examinerons <classname>Zend_Paginator</classname> dans des cas réels simples, comme paginer
+        des résultats de base de données.
+    </para>
+
+    <para>
+        Cette introduction vous a permis de voir globalement le potentiel de
+        <classname>Zend_Paginator</classname>.
+        Pour démarrer, voyons quelques extraits de codes au travers d'exemples.
+    </para>
+</sect1>

documentation/manual/fr/tutorials/paginator-simple.xml

@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20720 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.paginator.simple">
+    <title>Exemples simples</title>
+
+    <para>
+        Dans ce premier exemple nous n'allons rien faire de magnifique, mais ça donnera une
+        bonne idée de l'utilité de <classname>Zend_Paginator</classname>.
+        Imaginons un tableau $data qui contient les chiffres de 1 à 100, nous voulons le
+        diviser en un nombre de pages. Nous pouvons utiliser la méthode statique
+        <methodname>factory()</methodname> de <classname>Zend_Paginator</classname> pour
+        récupérer un objet <classname>Zend_Paginator</classname> avec notre tableau à
+        l'intérieur.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+// Créer un tableau contenant les chiffres de 1 à 100
+$data = range(1, 100);
+
+// Récupérons un objet Paginator grâce à la fabrique.
+$paginator = Zend_Paginator::factory($data);
+]]></programlisting>
+
+    <para>
+        C'est presque terminé! La variable $paginator contient une référence vers l'objet
+        Paginator. Par défaut il servira 10 entités par page. Pour afficher les données sur
+        la page, il suffit d'itérer sur l'objet Paginator dans une boucle foreach. La page
+        en cours est par défaut la première, nous verrons comment choisir une page après.
+        Le code ci-après affiche une liste qui contient les chiffres de 1 à 10, ce sont
+        les chiffres de la première page.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+// Créer un tableau contenant les chiffres de 1 à 100
+$data = range(1, 100);
+
+// Récupérons un objet Paginator grâce à la fabrique.
+$paginator = Zend_Paginator::factory($data);
+
+?><ul><?php
+
+// Rendu de chaque donnée dans une liste
+foreach ($paginator as $item) {
+    echo '<li>' . $item . '</li>';
+}
+
+?></ul>
+]]></programlisting>
+
+    <para>
+        Essayons maintenant de récupérer les données de la deuxième page. Vous pouvez utiliser
+        la méthode <methodname>setCurrentPageNumber()</methodname> pour choisir la page.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+// Créer un tableau contenant les chiffres de 1 à 100
+$data = range(1, 100);
+
+// Récupérons un objet Paginator grâce à la fabrique.
+$paginator = Zend_Paginator::factory($data);
+
+// Selection de la page 2
+$paginator->setCurrentPageNumber(2);
+
+?><ul><?php
+
+// Rendu de chaque donnée dans une liste
+foreach ($paginator as $item) {
+    echo '<li>' . $item . '</li>';
+}
+
+?></ul>
+]]></programlisting>
+
+    <para>
+        Bien sûr ici, ce sont les chiffres 1 à 20 qui s'affichent.
+    </para>
+
+    <para>
+        Ces quelques exemples simplifiés sont loin de tout montrer sur
+        <classname>Zend_Paginator</classname>. Une application réelle ne lit pas ses données depuis
+        un tableau c'est pourquoi la section suivante montre comment utiliser le Paginator avec des
+        résultats d'une requête sql. Au besoin, familiarisez vous avec
+        <classname>Zend_Db_Select</classname>.
+    </para>
+
+    <para>
+        Dans l'exemple utilisant une base de données, nous chercherons des billets de blog appelés
+        'posts'. La table des 'posts' a quatre colonnes: id, title, body, date_created.
+        Voyons un exemple simple.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+// Créons un objet select qui récupère des billets et les range par date de création descendante
+$select = $db->select()->from('posts')->sort('date_created DESC');
+
+// Créons un paginateur pour cette requête
+$paginator = Zend_Paginator::factory($select);
+
+// Selection de la page 2
+$paginator->setCurrentPageNumber(2);
+
+?><ul><?php
+
+// Affichage du titre de chaque billet pour la page en cours
+foreach ($paginator as $item) {
+    echo '<li>' . $item->title . '</li>';
+}
+
+?></ul>
+]]></programlisting>
+
+    <para>
+        Comme vous le voyez, cet exemple n'est pas très différent du précédent. La seule différence
+        est <classname>Zend_Db_Select</classname> qui est passé à la méthode
+        <methodname>factory()</methodname> à la place d'un tableau.
+        Pour plus de détails notamment sur l'optimisation de la requête de l'objet select,
+        lisez le chapitre sur les adaptateurs DbSelect et DbTableSelect de la documentation de
+        <classname>Zend_Paginator</classname>.
+    </para>
+
+</sect1>

documentation/manual/fr/tutorials/paginator-together.xml

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20720 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.paginator.together">
+    <title>Assembler le tout</title>
+
+    <para>
+        Nous avons vu comment créer un objet Paginator, comment le rendre sur la page et aussi comment
+        rendre les éléments de navigation au travers des pages. Dans cette section nous allons voir
+        comment intégrer Paginator dans MVC.
+    </para>
+
+    <para>
+        Dans les exemples qui suivent, nous allons ignorer une bonne pratique qu'est d'utiliser une
+        couche de services (Service Layer) ceci dans le but de garder nos exemples concis et simples
+        à comprendre. Lorsque vous manipulerez bien les couches de services, vous devriez pouvoir
+        intégrer Paginator simplement et efficacement.
+    </para>
+
+    <para>
+        Partons du contrôleur. L'application d'exemple est simple, et nous allons tout loger dans
+        IndexController et IndexAction. Encore une fois ce choix est fait pour l'exemple, vous ne
+        devriez pas utiliser les contrôleurs de cette façon.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+class IndexController extends Zend_Controller_Action
+{
+    public function indexAction()
+    {
+        // Configuration du script de navigation. Voyez le tutoriel sur le script
+        // des éléments de contrôle de la pagination pour plus d'informations
+        Zend_View_Helper_PaginationControl::setDefaultViewPartial('controls.phtml');
+
+        // Cherchons une connection à une base depuis le registre
+        $db = Zend_Registry::get('db');
+
+        // Créons un objet select qui récupère des billets et les range par date de création descendante
+        $select = $db->select()->from('posts')->sort('date_created DESC');
+
+        // Créons un paginateur pour cette requête
+        $paginator = Zend_Paginator::factory($select);
+
+        // Nous lisons le numéro de page depuis la requête. Si le paramètre n'est pas précisé
+        // la valeur 1 sera utilisée par défaut
+        $paginator->setCurrentPageNumber($this->_getParam('page', 1));
+
+        // Assignons enfin l'objet Paginator à notre vue
+        $this->view->paginator = $paginator;
+    }
+}
+]]></programlisting>
+
+    <para>
+        Le script qui suit est index.phtml, le script de vue pour IndexController/indexAction par
+        défaut. Gardons celui-ci simple : il utilisera le type de défilement par défaut.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+<ul>
+<?php
+// Affiche le titre de chaque billet pour la page en cours
+foreach ($this->paginator as $item) {
+    echo '<li>' . $item->title . '</li>';
+}
+?>
+</ul>
+<?php echo $this->paginator; ?>
+]]></programlisting>
+
+    <para>
+        Naviguez maintenant dans votre projet pour voir Paginator en action. Nous n''avons vu
+        ici qu'une partie de l'utilisation et le manuel de référence vous en apprendra plus
+        sur les possibilités de Zend_Paginator.
+    </para>
+
+</sect1>

documentation/manual/fr/tutorials/plugins-conclusion.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20720 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.plugins.conclusion">
+    <title>Conclusion</title>
+
+    <para>
+        Comprendre le concept des plugins et des chemins de préfixes aide à la compréhension du
+        framework et de ses composants. Les plugins sont utilisés à de nombreux endroits:
+    </para>
+
+    <itemizedlist>
+        <listitem>
+            <para>
+                <classname>Zend_Application</classname>: ressources.
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                <classname>Zend_Controller_Action</classname>: aides d'action.
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                <classname>Zend_Feed_Reader</classname>: plugins.
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                <classname>Zend_Form</classname>: éléments, filtres, validateurs et décorateurs.
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                <classname>Zend_View</classname>: aides de vue.
+            </para>
+        </listitem>
+    </itemizedlist>
+
+    <para>
+        Encore beaucoup d'autres endroits. Prennez en main ce concept et vous pourrez alors
+        étendre de manière soutenue le Zend Framework.
+    </para>
+
+    <note>
+        <title>Remarque</title>
+
+        <para>
+            Notons que <classname>Zend_Controller_Front</classname> propose un système de plugin
+            mais il ne s'utilise pas de la même manière que décrit dans ce tutoriel. Les plugins
+            enregistrés auprès du contrôleur frontal doivent être instanciés directement et
+            enregistrés de manière individuelle. Ceci est dû au fait que le système de plugins
+            du contrôleur frontal date d'avant toute les possibilités d'extensions vues jusque ici
+            et des changements dans son coeur sont difficiles tout en gardant la compatibilité
+            avec les plugins déja existants.
+        </para>
+    </note>
+</sect1>

documentation/manual/fr/tutorials/plugins-intro.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20720 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.plugins.intro">
+    <title>Introduction</title>
+
+    <para>
+        Zend Framework utilise abondamment la notion de plugin. Les plugins permettent à la fois
+        l'extensibilité mais aussi la personnalisation du framework tout en gardant votre code
+        séparé de celui de Zend Framework.
+    </para>
+
+    <para>
+        Typiquement, les plugins dans Zend Framework fonctionnent comme suit:
+    </para>
+
+    <itemizedlist>
+        <listitem>
+            <para>
+                Les plugins sont des classes dont la définition va varier en fonction du composant
+                considéré. Par exemple vous aurez soit besoin d'implémenter une interface, soit
+                d'étendre une classe très souvent abstraite. Un plugin est donc une classe.
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                Les plugins relatifs aux même fonctionnalités vont partager un préfixe de classe.
+                Par exemple, si vous avez crée des aides de vue, il se peut que celle-ci partagent
+                le préfixe "<classname>Foo_View_Helper_</classname>".
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                Tout ce qui suit le préfixe est appelé <emphasis>nom du plugin</emphasis> ou
+                <emphasis>nom court</emphasis> (contrairement au "nom long", qui représente le
+                nom de la classe complet). Par exemple, si le préfixe du plugin est
+                "<classname>Foo_View_Helper_</classname>", et le nom de la classe
+                "<classname>Foo_View_Helper_Bar</classname>", le nom du plugin est
+                "<classname>Bar</classname>".
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                Les noms de plugins sont sensibles à la casse à l'exception de la première
+                lettre qui peut être soit en majuscules soit en minuscules. Dans nos
+                exemples, nous aurions pu utiliser "bar" ou "Bar" de manière équivalente.
+            </para>
+        </listitem>
+    </itemizedlist>
+
+    <para>
+        Voyons maintenant comment utiliser des plugins.
+    </para>
+</sect1>

documentation/manual/fr/tutorials/plugins-usage.xml

@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20720 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.plugins.usage">
+    <title>Utiliser des Plugins</title>
+
+    <para>
+        Les composants utilisant des plugins se servent de
+        <classname>Zend_Loader_PluginLoader</classname> pour fonctionner. Cette classe vous
+        propose d'enregistrer des "chemins de préfixes". Le composant va alors utiliser la méthode
+        <methodname>load()</methodname> du PluginLoader en lui passant le nom court du plugin
+        à charger. Le PluginLoader va ensuite tester chaque chemin de préfixe pour trouver une
+        classe qui corresponde au nom court passé. Les chemins de préfixes sont testés en ordre
+        LIFO (last in, first out) et il trouvera d'abord les chemins de préfixes enregistrés
+        en dernier, ce qui permet de surcharger des plugins existants.
+    </para>
+
+    <para>
+        Voici quelques exemples pour éclaircir tout ça.
+    </para>
+
+    <example id="learning.plugins.usage.basic">
+        <title>Exemple de base: ajouter un chemin de préfixes simple</title>
+
+        <para>
+            Dans cet exemple, nous supposerons que des validateurs ont été écrits et enregistrés
+            sous <filename>foo/plugins/validators/</filename>, puis que toutes ces classes
+            partagent le même préfixe "Foo_Validate_"; ces deux informations forment le
+            "chemin de préfixes". Imaginons maintenant deux validateurs, un s'appelle "Even" (impaire)
+            il validera donc un chiffre impaire, et l'autre "Dozens"(multiples) qui vérifiera
+            un chiffre multiple de 12. L'arbre ressemble à ceci:
+        </para>
+
+        <programlisting language="text"><![CDATA[
+foo/
+|-- plugins/
+|   |-- validators/
+|   |   |-- Even.php
+|   |   |-- Dozens.php
+]]></programlisting>
+
+        <para>
+            Maintenant, nous allons informer un <classname>Zend_Form_Element</classname> de ce
+            chemin de préfixes. La méthode <methodname>addPrefixPath()</methodname> de
+            <classname>Zend_Form_Element</classname> prend comme troisième paramètre le type de
+            plugin pour lequel on spécifie un chemin, dans notre cas il s'agit d'un plugin de
+            validation , "validate".
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$element->addPrefixPath('Foo_Validate', 'foo/plugins/validators/', 'validate');
+]]></programlisting>
+
+        <para>
+            Dès lors il devient possible de passer à l'élément le nom court du validateur. Dans l'exemple
+            qui suit, nous mixons des validateurs standards ("NotEmpty", "Int") et personnalisés
+            ("Even", "Dozens"):
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$element->addValidator('NotEmpty')
+        ->addValidator('Int')
+        ->addValidator('Even')
+        ->addValidator('Dozens');
+]]></programlisting>
+
+        <para>
+            Lorsque l'élément devra utiliser la validation, il appellera le plugin via le
+            PluginLoader. Les deux premiers validateurs vont correspondre à
+            <classname>Zend_Validate_NotEmpty</classname> et
+            <classname>Zend_Validate_Int</classname>, puis les deux suivants à
+            <classname>Foo_Validate_Even</classname> et <classname>Foo_Validate_Dozens</classname>,
+            respectivement.
+        </para>
+    </example>
+
+    <note>
+        <title>Que se passe-t-il si un plugin n'est pas trouvé?</title>
+
+        <para>
+            Que se passe-t-il si un plugin est demandé mais que le PluginLoader ne peut pas trouver
+            de classe qui y corresponde? Dans notre exemple ci-dessus, la question devient
+            "que se passe-t-il si j'enregistre le validateur "Bar" dans l'élément?"
+        </para>
+
+        <para>
+            Le PluginLoader va chercher dans tous les chemins de prefixes pour trouver un fichier qui
+            corresponde au nom du plugin. Si le fichier n'est pas trouvé, il passe au prochain
+            chemin.
+        </para>
+
+        <para>
+            Une fois que la pile de chemins est épuisée, si aucun fichier n'a été trouvé, il enverra
+            une <exceptionname>Zend_Loader_PluginLoader_Exception</exceptionname>.
+        </para>
+    </note>
+
+    <example id="learning.plugins.usage.override">
+        <title>Exemple intermédiaire: Surcharger un plugin existant</title>
+
+        <para>
+            Une des forces du PluginLoader est qu'il utilise une pile LIFO, ceci vous permet
+            de surcharger des plugins existants par les votres stockés dans des chemins
+            différents en enregistrant ce chemin dans la pile.
+        </para>
+
+        <para>
+            Par exemple, considérons <classname>Zend_View_Helper_FormButton</classname> (les aides
+            de vue sont une forme de plugin). Cette aide de vue accepte trois paramètres, un nom
+            DOM, une valeur (utilisée comme libéllé de bouton), et un tableau optionnel d'options.
+            L'aide génère du HTML concernant un élément de formulaire.
+        </para>
+
+        <para>
+            Imaginons que vous vouliez que cette aide génère un vrai bouton HTML
+            <constant>button</constant>; vous ne voulez pas que cette aide génère un identifiant DOM
+            mais plutôt une classe CSS; et que vous ne souhaitez pas utiliser d'options
+            supplémentaires. Vous pourriez faire cela de plusieurs manières. Dans tous les cas vous
+            allez créer votre aide de vue en y écrivant le comportement mais comment allez-vous
+            nommer votre aide de vue et comment l'instancier?
+        </para>
+
+        <para>
+            Nous allons d'abord nommer notre classe avec un nom unique non existant,
+            <classname>Foo_View_Helper_CssButton</classname>, ceci donne immédiatement un nom de plugin:
+            "CssButton". Pourquoi pas, mais ceci pose quelques problèmes: si vous utilisiez déja
+            "FormButton" dans votre code vous allez devoir changer le nom partout, et si un autre
+            développeur rejoind vos rangs, il pourrait être troublé par "CssButton" et intuitivement
+            penser à l'aide standard "FormButton".
+        </para>
+
+        <para>
+            Le mieux reste encore de nommer notre aide de vue "Button", en lui donnant comme nom de classe
+            <classname>Foo_View_Helper_Button</classname>. Nous enregistrons aussi le chemin de préfixes
+            dans la vue:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Zend_View::addHelperPath() utilise PluginLoader; attention par contre
+// sa signature inverse les arguments par rapport à PluginLoader, ceci car il
+// propose une valeur par défaut au préfixe : "Zend_View_Helper"
+//
+// La ligne ci-dessous suppose que la classe soit logée dans 'foo/view/helpers/'.
+$view->addHelperPath('foo/view/helpers', 'Foo_View_Helper');
+]]></programlisting>
+
+        <para>
+            A partir de ce moment, utiliser l'aide "Button" mènera vers votre propre classe
+            <classname>Foo_View_Helper_Button</classname>!
+        </para>
+    </example>
+</sect1>