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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.view.helpers.initial.headscript">
   4     <title>HeadScript Helper</title>
   5
   6     <para>
   7         The <acronym>HTML</acronym> <emphasis>&lt;script&gt;</emphasis> element is used to either
   8         provide inline client-side scripting elements or link to a remote resource
   9         containing client-side scripting code. The <classname>HeadScript</classname>
  10         helper allows you to manage both.
  11     </para>
  12
  13     <para>
  14         The <classname>HeadScript</classname> helper supports the following methods for
  15         setting and adding scripts:
  16     </para>
  17
  18     <itemizedlist>
  19         <listitem>
  20             <para>
  21                 <command>appendFile($src, $type = 'text/javascript', $attrs = array())</command>
  22             </para>
  23         </listitem>
  24
  25         <listitem>
  26             <para>
  27                 <command>offsetSetFile($index, $src, $type = 'text/javascript', $attrs =
  28                     array())</command>
  29             </para>
  30         </listitem>
  31
  32         <listitem>
  33             <para>
  34                 <command>prependFile($src, $type = 'text/javascript', $attrs = array())</command>
  35             </para>
  36         </listitem>
  37
  38         <listitem>
  39             <para>
  40                 <command>setFile($src, $type = 'text/javascript', $attrs = array())</command>
  41             </para>
  42         </listitem>
  43
  44         <listitem>
  45             <para>
  46                 <command>appendScript($script, $type = 'text/javascript', $attrs =
  47                     array())</command>
  48             </para>
  49         </listitem>
  50
  51         <listitem>
  52             <para>
  53                 <command>offsetSetScript($index, $script, $type = 'text/javascript', $attrs =
  54                     array())</command>
  55             </para>
  56         </listitem>
  57
  58         <listitem>
  59             <para>
  60                 <command>prependScript($script, $type = 'text/javascript', $attrs =
  61                     array())</command>
  62             </para>
  63         </listitem>
  64
  65         <listitem>
  66             <para>
  67                 <command>setScript($script, $type = 'text/javascript', $attrs = array())</command>
  68             </para>
  69         </listitem>
  70     </itemizedlist>
  71
  72     <para>
  73         In the case of the *<methodname>File()</methodname> methods, <varname>$src</varname> is
  74         the remote location of the script to load; this is usually in the form
  75         of a <acronym>URL</acronym> or a path. For the *<methodname>Script()</methodname> methods,
  76         <varname>$script</varname> is the client-side scripting directives you wish to
  77         use in the element.
  78     </para>
  79
  80     <note>
  81         <title>Setting Conditional Comments</title>
  82
  83         <para>
  84             <classname>HeadScript</classname> allows you to wrap the script tag in conditional
  85             comments, which allows you to hide it from specific browsers. To add the conditional
  86             tags, pass the conditional value as part of the <varname>$attrs</varname> parameter in
  87             the method calls.
  88         </para>
  89
  90         <example id="zend.view.helpers.initial.headscript.conditional">
  91             <title>Headscript With Conditional Comments</title>
  92
  93             <programlisting language="php"><![CDATA[
  94 // adding scripts
  95 $this->headScript()->appendFile(
  96     '/js/prototype.js',
  97     'text/javascript',
  98     array('conditional' => 'lt IE 7')
  99 );
 100 ]]></programlisting>
 101         </example>
 102     </note>
 103
 104     <para>
 105         <classname>HeadScript</classname> also allows capturing scripts; this can be
 106         useful if you want to create the client-side script programmatically,
 107         and then place it elsewhere. The usage for this will be showed in an
 108         example below.
 109     </para>
 110
 111     <para>
 112         Finally, you can also use the <methodname>headScript()</methodname> method to
 113         quickly add script elements; the signature for this is
 114         <methodname>headScript($mode = 'FILE', $spec, $placement = 'APPEND')</methodname>.
 115         The <varname>$mode</varname> is either 'FILE' or 'SCRIPT', depending on if
 116         you're linking a script or defining one. <varname>$spec</varname> is either
 117         the script file to link or the script source itself.
 118         <varname>$placement</varname> should be either 'APPEND', 'PREPEND', or 'SET'.
 119     </para>
 120
 121     <para>
 122         <classname>HeadScript</classname> overrides each of <methodname>append()</methodname>,
 123         <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, and
 124         <methodname>set()</methodname> to enforce usage of the special methods as listed above.
 125         Internally, it stores each item as a <property>stdClass</property> token, which it later
 126         serializes using the <methodname>itemToString()</methodname> method. This allows you
 127         to perform checks on the items in the stack, and optionally modify these
 128         items by simply modifying the object returned.
 129     </para>
 130
 131     <para>
 132         The <classname>HeadScript</classname> helper is a concrete implementation of the
 133         <link linkend="zend.view.helpers.initial.placeholder">Placeholder helper</link>.
 134     </para>
 135
 136     <note>
 137         <title>Use InlineScript for HTML Body Scripts</title>
 138
 139         <para>
 140             <classname>HeadScript</classname>'s sibling helper, <link
 141                 linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>,
 142             should be used when you wish to include scripts inline in the <acronym>HTML</acronym>
 143             <emphasis>body</emphasis>. Placing scripts at the end of your document is a
 144             good practice for speeding up delivery of your page, particularly
 145             when using 3rd party analytics scripts.
 146         </para>
 147     </note>
 148
 149     <note>
 150         <title>Arbitrary Attributes are Disabled by Default</title>
 151
 152         <para>
 153             By default, <classname>HeadScript</classname> only will render
 154             <emphasis>&lt;script&gt;</emphasis> attributes that are blessed by the W3C.
 155             These include 'type', 'charset', 'defer', 'language', and 'src'.
 156             However, some javascript frameworks, notably <ulink
 157                 url="http://www.dojotoolkit.org/">Dojo</ulink>, utilize custom
 158             attributes in order to modify behavior. To allow such attributes,
 159             you can enable them via the
 160             <methodname>setAllowArbitraryAttributes()</methodname> method:
 161         </para>
 162
 163         <programlisting language="php"><![CDATA[
 164 $this->headScript()->setAllowArbitraryAttributes(true);
 165 ]]></programlisting>
 166     </note>
 167
 168     <example id="zend.view.helpers.initial.headscript.basicusage">
 169         <title>HeadScript Helper Basic Usage</title>
 170
 171         <para>
 172             You may specify a new script tag at any time. As noted above, these
 173             may be links to outside resource files or scripts themselves.
 174         </para>
 175
 176         <programlisting language="php"><![CDATA[
 177 // adding scripts
 178 $this->headScript()->appendFile('/js/prototype.js')
 179                    ->appendScript($onloadScript);
 180 ]]></programlisting>
 181
 182         <para>
 183             Order is often important with client-side scripting; you may need to
 184             ensure that libraries are loaded in a specific order due to
 185             dependencies each have; use the various append, prepend, and
 186             offsetSet directives to aid in this task:
 187         </para>
 188
 189         <programlisting language="php"><![CDATA[
 190 // Putting scripts in order
 191
 192 // place at a particular offset to ensure loaded last
 193 $this->headScript()->offsetSetFile(100, '/js/myfuncs.js');
 194
 195 // use scriptaculous effects (append uses next index, 101)
 196 $this->headScript()->appendFile('/js/scriptaculous.js');
 197
 198 // but always have base prototype script load first:
 199 $this->headScript()->prependFile('/js/prototype.js');
 200 ]]></programlisting>
 201
 202         <para>
 203             When you're finally ready to output all scripts in your layout
 204             script, simply echo the helper:
 205         </para>
 206
 207         <programlisting language="php"><![CDATA[
 208 <?php echo $this->headScript() ?>
 209 ]]></programlisting>
 210     </example>
 211
 212     <example id="zend.view.helpers.initial.headscript.capture">
 213         <title>Capturing Scripts Using the HeadScript Helper</title>
 214
 215         <para>
 216             Sometimes you need to generate client-side scripts programmatically.
 217             While you could use string concatenation, heredocs, and the like,
 218             often it's easier just to do so by creating the script and
 219             sprinkling in <acronym>PHP</acronym> tags. <classname>HeadScript</classname> lets you do
 220             just that, capturing it to the stack:
 221         </para>
 222
 223         <programlisting language="php"><![CDATA[
 224 <?php $this->headScript()->captureStart() ?>
 225 var action = '<?php echo $this->baseUrl ?>';
 226 $('foo_form').action = action;
 227 <?php $this->headScript()->captureEnd() ?>
 228 ]]></programlisting>
 229
 230         <para>
 231             The following assumptions are made:
 232         </para>
 233
 234         <itemizedlist>
 235             <listitem>
 236                 <para>
 237                     The script will be appended to the stack. If you wish for it
 238                     to replace the stack or be added to the top, you will need
 239                     to pass 'SET' or 'PREPEND', respectively, as the first
 240                     argument to <methodname>captureStart()</methodname>.
 241                 </para>
 242             </listitem>
 243
 244             <listitem>
 245                 <para>
 246                     The script <acronym>MIME</acronym> type is assumed to be 'text/javascript'; if
 247                     you wish to specify a different type, you will need to pass it
 248                     as the second argument to <methodname>captureStart()</methodname>.
 249                 </para>
 250             </listitem>
 251
 252             <listitem>
 253                 <para>
 254                     If you wish to specify any additional attributes for the
 255                     <emphasis>&lt;script&gt;</emphasis> tag, pass them in an array as
 256                     the third argument to <methodname>captureStart()</methodname>.
 257                 </para>
 258             </listitem>
 259         </itemizedlist>
 260     </example>
 261 </sect3>
 262 <!--
 263 vim:se ts=4 sw=4 et:
 264 -->