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

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

    <para>
        L'élément HTML <code>&lt;script&gt;</code> est utilisé pour à la fois pour fournir des
        éléments de scripts côté-client dans le code HTML et aussi pour lier une ressource distante
        contenant du script côté-client. L'aide de vue <code>HeadScript</code> vous permet de gérer
        ces deux cas.
    </para>

    <para>
        L'aide de vue <code>HeadScript</code> supportent les méthodes suivantes pour
        paramétrer ou ajouter des scripts :
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <code>appendFile($src, $type = 'text/javascript', $attrs =
                array())</code>
            </para>
        </listitem>

        <listitem>
            <para>
                <code>offsetSetFile($index, $src, $type = 'text/javascript', $attrs =
                array())</code>
            </para>
        </listitem>

        <listitem>
            <para>
                <code>prependFile($src, $type = 'text/javascript', $attrs =
                array())</code>
            </para>
        </listitem>

        <listitem>
            <para><methodname>setFile($src, $type = 'text/javascript', $attrs = array())</methodname></para>
        </listitem>

        <listitem>
            <para>
                <code>appendScript($script, $type = 'text/javascript', $attrs =
                array())</code>
            </para>
        </listitem>

        <listitem>
            <para>
                <code>offsetSetScript($index, $script, $type = 'text/javascript', $attrs =
                array())</code>
            </para>
        </listitem>

        <listitem>
            <para>
                <code>prependScript($script, $type = 'text/javascript', $attrs =
                array())</code>
            </para>
        </listitem>

        <listitem>
            <para>
                <code>setScript($script, $type = 'text/javascript', $attrs =
                array())</code>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Dans le cas des méthodes de type <code>*File()</code>, <varname>$src</varname> est
        l'emplacement distant du script à charger ; c'est généralement sous la forme d'une <acronym>URL</acronym> ou
        d'un chemin de fichier. Pour les méthode de type <code>*Script()</code>,
        <varname>$script</varname> sont les directives de script côté-client que vous souhaitez utiliser
        dans l'élément.
    </para>

    <note>
        <title>Paramétrez des commentaires conditionnels</title>

        <para>
            <code>HeadScript</code> vous permet d'englober vos balises de script avec des
            commentaires conditionnels, ce qui permet de les masquer pour des navigateurs
            spécifiques. Pour ajouter les balises conditionnelles, fournissez le paramètre
            <code>conditional</code> en tant que partie du paramètre <varname>$attrs</varname> lors de
            l'appel de la méthode.
        </para>

        <example id="zend.view.helpers.initial.headscript.conditional">
            <title>Headscript avec des commentaires conditionnels</title>

            <programlisting language="php"><![CDATA[
// adding scripts
$this->headScript()->appendFile('/js/prototype.js',
                                'text/javascript',
                                array('conditional' => 'lt IE 7');
]]></programlisting>
        </example>
    </note>

    <para>
        <code>HeadScript</code> vous permet aussi de capturer des scripts ; ceci peut être
        utile si vous voulez créer du script côté-client par programmation, et ensuite le placer
        n'importe où. Une utilisation de ceci est montré dans un exemple ci-dessous.
    </para>

    <para>
        Enfin, vous pouvez aussi utiliser la méthode <methodname>headScript()</methodname> pour rapidement
        ajouter des éléments de script ; le prototype dans ce cas est <code>headScript($mode =
        'FILE', $spec, $placement = 'APPEND')</code>. Le <varname>$mode</varname> est soit "FILE", soit
        "SCRIPT", suivant si vous liez un script ou que vous en définissiez un. <varname>$spec</varname>
        est soit le script à lier ou la source du script elle-même. <varname>$placement</varname> est
        "APPEND", "PREPEND", ou "SET".
    </para>

    <para>
        <code>HeadScript</code> surcharge chacun des <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 être ensuite sérialisé grâce à la
        méthode <methodname>itemToString()</methodname>. Ceci vous permet de réaliser des vérifications sur les
        éléments dans la pile, et optionnellement de les modifier en modifiant simplement l'objet
        retourné.
    </para>

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

    <note>
        <title>Utilisez InlineScript pour les scripts dans le corps ("body") du HTML</title>

        <para>
            L'aide de vue, <link
            linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>, similaire à
            <code>HeadScript</code> devrait être utilisée quand vous souhaitez inclure des scripts
            dans le corps ("<classname>body</classname>") du HTML. Placer ces scripts en fin du
            document est une bonne pratique pour accélérer l'envoi de votre page, particulièrement
            pour les scripts tiers d'analyse.
        </para>
    </note>

    <note>
        <title>Les attributs arbitraires sont désactivées par défaut</title>

        <para>
            Par défaut, <code>HeadScript</code> affichera seulement les attributs de
            <code>&lt;script&gt;</code> approuvés par le W3C. Ceux-ci inclus "<code>type</code>",
            "<code>charset</code>", "<code>defer</code>", "<code>language</code>", et
            "<code>src</code>". Cependant, certaines bibliothèques javascript, notamment <ulink
            url="http://www.dojotoolkit.org/">Dojo</ulink>, utilise des attributs personnalisés dans
            le but de modifier le comportement. Pour autoriser ce type d'attribut, vous pouvez les
            activer grâce à la méthode <methodname>setAllowArbitraryAttributes()</methodname> :
        </para>

        <programlisting language="php"><![CDATA[
$this->headScript()->setAllowArbitraryAttributes(true);
]]></programlisting>
    </note>

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

        <para>
            Vous devriez ajouter une nouvelle balise de script à chaque fois. Comme noté
            ci-dessus, ceux-ci peuvent être des liens vers des ressources externes ou vers les
            scripts eux-mêmes.
        </para>

        <programlisting language="php"><![CDATA[
// ajout de scripts
$this->headScript()->appendFile('/js/prototype.js')
                   ->appendScript($onloadScript);
]]></programlisting>

        <para>
            L'ordre est souvent important avec les scripts côté-client ; vous devez vous
            assurer de charger les librairies dans un ordre spécifique en fonction de leurs
            dépendances ; utilisez à la fois les directives <code>append</code>,
            <code>prepend</code>, et <code>offsetSet</code> pour vous aider dans cette tâche
            :
        </para>

        <programlisting language="php"><![CDATA[
// mettre les scripts dans l'ordre

// placer celui-ci à un offset particulier pour s'assurer
// de le charger en dernier
$this->headScript()->offsetSetFile(100, '/js/myfuncs.js');

// utiliser les effets de scriptaculous (append utilise
// l'index suivant, c-à-d. 101)
$this->headScript()->appendFile('/js/scriptaculous.js');

// mais dans tous les cas, le script de base prototype
// doit être chargé en premier :
$this->headScript()->prependFile('/js/prototype.js');
]]></programlisting>

        <para>
            Quand vous êtes finalement prêt à afficher tous les scripts dans votre layout,
            faîtes simplement un <code>echo</code> de l'aide :
        </para>

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

    <example id="zend.view.helpers.initial.headscript.capture">
        <title>Capturer les scripts en utilisant l'aide HeadScript</title>

        <para>
            Parfois vous devez générer des scripts côté-client par programme. Même si vous
            pouvez employer la concaténation de chaînes, les "heredocs", ou tout autre équivalent,
            il est souvent plus facile de faire juste la création des scripts et de les entourer par
            des balises <acronym>PHP</acronym>. <code>HeadScript</code> vous permet de le faire, et capture ainsi
            l'élément dans la pile :
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->headScript()->captureStart() ?>
var action = '<?php echo $this->baseUrl ?>';
$('foo_form').action = action;
<?php $this->headScript()->captureEnd() ?>
]]></programlisting>

        <para>Les suppositions suivantes sont considérées :</para>

        <itemizedlist>
            <listitem>
                <para>
                    Les déclarations de scripts sont ajoutées à la pile. Si vous souhaitez
                    qu'elles remplacent la pile ou qu'elles soient ajoutées en début de pile, vous
                    devez fournir "SET" ou "PREPEND", en tant que premier argument de
                    <methodname>captureStart()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Le type <acronym>MIME</acronym> est considéré comme étant "text/javascript" ; si vous
                    souhaitez spécifier un type différent, vous devez le fournir en tant que
                    deuxième argument de <methodname>captureStart()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Si vous souhaitez spécifier un quelconque attribut additionnel pour la
                    balise <code>&lt;script&gt;</code>, fournissez-le sous la forme d'un tableau en
                    troisième argument de <methodname>captureStart()</methodname>.
                </para>
            </listitem>
        </itemizedlist>
    </example>
</sect3>