repo_zf1/documentation/manual/ru/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>
        HTML-элемент <code>&lt;script&gt;</code> используется для добавления
        скриптового кода, исполняемого на клиентской стороне, как
        непосредственно в документ, так и через ссылки на удаленные ресурсы,
        содержащие этот код. Помощник <code>HeadScript</code> позволяет
        использовать оба способа включения.
    </para>

    <para>
        Помощник <code>HeadScript</code> поддерживает следующие методы для
        установки и добавления скриптов:
    </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>
        В методах <code>*File()</code> через параметр <varname>$src</varname>
        указывается местоположение скрипта, который требуется загрузить; обычно
        оно указывется в виде URL или пути к нему.
        В методах <code>*Script()</code> через параметр <varname>$script</varname>
        передается скриптовый код, который требуется включить в
        элемент <code>&lt;script&gt;</code>.
    </para>

    <note>
        <title>Установка условных комментариев</title>

        <para>
            <code>HeadScript</code> поддерживает включение тега в условные
            комментарии с тем, чтобы скрыть его от определенных
            браузеров. Для того, чтобы добавить условные теги,
            передавайте условие через параметр
            <varname>$attrs</varname> в вызове метода, как показано в примере:
        </para>

        <example id="zend.view.helpers.initial.headscript.conditional">
            <title>Скрипты с условными комментариями</title>
            <programlisting language="php"><![CDATA[
// добавление скриптов
$this->headScript()->appendFile(
    '/js/prototype.js',
    'text/javascript',
    array('conditional' => 'lt IE 7')
);
]]></programlisting>
        </example>
    </note>

    <para>
        <code>HeadScript</code> также позволяет "захватывать" вывод скриптов;
        это может быть полезным при создании скриптов
        программным способом. Пример использования этой возможности будут
        показан ниже.
    </para>

    <para>
        Для быстрого добавления скриптовых элементов Вы можете использовать
        метод <code>headScript()</code>, сигнатура этого метода -
        <code>headScript($mode = 'FILE', $spec, $placement = 'APPEND')</code>.
        Параметр <varname>$mode</varname> может иметь значение 'FILE' или 'SCRIPT',
        в зависимости от того, ссылаетесь ли вы на уже существующий скрипт или
        передаете код для влючения в элемент
        <code>&lt;script&gt;</code>. <varname>$spec</varname> содержит либо путь к
        файлу, к которому нужно добавить ссылку, либо сам скриптовый код.
        <varname>$placement</varname> должен иметь одно из следующих значений:
        'APPEND', 'PREPEND' или 'SET'.
    </para>

    <para>
        <code>HeadScript</code> перегружает методы <code>append()</code>,
        <code>offsetSet()</code>, <code>prepend()</code> и <code>set()</code>
        с целью принудительного использования специальных методов, перечисленных
        выше. Внутри себя помощник сохраняет каждый элемент в виде маркера
        <code>stdClass</code>, который затем преобразовывается в строку через
        метод <code>itemToString()</code>. Это позволяет производить проверку
        элементов в стеке и при необходимости модифицировать их, просто
        извлекая объект и изменяя его.
    </para>

    <para>
        Помощник <code>HeadScript</code> является частной реализацией 
        <link linkend="zend.view.helpers.initial.placeholder">помощника
            Placeholder</link>.
    </para>

    <note>
        <title>Используйте InlineScript для скриптов в теле документа</title>

        <para>
            Для добавления скриптов внутри HTML-элемента <code>body</code>
            должен использоваться
            родственный помощник <link
                linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>.
            Помещение скриптов в конец документа является хорошей практикой
            для повышения скорости отдачи страницы, особенно если используются
            сторонние скрипты-аналитики.
        </para>
    </note>

    <note>
        <title>Установка произвольных атрибутов по умолчанию отключена</title>

        <para>
            По умолчанию <code>HeadScript</code> будет генерировать только
            атрибуты, соответствующие спецификации W3C.
            В список этих атрибутов входят 'type', 'charset', 'defer',
            'language' и 'src'. Однако некоторые JavaScript фреймворки,
            а в особенности <ulink url="http://www.dojotoolkit.org/">Dojo</ulink>,
            используют специальные атрибуты в целях изменения поведения. Вы
            можете разрешить использование таких атрибутов, воспользовавшись
            методом <code>setAllowArbitraryAttributes()</code>:
        </para>

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

    <example id="zend.view.helpers.initial.headscript.basicusage">
        <title>Использование помощника HeadScript</title>

        <para>
            Вы можете указывать скрипты для добавления в документ в любой момент
            времени. Как было указано ранее, это могут быть как ссылки на
            файлы со скриптами, так и сами скрипты.
        </para>

        <programlisting language="php"><![CDATA[
// добавление скриптов
$this->headScript()->appendFile('/js/prototype.js')
                   ->appendScript($onloadScript);
]]></programlisting>

        <para>
            Порядок следования часто важен в скриптах, интерпретируемых на
            стороне клиента - например, нужно быть уверенным в том, что
            библиотеки загружаются в порядке, обусловленном
            зависимостями между ними. В этом случае используйте специальные
            методы методы для добавления в начало, конец, и по определенному
            смещению:
        </para>

        <programlisting language="php"><![CDATA[
// Размещение скриптов в определенном порядке

// Добавление по определенному смещению
$this->headScript()->offsetSetFile(100, '/js/myfuncs.js');

// Используем эффекты из библиотеки script.aculo.us
// (будет добавлена с использованием следующего смещения, 101)
$this->headScript()->appendFile('/js/scriptaculous.js');

// Но скрипт prototype всегда должен загружаться первым:
$this->headScript()->prependFile('/js/prototype.js');
]]></programlisting>

        <para>
            Когда все будет готово для размещения скриптов в макете, просто
            "выводите" помощника:
        </para>

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

    <example id="zend.view.helpers.initial.headscript.capture">
        <title>Составление скриптов с использованием помощника HeadScript</title>

        <para>
            Иногда нужно генерировать скрипты программым способом.
            Хотя вы можете использовать конкатенацию строк, синтаксис heredoc
            и т.п., часто бывает легче создать скрипт с включением PHP-тегов.
            <code>HeadScript</code> позволяет делать это, захватывая
            вывод в стек:
        </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>
            Используются следующие допущения:
        </para>

        <itemizedlist>
            <listitem><para>
                    Скрипт будет добавлен в конец стека. Если требуется
                    переопределить содержимое стека или добавить скрипт в
                    конец стека, то передавайте соответственно
                    'SET' или 'PREPEND' в качестве первого аргумента
                    <code>captureStart()</code>.
            </para></listitem>

            <listitem><para>
                    По умолчанию предполагается, что MIME-тип скрипта -
                    'text/javascript'. Если требуется указать другой тип
                    скрипта, то передавайте его в качестве второго аргумента
                    <code>captureStart()</code>.
            </para></listitem>

            <listitem><para>
                    Если вы хотите указать какие-либо дополнительные аргументы
                    для тега <code>&lt;script&gt;</code>, то передавайте их
                    в массиве в качестве третьего аргумента
                    <code>captureStart()</code>.
            </para></listitem>
        </itemizedlist>
    </example>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->