repo_zf1/documentation/manual/fr/tutorials/view-placeholders-standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="learning.view.placeholders.standard">
    <title>Placeholders standards</title>

    <para>
        Dans la <link linkend="learning.view.placeholders.basics">section précédente</link>, nous
        avons vu l'aide de vue <methodname>placeholder()</methodname> et comment l'utiliser pour
        aggréger du contenu personnalisable. Dans ce chapitre, nous allons passer en revue quelques
        placeholders concrets fournis avec Zend Framework, ainsi que la manière de les utiliser à
        votre avantage pour créer des layouts complexes.
    </para>

    <para>
        La plupart des placeholders fournis permettent de gérer le contenur de la section
        <emphasis>&lt;head&gt;</emphasis> de la layout -- une zone qui ne peut typiquement pas être
        manipulée directement par vos scripts de vue, mais que vous voulez tout de même traiter.
        Par exemples: vous voudriez que votre titre se compose d'un certain contenu sur toutes les
        pages mais aussi d'une partie dynamique relative au contrôleur/action en cours; aussi vous
        voudriez préciser des fichiers <acronym>CSS</acronym> à charger basés sur la section de
        l'application en cours; enfin vous pourriez avoir recours à des scripts JavaScript
        spécifiques parfois, ou encore changer la déclaration de <emphasis>DocType</emphasis>.
    </para>

    <para>
        Zend Framework est livré avec des implémentations de placeholder pour chacune de ces
        situations et encore d'autres.
    </para>

    <sect2 id="learning.view.placeholders.standard.doctype">
        <title>Changer le DocType</title>

        <para>
            Les déclarations de <emphasis>DocType</emphasis> sont difficiles à mémoriser et souvent
            essentielles pour s'assurer que le navigateur rende correctement le contenu. L'aide de
            vue <methodname>doctype()</methodname> permet d'utiliser des mnemonics pour spécifier un
            <emphasis>DocType</emphasis>; aussi, d'autres aides de vues interrogeront l'aide
            <methodname>doctype()</methodname> pour s'assurer que le contenu qu'elles génèrent est
            conforme au <emphasis>DocType</emphasis> utilisé.
        </para>

        <para>
            Par exemple si vous souhaitez utiliser la <acronym>DTD</acronym>
            <acronym>XHTML1</acronym> Strict, vous pouvez simplement la préciser
            comme ceci&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$this->doctype('XHTML1_STRICT');
]]></programlisting>

        <para>
            Voici les autres mnemonics utilisables&#160;:
        </para>

        <variablelist>
            <varlistentry>
                <term>XHTML1_STRICT</term>

                <listitem>
                    <para>
                        <acronym>XHTML</acronym> 1.0 Strict
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>XHTML1_TRANSITIONAL</term>

                <listitem>
                    <para>
                        <acronym>XHTML</acronym> 1.0 Transitional
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>HTML4_STRICT</term>

                <listitem>
                    <para>
                        <acronym>HTML</acronym> 4.01 Strict
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>HTML4_Loose</term>

                <listitem>
                    <para>
                        <acronym>HTML</acronym> 4.01 Loose
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>HTML5</term>

                <listitem>
                    <para>
                        <acronym>HTML</acronym> 5
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>

        <para>
            Vous pouvez changer le type et rendre la déclaration en un seul appel&#160;:
        </para>

        <programlisting language="php"><![CDATA[
echo $this->doctype('XHTML1_STRICT');
]]></programlisting>

        <para>
            Cependant l'approche conseillée est de préciser le type dans le bootstrap et rendre
            l'aide de vue dans la layout. Essayez d'ajouter ceci à votre classe de bootstrap&#160;:
        </para>

        <programlisting language="php"><![CDATA[
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    protected function _initDocType()
    {
        $this->bootstrap('View');
        $view = $this->getResource('View');
        $view->doctype('XHTML1_STRICT');
    }
}
]]></programlisting>

        <para>
            Puis, dans le script de layout, affichez simplement avec
            <methodname>echo()</methodname> l'aide en haut du fichier&#160;:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->doctype() ?>
<html>
    <!-- ... -->
]]></programlisting>

        <para>
            Ceci permet d'être sûr que les aides de vue diverses utiliseront cette déclaration,
            que le docType est précisé avant le rendu du layout et qu'il n'existe qu'un seul
            endroit logique pour le changer.
        </para>
    </sect2>

    <sect2 id="learning.view.placeholders.standard.head-title">
        <title>Spécifier le titre de la page</title>

        <para>
            Souvent, le site incluera le nom de la société dans le titre de la page et ajoutera
            ensuite des informations basées sur la page en cours de lecture. Par exemple, le site
            <filename>zend.com</filename> inclut la chaine "<filename>Zend.com</filename>" sur
            toutes les pages et y fait précèder des informations relatives à la page en
            cours&#160;: "Zend Server - <filename>Zend.com</filename>". Dans Zend Framework,
            l'aide de vue <methodname>headTitle()</methodname> peut vous simplifier cette tâche.
        </para>

        <para>
            Au plus simple, l'aide <methodname>headTitle()</methodname> permet d'aggréger du
            contenu pour la balise <emphasis>&lt;title&gt;</emphasis>; lorsque vous l'affichez,
            il assemble son contenu dans l'ordre des ajouts. Pour contrôler l'ordre, les méthodes
            <methodname>prepend()</methodname> et <methodname>append()</methodname> sont là, pour
            changer le séparateur à utiliser entre les segments, utilisez la méthode
            <methodname>setSeparator()</methodname>.
        </para>

        <para>
            Typiquement vous devriez renseigner tous les segments communs à toutes les pages en
            bootstrap, de la même manière que nous avions agit avec le doctype. Dans ce cas, nous
            allons écrire une méthode <methodname>_initPlaceholders()</methodname> pour gérer
            tous les placeholders et préciser un titre initial ainsi qu'un séparateur.
        </para>

        <programlisting language="php"><![CDATA[
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    // ...

    protected function _initPlaceholders()
    {
        $this->bootstrap('View');
        $view = $this->getResource('View');
        $view->doctype('XHTML1_STRICT');

        // Précise le titre initial et le séparateur:
        $view->headTitle('My Site')
             ->setSeparator(' :: ');
    }

    // ...
}
]]></programlisting>

        <para>
            Dans un script de vue, nous voulons ajouter un nouveau segment&#160;:
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->headTitle()->append('Some Page'); // placé après les autres segments ?>
<?php $this->headTitle()->prepend('Some Page'); // placé avant ?>
]]></programlisting>

        <para>
            Dans notre layout, nous affichons simplement l'aide
            <methodname>headTitle()</methodname>&#160;:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->doctype() ?>
<html>
    <?php echo $this->headTitle() ?>
    <!-- ... -->
]]></programlisting>

        <para>
            Le contenu suivant aura été généré&#160;:
        </para>

        <programlisting language="html"><![CDATA[
<!-- Si append() a été utilisé: -->
<title>My Site :: Some Page</title>

<!-- Si prepend() a été utilisé: -->
<title>Some Page :: My Site</title>
]]></programlisting>
    </sect2>

    <sect2 id="learning.view.placeholders.standard.head-link">
        <title>Spécifier des feuilles de style avec HeadLink</title>

        <para>
            Les bons développeurs <acronym>CSS</acronym> créront souvent une feuille de style
            globale et des feuilles individuelles pour les sections spécifiques ou certaines
            pages du site puis chargeront celles-ci plus tard conditionnellement afin de réduire
            le nombre de données à transférer entre chaque requête. Le placeholder
            <methodname>headLink()</methodname> permet de réaliser de telles aggrégations
            conditionnelles de feuilles de style.
        </para>

        <para>
            Pour cela, <methodname>headLink()</methodname> definit une certain nombre de méthodes
            "virtuelles" (via surcharge) pour simplifier le tout. Celles qui vont nous concernet
            sont <methodname>appendStylesheet()</methodname> et
            <methodname>prependStylesheet()</methodname>. Chacune peut accepter jusqu'à quatre
            arguments, <varname>$href</varname> (chemin relatif vers la feuille de style),
            <varname>$media</varname> (le type <acronym>MIME</acronym>, par défaut "text/css"),
            <varname>$conditionalStylesheet</varname> (à utiliser pour préciser une "condition"
            à évaluer pour la feuille de style), et <varname>$extras</varname> (un tableau
            associatif utiliser générallement pour renseigner une clé pour "media"). Dans la
            plupart des cas, seul le premier argument suffira, le chemin relatif vers la feuille
            de style.
        </para>

        <para>
            Dans notre exemple, nous supposerons que toutes les pages ont besoin de charger une
            feuille de style stockée dans "<filename>/styles/site.css</filename>" (relativement
            au document root)&#160;; nous allons préciser cela dans notre méthode de bootstrap
            <methodname>_initPlaceholders()</methodname>.
        </para>

        <programlisting language="php"><![CDATA[
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    // ...

    protected function _initPlaceholders()
    {
        $this->bootstrap('View');
        $view = $this->getResource('View');
        $view->doctype('XHTML1_STRICT');

        // Affecte le titre original et le séparateur:
        $view->headTitle('My Site')
             ->setSeparator(' :: ');

        // Affecte la feuille de style originale:
        $view->headLink()->prependStylesheet('/styles/site.css');
    }

    // ...
}
]]></programlisting>

        <para>
            Plus tard, dans un contrôleur par exemple, nous pouvons rajouter des feuilles de
            style:
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->headLink()->appendStylesheet('/styles/user-list.css') ?>
]]></programlisting>

        <para>
            Dans notre layout, là encore, un simple echo sur le placeholder&#160;:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->doctype() ?>
<html>
    <?php echo $this->headTitle() ?>
    <?php echo $this->headLink() ?>
    <!-- ... -->
]]></programlisting>

        <para>
            Ceci génèrera quelque chose comme:
        </para>

        <programlisting language="html"><![CDATA[
<link rel="stylesheet" type="text/css" href="/styles/site.css" />
<link rel="stylesheet" type="text/css" href="/styles/user-list.css" />
]]></programlisting>
    </sect2>

    <sect2 id="learning.view.placeholders.standard.head-script">
        <title>Aggréger des scripts avec HeadScript</title>

        <para>
            Un autre moyen de ne pas surcharger la page est de ne charger le JavaScript que
            lorsque c'est nécessaire. Vous aurez donc besoin de scripts découpés: peut-être un
            pour afficher le menu du site progressivement, un autre pour traiter le contenu d'une
            page spécifique. Dans ces cas, l'aide <methodname>headScript()</methodname> propose
            une solution.
        </para>

        <para>
            Comme l'aide <methodname>headLink()</methodname>, <methodname>headScript()</methodname>
            permet d'empiler en début ou fin des scripts entiers et de les afficher d'un coup. Cela
            est très flexible pour spécifier des fichiers de scripts entiers à charger, ou encore
            du code JavaScript explicite. Vous pouvez aussi capturer le JavaScript via
            <methodname>captureStart()</methodname>/<methodname>captureEnd()</methodname>, qui
            permettent d'utiliser du code JavaScript inline plutot que de demander un appel serveur
            pour charger un fichier.
        </para>

        <para>
            Tout comme <methodname>headLink()</methodname>, <methodname>headScript()</methodname>
            propose des mééthodes "virtuelles" via surcharge pour spécifier rapidement des contenus
            à aggréger; les méthodes sont <methodname>prependFile()</methodname>,
            <methodname>appendFile()</methodname>, <methodname>prependScript()</methodname>, et
            <methodname>appendScript()</methodname>. Les deux premières vous permettent de préciser
            des fichiers référéncés dans l'attribut <varname>$src</varname> d'une balise
            <emphasis>&lt;script&gt;</emphasis>; les deux dernières vont prendre le contenu qu'on
            leur passe et le rendre comme du JavaScript dans les balises
            <emphasis>&lt;script&gt;</emphasis>.
        </para>

        <para>
            Dans cet exemple, nous allons spécifier qu'un script,
            "<filename>/js/site.js</filename>" a besoin d'être chargé sur chaque page&#160;; nous
            allons donc mettre à jour notre méthode de bootstap
            <methodname>_initPlaceholders()</methodname> pour effectuer cela.
        </para>

        <programlisting language="php"><![CDATA[
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    // ...

    protected function _initPlaceholders()
    {
        $this->bootstrap('View');
        $view = $this->getResource('View');
        $view->doctype('XHTML1_STRICT');

        // Titre et séparateur d'origine:
        $view->headTitle('My Site')
             ->setSeparator(' :: ');

        // Feuille de style originale:
        $view->headLink()->prependStylesheet('/styles/site.css');

        // Affecte le JS initial à charger:
        $view->headScript()->prependFile('/js/site.js');
    }

    // ...
}
]]></programlisting>

        <para>
            Dans un script de vue, nous voulons ajouter un script ou capturer du contenu
            JavaScript à inclure dans le document.
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->headScript()->appendFile('/js/user-list.js') ?>
<?php $this->headScript()->captureStart() ?>
site = {
    baseUrl: "<?php echo $this->baseUrl() ?>"
};
<?php $this->headScript()->captureEnd() ?>
]]></programlisting>

        <para>
            Dans notre script de layout, nous affichons simplement le placeholder, tout comme
            nous avions fait pour les autres précédemment&#160;:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->doctype() ?>
<html>
    <?php echo $this->headTitle() ?>
    <?php echo $this->headLink() ?>
    <?php echo $this->headScript() ?>
    <!-- ... -->
]]></programlisting>

        <para>
            Le contenu suivant sera généré:
        </para>

        <programlisting language="html"><![CDATA[
<script type="text/javascript" src="/js/site.js"></script>
<script type="text/javascript" src="/js/user-list.js"></script>
<script type="text/javascript">
site = {
    baseUrl: "<?php echo $this->baseUrl() ?>"
};
</script>
]]></programlisting>

        <note>
            <title>Variante InlineScript</title>

            <para>
                La plupart des navigateur bloquent l'affichage tant que tous les scritps et les
                feuilles de style référencés dans la section <emphasis>&lt;head&gt;</emphasis>
                ne sont pas chargés. Ces règles permettent un meilleur feeling au niveau du rendu
                de la page et permettent à l'utilisateur de voir le contenu de la page plus tôt.
            </para>

            <para>
                Pour cela, vous pouvez par exemple écrire vos tags
                <emphasis>&lt;script&gt;</emphasis> après avoir fermé
                <emphasis>&lt;body&gt;</emphasis>. (C'est une pratique recommandée
                par <ulink url="http://developer.yahoo.com/yslow/">Y!Slow project</ulink>.)
            </para>

            <para>
                Zend Framework supporte cela de deux manières différentes&#160;:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        Vous pouvez rendre <methodname>headScript()</methodname> où vous voulez
                        dans votre layout; ce n'est pas parce que la méthode commence par "head"
                        que vous devez l'appeler pour cette section du HTML.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Aussi, vous pourriez utiliser l'aide de vue
                        <methodname>inlineScript()</methodname>, qui est simplement une variante
                        de <methodname>headScript()</methodname> avec le même
                        comportement mais un registre séparé.
                    </para>
                </listitem>
            </itemizedlist>
        </note>
    </sect2>
</sect1>