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

<!-- EN-Revision: 14463 -->
<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><code>setFile($src, $type = 'text/javascript', $attrs = array())</code></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>, <code>$src</code> est l'emplacement distant du script à
    charger ; c'est généralement sous la forme d'une URL ou d'un chemin de fichier. Pour les méthode de type
    <code>*Script()</code>, <code>$script</code> 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 <code>$attrs</code> 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 role="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 <code>headScript()</code> pour rapidement ajouter des éléments de
    script ; le prototype dans ce cas est <code>headScript($mode = 'FILE', $spec, $placement = 'APPEND')</code>. Le
    <code>$mode</code> est soit "FILE", soit "SCRIPT", suivant si vous liez un script ou que vous en définissiez un.
    <code>$spec</code> est soit le script à lier ou la source du script elle-même. <code>$placement</code> est "APPEND",
    "PREPEND", ou "SET".</para>

    <para><code>HeadScript</code> surcharge chacun des <code>append()</code>, <code>offsetSet()</code>,
    <code>prepend()</code>, et <code>set()</code> 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 <code>itemToString()</code>. 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
        <code>setAllowArbitraryAttributes()</code> :</para>

        <programlisting role="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 role="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 role="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 role="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 PHP. <code>HeadScript</code> vous permet de le faire, et
        capture ainsi l'élément dans la pile :</para>

        <programlisting role="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 <code>captureStart()</code>.</para>
            </listitem>

            <listitem>
                <para>Le type MIME 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 <code>captureStart()</code>.</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
                <code>captureStart()</code>.</para>
            </listitem>
        </itemizedlist>
    </example>
</sect3>