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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.view.helpers.initial.headscript">
    <title>HeadScript Helper</title>

    <para>
        The <acronym>HTML</acronym> <emphasis>&lt;script&gt;</emphasis> element is used to either
        provide inline client-side scripting elements or link to a remote resource
        containing client-side scripting code. The <classname>HeadScript</classname>
        helper allows you to manage both.
    </para>

    <para>
        The <classname>HeadScript</classname> helper supports the following methods for
        setting and adding scripts:
    </para>

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

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

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

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

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

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

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

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

    <para>
        In the case of the *<methodname>File()</methodname> methods, <varname>$src</varname> is
        the remote location of the script to load; this is usually in the form
        of a <acronym>URL</acronym> or a path. For the *<methodname>Script()</methodname> methods,
        <varname>$script</varname> is the client-side scripting directives you wish to
        use in the element.
    </para>

    <note>
        <title>Setting Conditional Comments</title>

        <para>
            <classname>HeadScript</classname> allows you to wrap the script tag in conditional
            comments, which allows you to hide it from specific browsers. To add the conditional
            tags, pass the conditional value as part of the <varname>$attrs</varname> parameter in
            the method calls.
        </para>

        <example id="zend.view.helpers.initial.headscript.conditional">
            <title>Headscript With Conditional Comments</title>

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

    <note>
        <title>Preventing HTML style comments or CDATA wrapping of scripts</title>

        <para>
            By default <classname>HeadScript</classname> will wrap scripts with HTML
            comments or it wraps scripts with XHTML cdata. This behavior can be
            problematic when you intend to use the script tag in an alternative way by
            setting the type to something other then 'text/javascript'. To prevent such
            escaping, pass an <varname>noescape</varname> with a value of true as part of
            the <varname>$attrs</varname> parameter in the method calls.
        </para>

        <example id="zend.view.helpers.initial.headscript.noescape">
            <title>Create an jQuery template with the headScript</title>

            <programlisting language="php"><![CDATA[
// jquery template
$template = '<div class="book">{{:title}}</div>';
$this->headScript()->appendScript(
    $template,
    'text/x-jquery-tmpl',
    array('id='tmpl-book', 'noescape' => true)
);
]]></programlisting>
        </example>
    </note>

    <para>
        <classname>HeadScript</classname> also allows capturing scripts; this can be
        useful if you want to create the client-side script programmatically,
        and then place it elsewhere. The usage for this will be showed in an
        example below.
    </para>

    <para>
        Finally, you can also use the <methodname>headScript()</methodname> method to
        quickly add script elements; the signature for this is
        <methodname>headScript($mode = 'FILE', $spec, $placement = 'APPEND')</methodname>.
        The <varname>$mode</varname> is either 'FILE' or 'SCRIPT', depending on if
        you're linking a script or defining one. <varname>$spec</varname> is either
        the script file to link or the script source itself.
        <varname>$placement</varname> should be either 'APPEND', 'PREPEND', or 'SET'.
    </para>

    <para>
        <classname>HeadScript</classname> overrides each of <methodname>append()</methodname>,
        <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, and
        <methodname>set()</methodname> to enforce usage of the special methods as listed above.
        Internally, it stores each item as a <property>stdClass</property> token, which it later
        serializes using the <methodname>itemToString()</methodname> method. This allows you
        to perform checks on the items in the stack, and optionally modify these
        items by simply modifying the object returned.
    </para>

    <para>
        The <classname>HeadScript</classname> helper is a concrete implementation of the
        <link linkend="zend.view.helpers.initial.placeholder">Placeholder helper</link>.
    </para>

    <note>
        <title>Use InlineScript for HTML Body Scripts</title>

        <para>
            <classname>HeadScript</classname>'s sibling helper, <link
                linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>,
            should be used when you wish to include scripts inline in the <acronym>HTML</acronym>
            <emphasis>body</emphasis>. Placing scripts at the end of your document is a
            good practice for speeding up delivery of your page, particularly
            when using 3rd party analytics scripts.
        </para>
    </note>

    <note>
        <title>Arbitrary Attributes are Disabled by Default</title>

        <para>
            By default, <classname>HeadScript</classname> only will render
            <emphasis>&lt;script&gt;</emphasis> attributes that are blessed by the W3C.
            These include 'type', 'charset', 'defer', 'language', and 'src'.
            However, some javascript frameworks, notably <ulink
                url="http://www.dojotoolkit.org/">Dojo</ulink>, utilize custom
            attributes in order to modify behavior. To allow such attributes,
            you can enable them via the
            <methodname>setAllowArbitraryAttributes()</methodname> method:
        </para>

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

    <example id="zend.view.helpers.initial.headscript.basicusage">
        <title>HeadScript Helper Basic Usage</title>

        <para>
            You may specify a new script tag at any time. As noted above, these
            may be links to outside resource files or scripts themselves.
        </para>

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

        <para>
            Order is often important with client-side scripting; you may need to
            ensure that libraries are loaded in a specific order due to
            dependencies each have; use the various append, prepend, and
            offsetSet directives to aid in this task:
        </para>

        <programlisting language="php"><![CDATA[
// Putting scripts in order

// place at a particular offset to ensure loaded last
$this->headScript()->offsetSetFile(100, '/js/myfuncs.js');

// use scriptaculous effects (append uses next index, 101)
$this->headScript()->appendFile('/js/scriptaculous.js');

// but always have base prototype script load first:
$this->headScript()->prependFile('/js/prototype.js');
]]></programlisting>

        <para>
            When you're finally ready to output all scripts in your layout
            script, simply echo the helper:
        </para>

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

    <example id="zend.view.helpers.initial.headscript.capture">
        <title>Capturing Scripts Using the HeadScript Helper</title>

        <para>
            Sometimes you need to generate client-side scripts programmatically.
            While you could use string concatenation, heredocs, and the like,
            often it's easier just to do so by creating the script and
            sprinkling in <acronym>PHP</acronym> tags. <classname>HeadScript</classname> lets you do
            just that, capturing it to the stack:
        </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>
            The following assumptions are made:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    The script will be appended to the stack. If you wish for it
                    to replace the stack or be added to the top, you will need
                    to pass 'SET' or 'PREPEND', respectively, as the first
                    argument to <methodname>captureStart()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    The script <acronym>MIME</acronym> type is assumed to be 'text/javascript'; if
                    you wish to specify a different type, you will need to pass it
                    as the second argument to <methodname>captureStart()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    If you wish to specify any additional attributes for the
                    <emphasis>&lt;script&gt;</emphasis> tag, pass them in an array as
                    the third argument to <methodname>captureStart()</methodname>.
                </para>
            </listitem>
        </itemizedlist>
    </example>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->