repo_zf1/documentation/manual/fr/module_specs/Zend_View-Helpers-Partial.xml

<!-- EN-Revision: 14385 -->
<sect3 id="zend.view.helpers.initial.partial">
    <title>L'aide de vue Partial</title>

    <para>L'aide de vue <code>Partial</code> est utilisée pour effectuer le rendu d'un modèle ("template") spécifique
    dans sa propre portée de variable. L'utilisation principale est pour les fragments réutilisables de modèle avec
    lesquels vous n'avez pas besoin de vous inquiéter des conflits de noms de variable. De plus, ils vous permettent de
    spécifier les scripts de vue partiels dans des modules spécifiques.</para>

    <para>Une soeur de l'aide <code>Partial</code>, l'aide de vue de <code>PartialLoop</code> vous permet de passer des
    données itératives, et effectue un rendu partiel pour chaque élément.</para>

    <note>
        <title>Compteur de PartialLoop</title>

        <para>L'aide de vue <code>PartialLoop</code> assigne une variable à la vue nommée <code>partialCounter</code>
        qui fournit la position courante du tableau au script de vue. Ce qui permet simplement d'avoir des couleurs
        alternatives dans les lignes d'un tableau par exemple.</para>
    </note>

    <example id="zend.view.helpers.initial.partial.usage">
        <title>Utilisation de base des Partials</title>

        <para>L'utilisation de base des <code>Partials</code> est d'effectuer le rendu d'un fragment de modèle dans sa
        propre portée de vue. Examinez le script partiel suivant :</para>

        <programlisting role="php"><![CDATA[
<!--partiel.phtml-->
<ul>
    <li>De : <?php echo $this->escape($this->de) ?></li>
    <li>Sujet : <?php echo $this->escape($this->sujet) ?></li>
</ul>
]]></programlisting>

        <para>Vous l'appelleriez alors dans votre script de vue en utilisant ce qui suit :</para>

        <programlisting role="php"><![CDATA[
<?php echo $this->partial('partiel.phtml', array(
    'de' => 'Equipe Framework',
    'sujet' => 'vues partielles')); ?>
]]></programlisting>

        <para>Qui vous retournerait :</para>

        <programlisting role="html"><![CDATA[
<ul>
    <li>De : Equipe Framework</li>
    <li>Sujet : vues partielles</li>
</ul>
]]></programlisting>
    </example>

    <note>
        <title>Qu'est qu'un modèle ?</title>

        <para>Un modèle utilisé avec l'aide de vue <code>Partial</code> peut être un des suivants :</para>

        <itemizedlist>
            <listitem>
                <para><emphasis>Tableaux ("array")</emphasis> : si un tableau est fourni, il devrait être associatif,
                car ses paires de clé/valeur sont assignées à la vue avec les clés comme variables de vue.</para>
            </listitem>

            <listitem>
                <para><emphasis>Objet implémentant la méthode toArray()</emphasis> : si un objet est fourni et qu'il
                possède une méthode <code>toArray()</code>, le résultat de <code>toArray()</code> sera assigné à la vue
                comme variable de vue.</para>
            </listitem>

            <listitem>
                <para><emphasis>Objet standard</emphasis> : tout autre objet assignera le résultat de
                <code>object_get_vars()</code> (essentiellement toutes les propriétés publiques de l'objet) à l'objet de
                vue.</para>
            </listitem>
        </itemizedlist>

        <para>Si votre modèle est un objet, vous pouvez vouloir le fournir en tant qu'objet au script partiel, plutôt
        que de le sérialiser en un tableau de variables. Vous pouvez faire ceci en paramétrant la propriété "objectKey"
        de l'aide de vue approprié :</para>

        <programlisting role="php"><![CDATA[
// Tell partial to pass objects as 'model' variable
$view->partial()->setObjectKey('model');

// Tell partial to pass objects from partialLoop as 'model' variable in final
// partial view script:
$view->partialLoop()->setObjectKey('model');
]]></programlisting>

        <para>Cette technique est particulièrement utile quand vous fournissez un <classname>Zend_Db_Table_Rowset</classname>s à
        <code>partialLoop()</code>, ainsi vous avez un accès complet à vos objets <code>Row</code> à l'intérieur de vos
        scripts de vue, permettant d'appeler des méthodes sur ceux-ci (comme récupérer des valeurs d'un <code>Row</code>
        parent ou dépendant).</para>
    </note>

    <example id="zend.view.helpers.initial.partial.partialloop">
        <title>Utiliser PartialLoop pour effectuer le rendu d'éléments itératifs</title>

        <para>Typiquement, vous voudrez employer des <code>Partials</code> dans une boucle, pour rendre le même fragment
        de contenu plusieurs fois ; de cette façon vous pouvez mettre de grands blocs de contenu répété ou de logique
        complexe d'affichage dans un endroit unique. Toutefois ceci a un impact d'exécution, car l'aide Partial doit
        être appelée une fois par itération.</para>

        <para>L'aide de vue <code>PartialLoop</code> résout ce problème. Elle vous permet de fournir un élément itérable
        (tableau ou objet implémentant <code>Iterator</code>) comme modèle. Elle réitère alors au-dessus de celui-ci en
        fournissant les éléments au script partiel. Les éléments dans l'itérateur peuvent être n'importe quel modèle que
        l'aide de vue <code>Partial</code> permet (cf. ci-dessus).</para>

        <para>Considérons le script partiel suivant :</para>

        <programlisting role="php"><![CDATA[
<!--partialLoop.phtml-->
    <dt><?php echo $this->key ?></dt>
    <dd><?php echo $this->value ?></dd>
]]></programlisting>

        <para>Et le "modèle" suivant :</para>

        <programlisting role="php"><![CDATA[
$model = array(
    array('key' => 'Mammifère', 'value' => 'Chameau'),
    array('key' => 'Oiseau',    'value' => 'Pingouin'),
    array('key' => 'Reptile',   'value' => 'Asp'),
    array('key' => 'Poisson',   'value' => 'Flounder')
);
]]></programlisting>

        <para>Dans votre script de vue, vous pouvez maintenant appeler l'aide <code>PartialLoop</code> :</para>

        <programlisting role="php"><![CDATA[
<dl>
<?php echo $this->partialLoop('partialLoop.phtml', $model) ?>
</dl>
]]></programlisting>

        <programlisting role="html"><![CDATA[
<dl>
    <dt>Mammifère</dt>
    <dd>Chameau</dd>

    <dt>Oiseau</dt>
    <dd>Pingouin</dd>

    <dt>Reptile</dt>
    <dd>Asp</dd>

    <dt>Poisson</dt>
    <dd>Flounder</dd>

</dl>
]]></programlisting>
    </example>

    <example id="zend.view.helpers.initial.partial.modules">
        <title>Effectuer le rendu partiel dans des modules différents</title>

        <para>Parfois un partiel existera dans un module différent. Si vous connaissez le nom du module, vous pouvez le
        fournir comme deuxième argument à <code>partial()</code> ou à <code>partialLoop()</code>, en déplaçant
        l'argument <code>$model</code> à la troisième position.</para>

        <para>Par exemple, s'il y a un gestionnaire de page partiel que vous souhaitez utiliser et qui est dans le
        module "liste", vous pourriez le saisir comme suit :</para>

        <programlisting role="php"><![CDATA[
<?php echo $this->partial('pager.phtml', 'liste', $pagerData) ?>
]]></programlisting>

        <para>De cette façon, vous pouvez réutiliser des partiels créés spécifiquement pour d'autre modules. Ceci dit,
        il est probablement une meilleure pratique de mettre des partiels réutilisables dans des dossiers partagés de
        script de vue.</para>
    </example>
</sect3>