documentation/manual/ru/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         HTML-элемент <code>&lt;script&gt;</code> используется для добавления
   8         скриптового кода, исполняемого на клиентской стороне, как
   9         непосредственно в документ, так и через ссылки на удаленные ресурсы,
  10         содержащие этот код. Помощник <code>HeadScript</code> позволяет
  11         использовать оба способа включения.
  12     </para>
  13
  14     <para>
  15         Помощник <code>HeadScript</code> поддерживает следующие методы для
  16         установки и добавления скриптов:
  17     </para>
  18
  19     <itemizedlist>
  20         <listitem><para><code>appendFile($src, $type = 'text/javascript',
  21                     $attrs = array())</code></para></listitem>
  22         <listitem><para><code>offsetSetFile($index, $src, $type = 'text/javascript',
  23                     $attrs = array())</code></para></listitem>
  24         <listitem><para><code>prependFile($src, $type = 'text/javascript',
  25                     $attrs = array())</code></para></listitem>
  26         <listitem><para><code>setFile($src, $type = 'text/javascript',
  27                     $attrs = array())</code></para></listitem>
  28         <listitem><para><code>appendScript($script, $type = 'text/javascript',
  29                     $attrs = array())</code></para></listitem>
  30         <listitem><para><code>offsetSetScript($index, $script, $type = 'text/javascript',
  31                     $attrs = array())</code></para></listitem>
  32         <listitem><para><code>prependScript($script, $type = 'text/javascript',
  33                     $attrs = array())</code></para></listitem>
  34         <listitem><para><code>setScript($script, $type = 'text/javascript',
  35                     $attrs = array())</code></para></listitem>
  36     </itemizedlist>
  37
  38     <para>
  39         В методах <code>*File()</code> через параметр <varname>$src</varname>
  40         указывается местоположение скрипта, который требуется загрузить; обычно
  41         оно указывется в виде URL или пути к нему.
  42         В методах <code>*Script()</code> через параметр <varname>$script</varname>
  43         передается скриптовый код, который требуется включить в
  44         элемент <code>&lt;script&gt;</code>.
  45     </para>
  46
  47     <note>
  48         <title>Установка условных комментариев</title>
  49
  50         <para>
  51             <code>HeadScript</code> поддерживает включение тега в условные
  52             комментарии с тем, чтобы скрыть его от определенных
  53             браузеров. Для того, чтобы добавить условные теги,
  54             передавайте условие через параметр
  55             <varname>$attrs</varname> в вызове метода, как показано в примере:
  56         </para>
  57
  58         <example id="zend.view.helpers.initial.headscript.conditional">
  59             <title>Скрипты с условными комментариями</title>
  60             <programlisting language="php"><![CDATA[
  61 // добавление скриптов
  62 $this->headScript()->appendFile(
  63     '/js/prototype.js',
  64     'text/javascript',
  65     array('conditional' => 'lt IE 7')
  66 );
  67 ]]></programlisting>
  68         </example>
  69     </note>
  70
  71     <para>
  72         <code>HeadScript</code> также позволяет "захватывать" вывод скриптов;
  73         это может быть полезным при создании скриптов
  74         программным способом. Пример использования этой возможности будут
  75         показан ниже.
  76     </para>
  77
  78     <para>
  79         Для быстрого добавления скриптовых элементов Вы можете использовать
  80         метод <code>headScript()</code>, сигнатура этого метода -
  81         <code>headScript($mode = 'FILE', $spec, $placement = 'APPEND')</code>.
  82         Параметр <varname>$mode</varname> может иметь значение 'FILE' или 'SCRIPT',
  83         в зависимости от того, ссылаетесь ли вы на уже существующий скрипт или
  84         передаете код для влючения в элемент
  85         <code>&lt;script&gt;</code>. <varname>$spec</varname> содержит либо путь к
  86         файлу, к которому нужно добавить ссылку, либо сам скриптовый код.
  87         <varname>$placement</varname> должен иметь одно из следующих значений:
  88         'APPEND', 'PREPEND' или 'SET'.
  89     </para>
  90
  91     <para>
  92         <code>HeadScript</code> перегружает методы <code>append()</code>,
  93         <code>offsetSet()</code>, <code>prepend()</code> и <code>set()</code>
  94         с целью принудительного использования специальных методов, перечисленных
  95         выше. Внутри себя помощник сохраняет каждый элемент в виде маркера
  96         <code>stdClass</code>, который затем преобразовывается в строку через
  97         метод <code>itemToString()</code>. Это позволяет производить проверку
  98         элементов в стеке и при необходимости модифицировать их, просто
  99         извлекая объект и изменяя его.
 100     </para>
 101
 102     <para>
 103         Помощник <code>HeadScript</code> является частной реализацией
 104         <link linkend="zend.view.helpers.initial.placeholder">помощника
 105             Placeholder</link>.
 106     </para>
 107
 108     <note>
 109         <title>Используйте InlineScript для скриптов в теле документа</title>
 110
 111         <para>
 112             Для добавления скриптов внутри HTML-элемента <code>body</code>
 113             должен использоваться
 114             родственный помощник <link
 115                 linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>.
 116             Помещение скриптов в конец документа является хорошей практикой
 117             для повышения скорости отдачи страницы, особенно если используются
 118             сторонние скрипты-аналитики.
 119         </para>
 120     </note>
 121
 122     <note>
 123         <title>Установка произвольных атрибутов по умолчанию отключена</title>
 124
 125         <para>
 126             По умолчанию <code>HeadScript</code> будет генерировать только
 127             атрибуты, соответствующие спецификации W3C.
 128             В список этих атрибутов входят 'type', 'charset', 'defer',
 129             'language' и 'src'. Однако некоторые JavaScript фреймворки,
 130             а в особенности <ulink url="http://www.dojotoolkit.org/">Dojo</ulink>,
 131             используют специальные атрибуты в целях изменения поведения. Вы
 132             можете разрешить использование таких атрибутов, воспользовавшись
 133             методом <code>setAllowArbitraryAttributes()</code>:
 134         </para>
 135
 136         <programlisting language="php"><![CDATA[
 137 $this->headScript()->setAllowArbitraryAttributes(true);
 138 ]]></programlisting>
 139     </note>
 140
 141     <example id="zend.view.helpers.initial.headscript.basicusage">
 142         <title>Использование помощника HeadScript</title>
 143
 144         <para>
 145             Вы можете указывать скрипты для добавления в документ в любой момент
 146             времени. Как было указано ранее, это могут быть как ссылки на
 147             файлы со скриптами, так и сами скрипты.
 148         </para>
 149
 150         <programlisting language="php"><![CDATA[
 151 // добавление скриптов
 152 $this->headScript()->appendFile('/js/prototype.js')
 153                    ->appendScript($onloadScript);
 154 ]]></programlisting>
 155
 156         <para>
 157             Порядок следования часто важен в скриптах, интерпретируемых на
 158             стороне клиента - например, нужно быть уверенным в том, что
 159             библиотеки загружаются в порядке, обусловленном
 160             зависимостями между ними. В этом случае используйте специальные
 161             методы методы для добавления в начало, конец, и по определенному
 162             смещению:
 163         </para>
 164
 165         <programlisting language="php"><![CDATA[
 166 // Размещение скриптов в определенном порядке
 167
 168 // Добавление по определенному смещению
 169 $this->headScript()->offsetSetFile(100, '/js/myfuncs.js');
 170
 171 // Используем эффекты из библиотеки script.aculo.us
 172 // (будет добавлена с использованием следующего смещения, 101)
 173 $this->headScript()->appendFile('/js/scriptaculous.js');
 174
 175 // Но скрипт prototype всегда должен загружаться первым:
 176 $this->headScript()->prependFile('/js/prototype.js');
 177 ]]></programlisting>
 178
 179         <para>
 180             Когда все будет готово для размещения скриптов в макете, просто
 181             "выводите" помощника:
 182         </para>
 183
 184         <programlisting language="php"><![CDATA[
 185 <?php echo $this->headScript() ?>
 186 ]]></programlisting>
 187     </example>
 188
 189     <example id="zend.view.helpers.initial.headscript.capture">
 190         <title>Составление скриптов с использованием помощника HeadScript</title>
 191
 192         <para>
 193             Иногда нужно генерировать скрипты программым способом.
 194             Хотя вы можете использовать конкатенацию строк, синтаксис heredoc
 195             и т.п., часто бывает легче создать скрипт с включением PHP-тегов.
 196             <code>HeadScript</code> позволяет делать это, захватывая
 197             вывод в стек:
 198         </para>
 199
 200         <programlisting language="php"><![CDATA[
 201 <?php $this->headScript()->captureStart() ?>
 202 var action = '<?php echo $this->baseUrl ?>';
 203 $('foo_form').action = action;
 204 <?php $this->headScript()->captureEnd() ?>
 205 ]]></programlisting>
 206
 207         <para>
 208             Используются следующие допущения:
 209         </para>
 210
 211         <itemizedlist>
 212             <listitem><para>
 213                     Скрипт будет добавлен в конец стека. Если требуется
 214                     переопределить содержимое стека или добавить скрипт в
 215                     конец стека, то передавайте соответственно
 216                     'SET' или 'PREPEND' в качестве первого аргумента
 217                     <code>captureStart()</code>.
 218             </para></listitem>
 219
 220             <listitem><para>
 221                     По умолчанию предполагается, что MIME-тип скрипта -
 222                     'text/javascript'. Если требуется указать другой тип
 223                     скрипта, то передавайте его в качестве второго аргумента
 224                     <code>captureStart()</code>.
 225             </para></listitem>
 226
 227             <listitem><para>
 228                     Если вы хотите указать какие-либо дополнительные аргументы
 229                     для тега <code>&lt;script&gt;</code>, то передавайте их
 230                     в массиве в качестве третьего аргумента
 231                     <code>captureStart()</code>.
 232             </para></listitem>
 233         </itemizedlist>
 234     </example>
 235 </sect3>
 236 <!--
 237 vim:se ts=4 sw=4 et:
 238 -->