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

<!-- EN-Revision: 13836 -->
<sect1 id="zend.paginator.advanced">
    <title>Utilisation avancée</title>

    <sect2 id="zend.paginator.advanced.adapters">
        <title>Adaptateurs de source de données personnalisée</title>

        <para>À partir d'un moment, vous pourriez avoir besoin de parcourir un type de données qui n'est pas couvert par
        les adaptateurs fournis par défaut. Dans ce cas, vous devrez écrire vos propres adaptateurs.</para>

        <para>Pour faire ceci, vous devez implémenter <classname>Zend_Paginator_Adapter_Interface</classname>. Il existe deux
        méthodes requises :</para>

        <itemizedlist>
            <listitem>
                <para><code>count()</code></para>
            </listitem>

            <listitem>
                <para><code>getItems($offset, $itemCountPerPage)</code></para>
            </listitem>
        </itemizedlist>

        <para>De plus, vous voudrez peut-être implémenter un constructeur qui prend votre source de données comme
        paramètre et le stocke comme propriété protégée ou privée. La manière suivant laquelle vous allez spécifiquement
        faire ceci, vous incombe.</para>

        <para>Si vous avez déjà utilisé l'interface SPL <ulink
        url="http://www.php.net/~helly/php/ext/spl/interfaceCountable.html"><code>Countable</code></ulink>, vous êtes
        familier avec <code>count()</code>. Utilisé avec <classname>Zend_Paginator</classname>, il s'agit du nombre total
        d'éléments dans la collection de données. De plus, l'instance <classname>Zend_Paginator</classname> fournit une méthode
        <code>countAllItems()</code> qui proxie vers la méthode <code>count()</code> de l'adaptateur.</para>

        <para>La méthode <code>getItems()</code> est seulement légèrement plus compliquée. Pour ceci, les paramètres
        sont un point de départ et un nombre d'éléments à afficher par page. Vous devez retourner la portion appropriée
        de données. Pour un tableau, il s'agirait :</para>

        <para><programlisting role="php"><![CDATA[
return array_slice($this->_array, $offset, $itemCountPerPage);
]]></programlisting></para>

        <para>Regardez les adaptateurs fournis par défaut (ils implémentent tous
        <classname>Zend_Paginator_Adapter_Interface</classname>) pour avoir une idée de la manière d'implémenter votre propre
        adaptateur.</para>
    </sect2>

    <sect2 id="zend.paginator.advanced.scrolling-styles">
        <title>Styles de défilement personnalisés</title>

        <para>Créer votre propre style de défilement requiert que vous implémentiez
        <classname>Zend_Paginator_ScrollingStyle_Interface</classname>, qui définit une seule méthode, <code>getPages()</code>. Et
        plus spécifiquement :</para>

        <para><programlisting role="php"><![CDATA[
public function getPages(Zend_Paginator $paginator, $pageRange = null);
]]></programlisting></para>

        <para>Cette méthode doit calculer des bornes inférieures et supérieures des numéros de page dans la plage des
        pages dites "local" (c'est-à-dire qui sont proches de la page courante).</para>

        <para>A moins que votre style étende un autre style de défilement (voir
        <classname>Zend_Paginator_ScrollingStyle_Elastic</classname> par exemple), votre style personnalisé devra inévitablement
        se terminer par quelque chose de similaire à ceci :</para>

        <para><programlisting role="php"><![CDATA[
return $paginator->getPagesInRange($lowerBound, $upperBound);
]]></programlisting></para>

        <para>Il n'y a rien de spécial au sujet de cet appel ; c'est simplement une méthode pratique pour vérifier la
        validité de la limite inférieure et supérieure et pour renvoyer un tableau de ces bornes au paginateur.</para>

        <para>Quand vous êtes prêt à utiliser votre style de défilement, vous devez informer <classname>Zend_Paginator</classname>
        dans quel dossier le chercher, en réalisant ceci :</para>

        <para><programlisting role="php"><![CDATA[
$prefix = 'Mon_Paginator_StyleDefilement';
$path   = 'Mon/Paginator/StyleDefilement/';
Zend_Paginator::addScrollingStylePrefixPath($prefix, $path);
]]></programlisting></para>
    </sect2>

    <sect2 id="zend.paginator.advanced.caching">
        <title>Fonctionnalité de mise en cache</title>

        <para><classname>Zend_Paginator</classname> peut mettre en cache les données qu'il a déjà fourni, empêchant ainsi
        l'adaptateur de les rechercher chaque fois qu'ils sont demandés. Pour informer le paginateur de mettre en cache
        automatiquement les données issues de l'adaptateur, fournissez simplement une instance de
        <classname>Zend_Cache_Core</classname> à sa méthode <code>setCache()</code> :</para>

        <para><programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
$fO = array('lifetime' => 3600, 'automatic_serialization' => true);
$bO = array('cache_dir'=>'/tmp');
$cache = Zend_cache::factory('Core', 'File', $fO, $bO);
Zend_Paginator::setCache($cache);
]]></programlisting></para>

        <para>Tant que Zend_Paginator possède une instance de Zend_Cache_Core, les données seront mises en cache.
        Parfois vous ne voudrez pas mettre en cache les données même si vous avez déjà fourni un instance de cache. Vous
        pourrez alors utiliser la méthode <code>setCacheEnable()</code> :</para>

        <para><programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
// $cache est une instance de Zend_Cache_Core
Zend_Paginator::setCache($cache);
// ... plus loin dans le script
$paginator->setCacheEnable(false);
// le cache est maintenant désactivé
]]></programlisting></para>

        <para>Quand un cache est paramétré, les données y sont automatiquement stockées et extraites. Il peut alors être
        utile de vider le cache manuellement. Vous pouvez réaliser ceci en appelant
        <code>clearPageItemCache($pageNumber)</code>. Si vous ne passer aucun paramètre, le cache entier sera vidé. Vous
        pouvez fournir optionnellement un paramètre représentant le numéro de page à enlever du cache :</para>

        <para><programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
$items = $paginator->getCurrentItems();
// la page 1 est maintenant en cache
$page3Items = $paginator->getItemsByPage(3);
// la page 3 est maintenant en cache

// effacer le cache associé à la page 3
$paginator->clearPageItemCache(3);

// effacer tout le cache
$paginator->clearPageItemCache();
]]></programlisting></para>

        <para>Changer le nombre d'éléments par page videra tout le cache comme s'il était devenu invalide :</para>

        <para><programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
// récupérer des éléments
$items = $paginator->getCurrentItems();

// toutes les données vont être effacées du cache :
$paginator->setItemCountPerPage(2);
]]></programlisting></para>

        <para>Il est aussi possible de voir les données en cache et de les appeler directement grâce à la méthode
        <code>getPageItemCache()</code> :</para>

        <para><programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
$paginator->setItemCountPerPage(3);
Zend_Paginator::setCache($cache);

// récupérer des éléments
$items = $paginator->getCurrentItems();
$otherItems = $paginator->getItemsPerPage(4);

// voir ces éléments sous la forme d'un tableau à 2-dimensions :
var_dump($paginator->getPageItemCache());
]]></programlisting></para>
    </sect2>
</sect1>