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

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

    <para>
        L'élément HTML <code>&lt;meta&gt;</code> est utilisé pour fournir des métadonnées
        concernant votre document HTML - typiquement, les mots-clés, l'encodage du document, les
        directives de mise en cache, etc. Les balises de métadonnées peuvent être soit de type
        "http-equiv" ou "name", doivent contenir un attribut "content" et peuvent avoir aussi un
        attribut modificateur "lang" ou "scheme".
    </para>

    <para>
        L'aide de vue <code>HeadMeta</code> supporte les méthodes suivantes pour le
        paramétrage et l'ajout de métadonnées :
    </para>

    <itemizedlist>
        <listitem>
            <para><methodname>appendName($keyValue, $content, $conditionalName)</methodname></para>
        </listitem>

        <listitem>
            <para>
                <code>offsetSetName($index, $keyValue, $content,
                $conditionalName)</code>
            </para>
        </listitem>

        <listitem>
            <para><methodname>prependName($keyValue, $content, $conditionalName)</methodname></para>
        </listitem>

        <listitem>
            <para><methodname>setName($keyValue, $content, $modifiers)</methodname></para>
        </listitem>

        <listitem>
            <para>
                <code>appendHttpEquiv($keyValue, $content,
                $conditionalHttpEquiv)</code>
            </para>
        </listitem>

        <listitem>
            <para>
                <code>offsetSetHttpEquiv($index, $keyValue, $content,
                $conditionalHttpEquiv)</code>
            </para>
        </listitem>

        <listitem>
            <para>
                <code>prependHttpEquiv($keyValue, $content,
                $conditionalHttpEquiv)</code>
            </para>
        </listitem>

        <listitem>
            <para><methodname>setHttpEquiv($keyValue, $content, $modifiers)</methodname></para>
        </listitem>
    </itemizedlist>

     <para>
        Les méthodes suivantes sont aussi supportées avec le doctype XHTML1_RDFA si celui-ci a été
        spécifié avec <link linkend="zend.view.helpers.initial.doctype">l'aide de vue
        Doctype</link>&#160;:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <command>appendProperty($property, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>offsetSetProperty($index, $property, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>prependProperty($property, $content, $modifiers)</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>setProperty($property, $content, $modifiers)</command>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Le paramètre <varname>$keyValue</varname> est utilisé pour définir une valeur pour la clé
        "name" ou "http-equiv" ; <varname>$content</varname> est la valeur pour la clé "content", et
        <varname>$modifiers</varname> est un tableau associatif optionel qui peut contenir les clés "lang"
        et/ou "scheme".
    </para>

    <para>
        Vous pouvez aussi spécifier les métadonnées en utilisant la méthode
        <methodname>headMeta()</methodname> qui a la signature suivante : <code>headMeta($content, $keyValue,
        $keyType = 'name', $modifiers = array(), $placement = 'APPEND')</code>.
        <varname>$keyValue</varname> est le contenu de la clé spécifiée dans <varname>$keyType</varname>, qui
        peut être "name" ou "http-equiv". <varname>$keyType</varname> peut aussi être spécifié en tant que
        'property' si le doctype a été réglé à XHTML1_RDFA. <varname>$placement</varname> peut être soit "SET" (efface
        toutes les valeurs sauvegardées précédentes), soit "APPEND" (ajout en fin de pile), soit
        "PREPEND" (ajout en début de pile).
    </para>

    <para>
        <code>HeadMeta</code> surcharge chacune des méthodes <methodname>append()</methodname>,
        <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, et <methodname>set()</methodname>, pour imposer
        l'utilisation des méthodes spéciales énumérées ci-dessus. En interne, il stocke chaque
        élément sous la forme d'un <code>stdClass</code>, qui peut ensuite être sérialiser grâce à
        la méthode <methodname>itemToString()</methodname>. Ceci vous permet de réaliser des contrôles sur les
        éléments de la pile, et optionnellement de modifier ces éléments simplement en modifiant
        l'objet retourné.
    </para>

    <para>
        L'aide de vue <code>HeadMeta</code> est une implémentation concrète de l'aide <link
        linkend="zend.view.helpers.initial.placeholder">Placeholder</link>.
    </para>

    <example id="zend.view.helpers.initial.headmeta.basicusage">
        <title>Utilisation basique de l'aide HeadMeta</title>

        <para>
            Vous pouvez spécifier une nouvelle métadonnée à n'importe quel moment.
            Typiquement, vous pouvez spécifier les règles de mise en cache côté client ou les mots
            clés SEO (Search Engine Optimization : pour l'optimisation des moteurs de
            recherche).
        </para>

        <para>
            Par exemple, si vous souhaitez spécifier des mots clés SEO, vous devez créer une
            métadonnée de type "name" ayant pour nom "keywords" et pour contenu les mots clés que
            vous souhaitez associer à votre page :
        </para>

        <programlisting language="php"><![CDATA[
// paramètrage des mots clés
$this->headMeta()->appendName('keywords', 'framework, PHP, productivité');
]]></programlisting>

        <para>
            Si vous souhaitez paramètrer des règles de mise en cache côté client, vous devez
            créer une métadonnée de type "http-equiv" avec les règles que vous souhaitez imposer
            :
        </para>

        <programlisting language="php"><![CDATA[
// désactiver la mise en cache côté client
$this->headMeta()->appendHttpEquiv('expires',
                                   'Wed, 26 Feb 1997 08:21:57 GMT')
                 ->appendHttpEquiv('pragma', 'no-cache')
                 ->appendHttpEquiv('Cache-Control', 'no-cache');
]]></programlisting>

        <para>
            Une autre utilisation habituelle des métadonnées est le réglage du type de contenu
            ("content type"), de l'encodage, et le langage :
        </para>

        <programlisting language="php"><![CDATA[
// régler le type de contenu et l'encodage
$this->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=UTF-8')
                 ->appendHttpEquiv('Content-Language', 'fr-FR');
]]></programlisting>

         <para>
            Si vous proposez un document <acronym>HTML5</acronym>, vous pouvez fournir l'encodage
            de cette manière&#160;:
        </para>

        <programlisting language="php"><![CDATA[
// régler l'encodage en HTML5
$this->headMeta()->setCharset('UTF-8');
// donnera <meta charset="UTF-8">
]]></programlisting>

        <para>
            Et comme exemple final, une manière simple d'afficher un message de transition
            avant une redirection est d'utiliser une métadonnée "refresh" :
        </para>

        <programlisting language="php"><![CDATA[
// paramètrer une métadonnée refresh pour 3 secondes
// avant une nouvel URL :
$this->headMeta()->appendHttpEquiv('Refresh',
                                   '3;URL=http://www.some.org/some.html');
]]></programlisting>

        <para>
            Quand vous êtes prêts à placer vos métadonnées dans votre script de disposition,
            réalisez un "<code>echo</code>" de l'aide :
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->headMeta() ?>
]]></programlisting>
    </example>

    <example id="zend.view.helpers.initial.headmeta.property">
        <title>Utilisation de HeadMeta avec le doctype XHTML1_RDFA</title>

        <para>
            Activer le doctype RDFa avec <link
                linkend="zend.view.helpers.initial.doctype">l'aide de vue Doctype</link> active
            l'utilisation de l'attribut 'property' (en plus des habituels 'name' et 'http-equiv')
            avec HeadMeta. Ceci est commun par exemple avec le
            <ulink url="http://opengraphprotocol.org/">protocole Open Graph</ulink> de Facebook.
        </para>

        <para>
            Par exemple, vous pouvez spécifier un titre et un type de page Open Graph comme ceci&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$this->doctype(Zend_View_Helper_Doctype::XHTML1_RDFA);
$this->headMeta()->setProperty('og:title', 'my article title');
$this->headMeta()->setProperty('og:type', 'article');
echo $this->headMeta();

// l'affichage est :
//   <meta property="og:title" content="my article title" />
//   <meta property="og:type" content="article" />
]]></programlisting>

    </example>
</sect3>