repo_zf1/documentation/manual/fr/module_specs/Zend_Paginator-Usage.xml

<!-- EN-Revision: 13836 -->
<sect1 id="zend.paginator.usage">
    <title>Utilisation</title>

    <sect2 id="zend.paginator.usage.paginating">
        <title>Paginer des collections de données</title>

        <para>Afin de pouvoir paginer des éléments, <classname>Zend_Paginator</classname> doit posséder une manière générique
        d'accéder aux sources de données. De ce fait, tous les accès aux données se font via des adaptateurs de sources.
        Plusieurs adaptateurs existent par défaut :</para>

        <table id="zend.paginator.usage.paginating.adapters">
            <title>Adaptateurs pour <classname>Zend_Paginator</classname></title>

            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Adaptateur</entry>

                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><code>Array</code></entry>

                        <entry>Utilise un tableau PHP</entry>
                    </row>

                    <row>
                        <entry><code>DbSelect</code></entry>

                        <entry>Utilise une instance de <link linkend="zend.db.select"><classname>Zend_Db_Select</classname></link>
                        qui retourne un tableau</entry>
                    </row>

                    <row>
                        <entry><code>DbTableSelect</code></entry>

                        <entry>Utilise une instance <link
                        linkend="zend.db.table.fetch-all"><classname>Zend_Db_Table_Select</classname></link>, qui retournera une
                        instance de <classname>Zend_Db_Table_Rowset_Abstract</classname>. Ceci fournit aussi des informations
                        supplémentaires sur le jeu de résultats, tel que les noms de colonne.</entry>
                    </row>

                    <row>
                        <entry><code>Iterator</code></entry>

                        <entry>Utilise une instance implémentant <ulink
                        url="http://www.php.net/~helly/php/ext/spl/interfaceIterator.html"><code>Iterator</code></ulink></entry>
                    </row>

                    <row>
                        <entry><code>Null</code></entry>

                        <entry>N'utilise pas <classname>Zend_Paginator</classname> pour la pagination. En revanche, les options et
                        capacités de contrôle de la pagination restent disponibles.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <para>Plutôt que de sélectionner chaque ligne correspondant à une requête fournie, les adaptateurs
            <code>DbSelect</code> et <code>DbTableSelect</code> récupèrent seulement la quantité de données nécessaire
            pour l'affichage de la page courante.</para>

            <para>A cause de ceci, une seconde requête est générée dynamiquement pour déterminer le nombre total de
            lignes correspondantes. Cependant, il est possible de directement fournir un nombre ou un requête de
            dénombrement vous-même. Regardez la méthode <code>setRowCount()</code> de l'adaptateur <code>DbSelect</code>
            pour de plus amples informations.</para>
        </note>

        <para>Pour créer une instance de <classname>Zend_Paginator</classname>, vous devez spécifier un adaptateur à son
        constructeur:</para>

        <para><programlisting role="php"><![CDATA[
$paginator = new Zend_Paginator(new Zend_Paginator_Adapter_Array($array));
]]></programlisting></para>

        <para>Pour une meilleure intégration, vous pouvez utiliser la fabrique <code>factory()</code>:</para>

        <para><programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($array);
]]></programlisting></para>

        <note>
            <para>Pour l'adaptateur <code>Null</code>, il faut spécifier un chiffre à son constructeur en lieu et place
            de la collection de données.</para>
        </note>

        <para>Bien que l'instance soit techniquement utilisable dans l'état, dans votre contrôleur d'action vous devrez
        informer le paginateur du numéro de page demandé par l'utilisateur. Ceci lui permet d'avancer à travers les
        données paginées.</para>

        <para><programlisting role="php"><![CDATA[
$paginator->setCurrentPageNumber($page);
]]></programlisting></para>

        <para>La manière la plus simple de suivre et scruter cette valeur est via l'URL. Nous recommandons l'utilisation
        d'un routeur compatible avec <classname>Zend_Controller_Router_Interface</classname>, mais ceci n'est pas
        nécessaire.</para>

        <para>Voici une route que vous pourriez définir dans un fichier de configuration INI:</para>

        <para><programlisting role="php"><![CDATA[
routes.example.route = articles/:articleName/:page
routes.example.defaults.controller = articles
routes.example.defaults.action = view
routes.example.defaults.page = 1
routes.example.reqs.articleName = \w+
routes.example.reqs.page = \d+
]]></programlisting></para>

        <para>Avec une telle route (et en utilisant les composants MVC de Zend Framework), vous pourriez spécifier le
        numéro de la page de cette manière :</para>

        <para><programlisting role="php"><![CDATA[
$paginator->setCurrentPageNumber($this->_getParam('page'));
]]></programlisting></para>

        <para>Il y a d'autres options disponibles, voyez <link linkend="zend.paginator.configuration">la
        configuration</link> pour plus de détails.</para>

        <para>Enfin, il faut passer l'instance du paginateur à votre vue. Si vous utilisez <classname>Zend_View</classname> avec
        l'aide d'action <code>ViewRenderer</code>, ceci fonctionnera :</para>

        <para><programlisting role="php"><![CDATA[
$this->view->paginator = $paginator;
]]></programlisting></para>
    </sect2>

    <sect2 id="zend.paginator.rendering">
        <title>Rendre des pages avec les scripts de vue</title>

        <para>Le script de vue va être utilisé pour rendre les éléments de la page (bien sûr si
        <classname>Zend_Paginator</classname> est utilisé à cet effet), et pour afficher les éléments relatifs au contrôle de la
        pagination.</para>

        <para>Comme <classname>Zend_Paginator</classname> implémente l'interface SPL <ulink
        url="http://www.php.net/~helly/php/ext/spl/interfaceIteratorAggregate.html"><code>IteratorAggregate</code></ulink>,
        boucler sur les éléments et les afficher est très simple.</para>

        <para><programlisting role="php"><![CDATA[
<html>
<body>
<h1>Example</h1>
<?php if (count($this->paginator)): ?>
<ul>
<?php foreach ($this->paginator as $item): ?>
  <li><?= $item; ?></li>
<?php endforeach; ?>
</ul>
<?php endif; ?>

<?= $this->paginationControl($this->paginator, 'Sliding', 'my_pagination_control.phtml'); ?>
</body>
</html>
]]></programlisting></para>

        <para>Notez l'appel à l'aide de vue en fin de script. <code>PaginationControl</code> accepte jusqu'à quatre
        paramètres : l'instance du paginateur, un type de défilement (optionnel), un partial de vue (optionnel) et un
        tableau de paramètres additionnels.</para>

        <para>Les second et troisième paramètres sont très importants. Alors que le partial est utiliser pour déterminer
        comment <emphasis>présenter</emphasis> les données, le type de défilement définira la manière dont ils se
        <emphasis>comportent</emphasis>. Disons que le partial ressemble à un contrôle de recherche, comme ce qui suit
        :</para>

        <para><inlinegraphic align="center" fileref="figures/zend.paginator.usage.rendering.control.png" format="PNG"
        valign="middle" /></para>

        <para>Que se passe-t-il lorsque l'utilisateur clique sur le lien "next" quelques fois? Plusieurs choses peuvent
        arriver. Le numéro de la page courante pourrait rester au milieu (comme c'est le cas sur Yahoo!), ou il pourrait
        aussi bien avancer à la fin de la fourchette des pages et apparaître encore à gauche lorsque l'utilisateur
        clique alors sur "next". Le nombre de pages pourrait alors s'étendre ou se comprimer alors que l'utilisateur
        avance ("scroll") à travers (comme chez Google).</para>

        <para>Il existe 4 types de défilement intégrés dans Zend Framework :</para>

        <table id="zend.paginator.usage.rendering.scrolling-styles">
            <title>Types de défilement pour <classname>Zend_Paginator</classname></title>

            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Type de défilement</entry>

                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>All</entry>

                        <entry>Retourne toutes les pages. Très pratique lorsqu'il y a peu de pages totales.</entry>
                    </row>

                    <row>
                        <entry>Elastic</entry>

                        <entry>Un défilement de type Google qui s'étend et se contracte au fur et à mesure que
                        l'utilisateur avance dans les pages de résultats.</entry>
                    </row>

                    <row>
                        <entry>Jumping</entry>

                        <entry>Alors que l'utilisateur défile, le nombre de pages avance à la fin d'une échelle donnée,
                        puis recommence au début de l'échelle suivante.</entry>
                    </row>

                    <row>
                        <entry>Sliding</entry>

                        <entry>Un défilement de type Yahoo! qui positionne la page en cours au centre d'une échelle de
                        pages, le plus justement et près possible. Ce type de défilement est le type par défaut.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>Le quatrième et dernier paramètre est réservé pour un tableau associatif optionnel de variables
        supplémentaires que vous voulez rendre disponible dans vos partiels de vues (disponible via <code>$this</code>).
        Par exemple, ces valeurs permettent d'inclure des paramètres d'URL supplémentaires pour les liens de
        pagination.</para>

        <para>En spécifiant le partial de vue par défaut, le défilement et l'instance de vue, vous pouvez alors vous
        affranchir totalement des appels à <code>PaginationControl</code> :</para>

        <para><programlisting role="php"><![CDATA[
Zend_Paginator::setDefaultScrollingStyle('Sliding');
Zend_View_Helper_PaginationControl::setDefaultViewPartial(
    'my_pagination_control.phtml'
);
$paginator->setView($view);
]]></programlisting></para>

        <para>Utilisez dès lors un simple <code>echo</code> dans le script de vue pour le rendu du paginateur
        complet:</para>

        <para><programlisting role="php"><![CDATA[
<?= $this->paginator; ?>
]]></programlisting></para>

        <note>
            <para>Bien sûr, il est possible d'utiliser Zend_paginator avec d'autres moteurs de templates. Par exemple,
            avec Smarty vous pourriez faire ceci :</para>

            <para><programlisting role="php"><![CDATA[
$smarty->assign('pages', $paginator->getPages());
]]></programlisting></para>

            <para>Vous pouvez ainsi accéder aux valeurs du paginateur grâce à un template comme ceci :</para>

            <para><programlisting role="php"><![CDATA[
{$pages.pageCount}
]]></programlisting></para>
        </note>

        <sect3 id="zend.paginator.usage.rendering.example-controls">
            <title>Exemples de contrôles de pagination</title>

            <para>Voici quelques exemples qui vous aideront à démarrer avec le paginateur:</para>

            <para>Pagination de recherche :<programlisting role="php"><![CDATA[
<!--
Voir http://developer.yahoo.com/ypatterns/pattern.php?pattern=searchpagination
-->

<?php if ($this->pageCount): ?>
<div class="paginationControl">
<!-- Previous page link -->
<?php if (isset($this->previous)): ?>
  <a href="<?= $this->url(array('page' => $this->previous)); ?>">
    &lt; Previous
  </a> |
<?php else: ?>
  <span class="disabled">&lt; Previous</span> |
<?php endif; ?>

<!-- Numbered page links -->
<?php foreach ($this->pagesInRange as $page): ?>
  <?php if ($page != $this->current): ?>
    <a href="<?= $this->url(array('page' => $page)); ?>"><?= $page; ?></a> |
  <?php else: ?>
    <?= $page; ?> |
  <?php endif; ?>
<?php endforeach; ?>

<!-- Next page link -->
<?php if (isset($this->next)): ?>
  <a href="<?= $this->url(array('page' => $this->next)); ?>">Next &gt;</a>
<?php else: ?>
  <span class="disabled">Next &gt;</span>
<?php endif; ?>
</div>
<?php endif; ?>
]]></programlisting></para>

            <para>Pagination d'objets :<programlisting role="php"><![CDATA[
<!--
Voir http://developer.yahoo.com/ypatterns/pattern.php?pattern=itempagination
-->

<?php if ($this->pageCount): ?>
<div class="paginationControl">
<?= $this->firstItemNumber; ?> - <?= $this->lastItemNumber; ?>
of <?= $this->totalItemCount; ?>

<!-- First page link -->
<?php if (isset($this->previous)): ?>
  <a href="<?= $this->url(array('page' => $this->first)); ?>">First</a> |
<?php else: ?>
  <span class="disabled">First</span> |
<?php endif; ?>

<!-- Previous page link -->
<?php if (isset($this->previous)): ?>
  <a href="<?= $this->url(array('page' => $this->previous)); ?>">
    &lt; Previous
  </a> |
<?php else: ?>
  <span class="disabled">&lt; Previous</span> |
<?php endif; ?>

<!-- Next page link -->
<?php if (isset($this->next)): ?>
  <a href="<?= $this->url(array('page' => $this->next)); ?>">Next &gt;</a> |
<?php else: ?>
  <span class="disabled">Next &gt;</span> |
<?php endif; ?>

<!-- Last page link -->
<?php if (isset($this->next)): ?>
  <a href="<?= $this->url(array('page' => $this->last)); ?>">Last</a>
<?php else: ?>
  <span class="disabled">Last</span>
<?php endif; ?>

</div>
<?php endif; ?>
]]></programlisting></para>

            <para>Pagination Dropdown :<programlisting role="php"><![CDATA[
<?php if ($this->pageCount): ?>
<select id="paginationControl" size="1">
<?php foreach ($this->pagesInRange as $page): ?>
  <?php $selected = ($page == $this->current) ? ' selected="selected"' : ''; ?>
  <option value="<?= $this->url(array('page' => $page)); ?>"<?= $selected ?>>
    <?= $page; ?>
  </option>
<?php endforeach; ?>
</select>
<?php endif; ?>

<script type="text/javascript"
    src="http://ajax.googleapis.com/ajax/libs/prototype/1.6.0.2/prototype.js">
</script>
<script type="text/javascript">
$('paginationControl').observe('change', function() {
    window.location = this.options[this.selectedIndex].value;
})
</script>
]]></programlisting></para>
        </sect3>

        <sect3 id="zend.paginator.usage.rendering.properties">
            <title>Liste des propriétés</title>

            <para>Les options suivantes sont disponibles pour contrôler la pagination dans les partials de vue :</para>

            <table id="zend.paginator.usage.rendering.properties.table">
                <title>Propriétés disponibles aux partials de vue</title>

                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>Propriété</entry>

                            <entry>Type</entry>

                            <entry>Description</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>first</entry>

                            <entry>entier</entry>

                            <entry>Numéro de la première page</entry>
                        </row>

                        <row>
                            <entry>firstItemNumber</entry>

                            <entry>entier</entry>

                            <entry>Numéro absolu du premier objet(item) dans cette page</entry>
                        </row>

                        <row>
                            <entry>firstPageInRange</entry>

                            <entry>entier</entry>

                            <entry>Première page dans l'échelle retournée par le type de défilement</entry>
                        </row>

                        <row>
                            <entry>current</entry>

                            <entry>entier</entry>

                            <entry>Numéro de la page en cours</entry>
                        </row>

                        <row>
                            <entry>currentItemCount</entry>

                            <entry>entier</entry>

                            <entry>Nombre d'objets sur cette page</entry>
                        </row>

                        <row>
                            <entry>itemCountPerPage</entry>

                            <entry>integer</entry>

                            <entry>Nombre d'objets maximum à afficher par page</entry>
                        </row>

                        <row>
                            <entry>last</entry>

                            <entry>entier</entry>

                            <entry>Numéro de la dernière page</entry>
                        </row>

                        <row>
                            <entry>lastItemNumber</entry>

                            <entry>entier</entry>

                            <entry>Numéro absolu du dernier objet sur cette page</entry>
                        </row>

                        <row>
                            <entry>lastPageInRange</entry>

                            <entry>entier</entry>

                            <entry>Dernière page dans l'échelle retournée par le type de défilement</entry>
                        </row>

                        <row>
                            <entry>next</entry>

                            <entry>entier</entry>

                            <entry>Numéro de la page suivante</entry>
                        </row>

                        <row>
                            <entry>pageCount</entry>

                            <entry>entier</entry>

                            <entry>Nombre de pages</entry>
                        </row>

                        <row>
                            <entry>pagesInRange</entry>

                            <entry>tableau (array)</entry>

                            <entry>Tableau des pages retournées par le type de défilement</entry>
                        </row>

                        <row>
                            <entry>previous</entry>

                            <entry>entier</entry>

                            <entry>Numéro de la page précédente</entry>
                        </row>

                        <row>
                            <entry>totalItemCount</entry>

                            <entry>entier</entry>

                            <entry>Nombre total d'objets</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>
</sect1>