# Помощник HeadScript Helper

HTML-элемент `<script>` используется для добавления скриптового кода, исполняемого на клиентской стороне, как непосредственно в документ, так и через ссылки на удаленные ресурсы, содержащие этот код. Помощник `HeadScript` позволяет использовать оба способа включения.

Помощник `HeadScript` поддерживает следующие методы для установки и добавления скриптов:

- `appendFile($src, $type = 'text/javascript', $attrs = array())`

- `offsetSetFile($index, $src, $type = 'text/javascript', $attrs = array())`

- `prependFile($src, $type = 'text/javascript', $attrs = array())`

- `setFile($src, $type = 'text/javascript', $attrs = array())`

- `appendScript($script, $type = 'text/javascript', $attrs = array())`

- `offsetSetScript($index, $script, $type = 'text/javascript', $attrs = array())`

- `prependScript($script, $type = 'text/javascript', $attrs = array())`

- `setScript($script, $type = 'text/javascript', $attrs = array())`

В методах `*File()` через параметр `$src` указывается местоположение скрипта, который требуется загрузить; обычно оно указывется в виде URL или пути к нему. В методах `*Script()` через параметр `$script` передается скриптовый код, который требуется включить в элемент `<script>`.

## Установка условных комментариев

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

## Скрипты с условными комментариями

    // добавление скриптов
    $this->headScript()->appendFile(
        '/js/prototype.js',
        'text/javascript',
        array('conditional' => 'lt IE 7')
    );

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

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

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

Помощник `HeadScript` является частной реализацией помощника Placeholder.

## Используйте InlineScript для скриптов в теле документа

Для добавления скриптов внутри HTML-элемента `body` должен использоваться родственный помощник InlineScript. Помещение скриптов в конец документа является хорошей практикой для повышения скорости отдачи страницы, особенно если используются сторонние скрипты-аналитики.

## Установка произвольных атрибутов по умолчанию отключена

По умолчанию `HeadScript` будет генерировать только атрибуты, соответствующие спецификации W3C. В список этих атрибутов входят 'type', 'charset', 'defer', 'language' и 'src'. Однако некоторые JavaScript фреймворки, а в особенности Dojo, используют специальные атрибуты в целях изменения поведения. Вы можете разрешить использование таких атрибутов, воспользовавшись методом `setAllowArbitraryAttributes()`:

    $this->headScript()->setAllowArbitraryAttributes(true);

## Использование помощника HeadScript

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

    // добавление скриптов
    $this->headScript()->appendFile('/js/prototype.js')
                       ->appendScript($onloadScript);

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

    // Размещение скриптов в определенном порядке

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

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

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

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

    <?php echo $this->headScript() ?>

## Составление скриптов с использованием помощника HeadScript

Иногда нужно генерировать скрипты программым способом. Хотя вы можете использовать конкатенацию строк, синтаксис heredoc и т.п., часто бывает легче создать скрипт с включением PHP-тегов. `HeadScript` позволяет делать это, захватывая вывод в стек:

    <?php $this->headScript()->captureStart() ?>
    var action = '<?php echo $this->baseUrl ?>';
    $('foo_form').action = action;
    <?php $this->headScript()->captureEnd() ?>

Используются следующие допущения:

- Скрипт будет добавлен в конец стека. Если требуется переопределить содержимое стека или добавить скрипт в конец стека, то передавайте соответственно 'SET' или 'PREPEND' в качестве первого аргумента `captureStart()`.

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

- Если вы хотите указать какие-либо дополнительные аргументы для тега `<script>`, то передавайте их в массиве в качестве третьего аргумента `captureStart()`.