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 HTML <emphasis>&lt;script&gt;</emphasis> element is used to either provide
   8         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             <programlisting language="php"><![CDATA[
  93 // adding scripts
  94 $this->headScript()->appendFile(
  95     '/js/prototype.js',
  96     'text/javascript',
  97     array('conditional' => 'lt IE 7')
  98 );
  99 ]]></programlisting>
 100         </example>
 101     </note>
 102
 103     <para>
 104         <classname>HeadScript</classname> also allows capturing scripts; this can be
 105         useful if you want to create the client-side script programmatically,
 106         and then place it elsewhere. The usage for this will be showed in an
 107         example below.
 108     </para>
 109
 110     <para>
 111         Finally, you can also use the <methodname>headScript()</methodname> method to
 112         quickly add script elements; the signature for this is
 113         <methodname>headScript($mode = 'FILE', $spec, $placement = 'APPEND')</methodname>.
 114         The <varname>$mode</varname> is either 'FILE' or 'SCRIPT', depending on if
 115         you're linking a script or defining one. <varname>$spec</varname> is either
 116         the script file to link or the script source itself.
 117         <varname>$placement</varname> should be either 'APPEND', 'PREPEND', or 'SET'.
 118     </para>
 119
 120     <para>
 121         <classname>HeadScript</classname> overrides each of <methodname>append()</methodname>,
 122         <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, and
 123         <methodname>set()</methodname> to enforce usage of the special methods as listed above.
 124         Internally, it stores each item as a <property>stdClass</property> token, which it later
 125         serializes using the <methodname>itemToString()</methodname> method. This allows you
 126         to perform checks on the items in the stack, and optionally modify these
 127         items by simply modifying the object returned.
 128     </para>
 129
 130     <para>
 131         The <classname>HeadScript</classname> helper is a concrete implementation of the
 132         <link linkend="zend.view.helpers.initial.placeholder">Placeholder helper</link>.
 133     </para>
 134
 135     <note>
 136         <title>Use InlineScript for HTML Body Scripts</title>
 137
 138         <para>
 139             <classname>HeadScript</classname>'s sibling helper, <link
 140                 linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>,
 141             should be used when you wish to include scripts inline in the HTML
 142             <emphasis>body</emphasis>. Placing scripts at the end of your document is a
 143             good practice for speeding up delivery of your page, particularly
 144             when using 3rd party analytics scripts.
 145         </para>
 146     </note>
 147
 148     <note>
 149         <title>Arbitrary Attributes are Disabled by Default</title>
 150
 151         <para>
 152             By default, <classname>HeadScript</classname> only will render
 153             <emphasis>&lt;script&gt;</emphasis> attributes that are blessed by the W3C.
 154             These include 'type', 'charset', 'defer', 'language', and 'src'.
 155             However, some javascript frameworks, notably <ulink
 156                 url="http://www.dojotoolkit.org/">Dojo</ulink>, utilize custom
 157             attributes in order to modify behavior. To allow such attributes,
 158             you can enable them via the
 159             <methodname>setAllowArbitraryAttributes()</methodname> method:
 160         </para>
 161
 162         <programlisting language="php"><![CDATA[
 163 $this->headScript()->setAllowArbitraryAttributes(true);
 164 ]]></programlisting>
 165     </note>
 166
 167     <example id="zend.view.helpers.initial.headscript.basicusage">
 168         <title>HeadScript Helper Basic Usage</title>
 169
 170         <para>
 171             You may specify a new script tag at any time. As noted above, these
 172             may be links to outside resource files or scripts themselves.
 173         </para>
 174
 175         <programlisting language="php"><![CDATA[
 176 // adding scripts
 177 $this->headScript()->appendFile('/js/prototype.js')
 178                    ->appendScript($onloadScript);
 179 ]]></programlisting>
 180
 181         <para>
 182             Order is often important with client-side scripting; you may need to
 183             ensure that libraries are loaded in a specific order due to
 184             dependencies each have; use the various append, prepend, and
 185             offsetSet directives to aid in this task:
 186         </para>
 187
 188         <programlisting language="php"><![CDATA[
 189 // Putting scripts in order
 190
 191 // place at a particular offset to ensure loaded last
 192 $this->headScript()->offsetSetFile(100, '/js/myfuncs.js');
 193
 194 // use scriptaculous effects (append uses next index, 101)
 195 $this->headScript()->appendFile('/js/scriptaculous.js');
 196
 197 // but always have base prototype script load first:
 198 $this->headScript()->prependFile('/js/prototype.js');
 199 ]]></programlisting>
 200
 201         <para>
 202             When you're finally ready to output all scripts in your layout
 203             script, simply echo the helper:
 204         </para>
 205
 206         <programlisting language="php"><![CDATA[
 207 <?php echo $this->headScript() ?>
 208 ]]></programlisting>
 209     </example>
 210
 211     <example id="zend.view.helpers.initial.headscript.capture">
 212         <title>Capturing Scripts Using the HeadScript Helper</title>
 213
 214         <para>
 215             Sometimes you need to generate client-side scripts programmatically.
 216             While you could use string concatenation, heredocs, and the like,
 217             often it's easier just to do so by creating the script and
 218             sprinkling in <acronym>PHP</acronym> tags. <classname>HeadScript</classname> lets you do
 219             just that, capturing it to the stack:
 220         </para>
 221
 222         <programlisting language="php"><![CDATA[
 223 <?php $this->headScript()->captureStart() ?>
 224 var action = '<?php echo $this->baseUrl ?>';
 225 $('foo_form').action = action;
 226 <?php $this->headScript()->captureEnd() ?>
 227 ]]></programlisting>
 228
 229         <para>
 230             The following assumptions are made:
 231         </para>
 232
 233         <itemizedlist>
 234             <listitem>
 235                 <para>
 236                     The script will be appended to the stack. If you wish for it
 237                     to replace the stack or be added to the top, you will need
 238                     to pass 'SET' or 'PREPEND', respectively, as the first
 239                     argument to <methodname>captureStart()</methodname>.
 240                 </para>
 241             </listitem>
 242
 243             <listitem>
 244                 <para>
 245                     The script <acronym>MIME</acronym> type is assumed to be 'text/javascript'; if
 246                     you wish to specify a different type, you will need to pass it
 247                     as the second argument to <methodname>captureStart()</methodname>.
 248                 </para>
 249             </listitem>
 250
 251             <listitem>
 252                 <para>
 253                     If you wish to specify any additional attributes for the
 254                     <emphasis>&lt;script&gt;</emphasis> tag, pass them in an array as
 255                     the third argument to <methodname>captureStart()</methodname>.
 256                 </para>
 257             </listitem>
 258         </itemizedlist>
 259     </example>
 260 </sect3>
 261 <!--
 262 vim:se ts=4 sw=4 et:
 263 -->