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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.view.helpers.initial.placeholder">
    <title>L'aide de vue Placeholder</title>

    <note>
        <para>
            NDT. : Le terme "placeholder est conservé car sa signification varie en fonction
            du contexte : conteneur générique ou emplacement réservé.
        </para>
    </note>

    <para>
        L'aide de vue <code>Placeholder</code> est utilisé pour faire persister le contenu
        entre les scripts de vues et les instances de vues. Il offre aussi des fonctionnalités
        utiles comme l'agrégation de contenu, la capture de contenu de scripts de vues pour une
        utilisation ultérieure, et l'ajout de texte pré ou post contenu (et la personnalisation des
        séparateurs de contenu).
    </para>

    <example id="zend.view.helpers.initial.placeholder.usage">
        <title>Utilisation basique des Placeholders</title>

        <para>
            L'utilisation basique des placeholders est la persistance des données de vue.
            Chaque appel de l'aide <code>Placeholder</code> attend un nom de placeholder ; l'aide
            retourne un objet conteneur que vous pouvez soit manipuler ou simplement envoyé à
            l'affichage.
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->placeholder('foo')->set("Du texte pour plus tard") ?>

<?php
    echo $this->placeholder('foo');
    // outputs "Du texte pour plus tard"
?>
]]></programlisting>
    </example>

    <example id="zend.view.helpers.initial.placeholder.aggregation">
        <title>Utilisation des Placeholders pour agréger du contenu</title>

        <para>
            L'agrégation du contenu via les placeholders peut être aussi utile parfois. Par
            exemple, votre script de vue peut avoir une variable sous forme de tableau à partir de
            laquelle vous souhaitez récupérer des messages à afficher plus tard ; un autre script de
            vue peut ensuite déterminer de la manière suivant laquelle ils seront affichés.
        </para>

        <para>
            L'aide de vue <code>Placeholder</code> utilise des conteneurs qui étendent
            <code>ArrayObject</code>, fournissant de riches fonctionnalités de manipulations des
            tableaux. De plus, il offre une variété de méthodes pour le formatage du contenu stockée
            dans le conteneur :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setPrefix($prefix)</methodname> paramètre le texte qui sera placé
                    préalablement à tout le contenu. Utilisez <methodname>getPrefix()</methodname> à tout moment
                    pour déterminer le réglage courant.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setPostfix($prefix)</methodname> paramètre le texte qui sera placé après
                    tout le contenu. Utilisez <methodname>getPostfix()</methodname> à tout moment pour
                    déterminer le réglage courant.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setSeparator($prefix)</methodname> paramètre le texte qui sera placé entre
                    chaque élément de contenu. Utilisez <methodname>getSeparator()</methodname> à tout moment
                    pour déterminer le réglage courant.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setIndent($prefix)</methodname> peut être utilisé pour paramétrer une
                    indentation pour chaque élément du contenu. Si un entier est fourni, il s'agira
                    du nombre d'espaces à utiliser ; si une chaîne est fournie, elle sera utilisée.
                    Utilisez <methodname>getIndent()</methodname> à tout moment pour déterminer le réglage
                    courant.
                </para>
            </listitem>
        </itemizedlist>

        <programlisting language="php"><![CDATA[
<!-- premier script de vue -->
<?php $this->placeholder('foo')->exchangeArray($this->data) ?>
]]></programlisting>

        <programlisting language="php"><![CDATA[
<!-- autre script (plus tard) -->
<?php
$this->placeholder('foo')->setPrefix("<ul>\n    <li>")
                         ->setSeparator("</li><li>\n")
                         ->setIndent(4)
                         ->setPostfix("</li></ul>\n");
?>

<?php
    echo $this->placeholder('foo');
    // affiche une liste non-ordonnée avec une belle indentation
?>
]]></programlisting>

        <para>
            Puisque l'objet conteneur <code>Placeholder</code> étend <code>ArrayObject</code>,
            vous pouvez ainsi facilement assigner du contenu à une clé du conteneur en particulier,
            plutôt que de simplement de les envoyer les unes après les autres ("push"). Les clés
            peuvent être accédées soit en utilisant les propriétés d'objet ou comme les clés d'un
            tableau.
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->placeholder('foo')->bar = $this->data ?>
<?php echo $this->placeholder('foo')->bar ?>

<?php
$foo = $this->placeholder('foo');
echo $foo['bar'];
?>
]]></programlisting>
    </example>

    <example id="zend.view.helpers.initial.placeholder.capture">
        <title>Utilisation des Placeholders pour capturer le contenu</title>

        <para>
            Occasionnellement vous pouvez avoir du contenu pour un placeholder dans un script
            de vue qui est simple à mettre sous forme de modèle ("template") ; l'aide de vue
            <code>Placeholder</code> vous permet de capturer tout contenu arbitraire pour un rendu
            ultérieur en utilisant l'API suivante.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>captureStart($type, $key)</methodname> commence la capture de
                    contenu.
                </para>

                <para>
                    <varname>$type</varname> doit être une des constantes de
                    <code>Placeholder</code> : <constant>APPEND</constant> ou <constant>SET</constant>. Si c'est
                    <constant>APPEND</constant>, le contenu capturé est ajouté à la liste de contenu courant
                    dans le placeholder ; si c'est <constant>SET</constant>, le contenu capturé remplace
                    toute valeur existante dans le placeholder (potentiellement permet de remplacer
                    tout contenu préalable). Par défaut, <varname>$type</varname> vaut
                    <constant>APPEND</constant>.
                </para>

                <para>
                    <varname>$key</varname> peut être utilisé pour spécifier une clé en particulier
                    dans le conteneur placeholder dans laquelle vous souhaitez capturer le
                    contenu.
                </para>

                <para>
                    <methodname>captureStart()</methodname> verrouille la capture jusqu'à l'appel de
                    <methodname>captureEnd()</methodname> ; vous ne pouvez pas imbriquer des captures avec le
                    même conteneur placeholder. Le faire entraînera la levée d'une exception.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>captureEnd()</methodname> stoppe la capture de contenu, et le place dans
                    l'objet conteneur suivant la manière utilisée pour appeler
                    <methodname>captureStart()</methodname>.
                </para>
            </listitem>
        </itemizedlist>

        <programlisting language="php"><![CDATA[
<!-- Default capture: append -->
<?php $this->placeholder('foo')->captureStart();
foreach ($this->data as $datum): ?>
<div class="foo">
    <h2><?php echo $datum->title ?></h2>
    <p><?php echo $datum->content ?></p>
</div>
<?php endforeach; ?>
<?php $this->placeholder('foo')->captureEnd() ?>

<?php echo $this->placeholder('foo') ?>
]]></programlisting>

        <programlisting language="php"><![CDATA[
<!-- Capture to key -->
<?php $this->placeholder('foo')->captureStart('SET', 'data');
foreach ($this->data as $datum): ?>
<div class="foo">
    <h2><?php echo $datum->title ?></h2>
    <p><?php echo $datum->content ?></p>
</div>
 <?php endforeach; ?>
<?php $this->placeholder('foo')->captureEnd() ?>

<?php echo $this->placeholder('foo')->data ?>
]]></programlisting>
    </example>

    <sect4 id="zend.view.helpers.initial.placeholder.implementations">
        <title>Implémentation concrète des Placeholder</title>

        <para>
            Zend Framework embarque certaines implémentations concrètes de placeholders.
            Celles-ci sont destinées à des placeholders communément utilisés : doctype, titre de
            page, et les différents éléments &lt;head&gt;. Dans tous les cas, appeler le placeholder
            sans arguments retournera l'élément lui-même.
        </para>

        <para>
            La documentation pour chacun des éléments existe séparément, suivez les liens
            ci-dessous :
        </para>

        <itemizedlist>
            <listitem>
                <para><link linkend="zend.view.helpers.initial.doctype">Doctype</link></para>
            </listitem>

            <listitem>
                <para><link linkend="zend.view.helpers.initial.headlink">HeadLink</link></para>
            </listitem>

            <listitem>
                <para><link linkend="zend.view.helpers.initial.headmeta">HeadMeta</link></para>
            </listitem>

            <listitem>
                <para>
                    <link
                    linkend="zend.view.helpers.initial.headscript">HeadScript</link>
                </para>
            </listitem>

            <listitem>
                <para>
                    <link
                    linkend="zend.view.helpers.initial.headstyle">HeadStyle</link>
                </para>
            </listitem>

            <listitem>
                <para>
                    <link
                    linkend="zend.view.helpers.initial.headtitle">HeadTitle</link>
                </para>
            </listitem>

            <listitem>
                <para>
                    <link
                    linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>
                </para>
            </listitem>
        </itemizedlist>
    </sect4>
</sect3>