1. Документация
  2. Для разработчика сайта
  3. Функции и классы
  4. Встроенные классы
  5. Класс Blox

Метод Blox::addToHead() и др.

Blox::addToHead($code, $options)

Назначение метода — добавление кода в раздел head документа.

  • $code — вставляемый код
  • $options = [

    • 'action' =>   Одно из значений:

      • 'replace' — Если такой же код уже был вставлен, старый код будет удален, а новый код будет вставлен. В результате код будет находиться ниже.

      • 'insert' — Если такой же код уже был вставлен, новый код будет все-равно вставлен.

      • 'include' — В качестве параметра $code используется путь к файлу, уже содержимое которого вставляется с помощью include. Данная опция используется когда нужно вставить сразу большое количество строк кода.

    • 'position' =>   Одно из значений:

      • 'top' — Код будет вставлен выше всех остальных кодов, в том числе выше кодов, уже вставленных с помощью этой же опции top.

      • 'bottom' — Код будет вставлен в конец после всех кодов, в том числе ниже кодов, уже вставленных с помощью этой же опции bottom.

      Опция 'position' имеет меньший приоритет, чем опции 'before' и 'after'.

    • 'before' => 'код' — Код или фрагмент кода, по которому будет производиться поиск того кода, выше которого должен встать текущий код ($code).

      Обратите внимание на фразу "фрагмент кода". Это означает, что данный метод может искать код, относительного которого нужно определить свое место, не проверяя весь код целиком — достаточно указать наиболее характерный и уникальный фрагмент. То есть, не нужно даже знать в какой папке лежит соответствующий файл.

    • 'after' => 'код' — Код или фрагмент кода, по которому будет производиться поиск того кода, после которого должен встать текущий код ($code).

    • 'unlike' => ['код1','код2',...] — Фрагмент кода или массив кодов, при наличие которых в уже вставленных кодах, текущий код будет проигнорирован.

    • 'like' => ['код1','код2',...] — Фрагмент кода или массив кодов, которые должны быть вставлены перед текущим кодом, иначе текущий код будет проигнорирован.

      Пример: Переименовать метод tooltip в uitooltip (из jQuery UI) , так как такой же метод уже используется, но он взят из Bootstrap. Данный код вставить только при наличии подключения jQuery UI и только после него.

      Blox::addToHead(
    '<script>$.widget.bridge("uitooltip", $.ui.tooltip)</script>', 
    ['like'=>'jquery-ui.js', 'after'=>'jquery-ui.js']
);

    • 'unmatch' => 'паттерн' — Регулярный паттерн. При наличии кода, подходящего под это паттерн, среди уже вставленных кодов, текущий код будет проигнорирован. Пример: Blox::addToHead('.../jquery.fancybox-1.3.4.js', ['unmatch'=>'/fancybox.*?\.js/']);

    • 'match' => 'паттерн' — Регулярный паттерн. При отсутствии кода, подходящего под это паттерн, среди уже вставленных кодов, текущий код будет проигнорирован.

    • 'minimize' => false — Минимизировать код, то есть заменить множественные пробелы, табуляции и переносы строк на одиночные пробелы. Пример: Blox::addToHead($script, 'minimize');.

      Допустимо использовать опцию в виде строки.

      Перед минимизацией js-кода замените однострочные комменты на многострочные, операторы разделяйте точкой с запятой.

    ];

По умолчанию, когда не используется второй параметр $options (массив с опциями вставки кода), метод Blox::addToHead($code) будет добавлять коды в порядке их поступления. При этом повторяющийся код будет игнорироваться.

Пример: 
Blox::addToHead(
    '<link type="text/css" rel="stylesheet" href="http://blox.ru/style.css" />'
);

Параметр $code — сокращенная форма записи

Основное предназначение метода Blox::addToHead() – это подключение css и js файлов, поэтому для таких случаев существует сокращенная форма записи, без тегов.

Для подключения css или js файла достаточно указывать только URL подключаемого файла (необходимый код припишется автоматически при выводе страницы). Пример: 

Blox::addToHead('http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js');
Blox::addToHead('http://jqueryui.com/web-base-template/themes/jquery/css/base.css');

Можно использовать как относительный, так и абсолютный URL файлов. В любом случае, URL будут приведены к абсолютному виду. 

Blox::addToHead('templates/flashPlayer.js');

Особенности подключения jQuery

Особое место занимают коды библиотек "jQuery" и "jQuery UI". По умолчанию, попытка вторичного подключения этих библиотек, даже другой версии или с помощью указания другого файла, будет проигнорирована. Это не касается плагинов, написанных с использованием этих библиотек — они идут на общих основаниях.

Поведение метода Blox::addToHead() можно изменять с помощью опций вставки (массив $options), как это было описано выше.

Пример применения опций

page.tpl 

# Код подключения jQuery должен быть выше всех остальных кодов
Blox::addToHead(
    'templates/jquery-1.7.1.min.js', 
    ['position'=>'top']
);

photos.tpl 

# Код подключения плагина Fancybox должен идти после кода jQuery
Blox::addToHead(
    'templates/jquery.fancybox-1.3.4.js', 
    ['after'=>'jquery-1.7.1.min.js']
);
    # Другие допустимые варианты опции after:
    ['after'=>'templates/jquery-1.7.1.min.js']
    ['after'=>'jquery-1.7.1']

Естественный порядок подключения кодов

Если метод применить в файле конфигурации сайта config.php, то код появится на всех страницах сайта, и будет расположен выше остальных кодов.

При вызове метод Blox::addToHead() из файлов шаблона (.tpl, .tdd), нужно также учитывать последовательность исполнения файлов шаблона.

В частности, у корневого блока дескриптор вызывается раньше всех других блоков, а его шаблон – позже всех. Исходя из этого, чтобы код размещался выше, запись Blox::addToHead(...) нужно делать в дескрипторе (.tdd), а чтобы код появился ниже, эту запись нужно поместить в шаблон (.tpl).

При этом, естественно, код появится только на тех страницах, где выводится данный шаблон.

Blox::addToFoot($code, $options)

Полный аналог метода Blox::addToHead(). Разница в том, что соответствующие коды будут внесены не в раздел head, а в конец документа перед закрывающим тегом </body>.

Рекомендуем все js-файлы и js-скрипты на статичных страницах вставлять именно этим методом.

Если вы подключили библиотеку jQuery в конце документа, то все js-скрипты вида <script>...</script>, использующие эту библиотеку, вставлять прямо в коды шаблонов (без помощи метода Blox::addToFoot) уже нельзя. Исключение составляют блоки, вызываемые через ajax.

Пример:

page.tpl
Blox::addToFoot(
    '//code.jquery.com/jquery-1.12.1.min.js', 
    ['position'=>'top']
);
person.tpl
$js = '
<script>
    $("#person form").on("submit", function(){
        $("#person").css("opacity","0.4");
    })
</script>';

if (Blox::ajaxRequested())
    echo $js; # Если блок вызывается через ajax, метод Blox::addToFoot() не работает!
else
    Blox::addToFoot($js, ['after'=>'jquery-1', 'minimize']);

Коды вставляемые обоими методами, Blox::addToHead() и Blox::addToFoot(), проходят проверку на уникальность, единым списком.

Куда помещать общие файлы, не принадлежащие шаблонам?

При разработке большого сайта, появляются файлы и наборы файлов, используемые одновременно разными шаблонами, и при этом, не относящиеся непосредственно к шаблонам. Это файлы: js, css, стилевые картинки. Могут быть также файлы php и т.д. Как правило, эти файлы принадлежат сторонним продуктам (фреймворки, плагины и т.д.).

Естественно, привязывать общие файлы к шаблонам было бы неправильно. Но тогда возникает вопрос — как контролировать зависимость шаблонов от этих файлов?

На сегодняшний день существует мощное решение — это composer. Однако, здесь мы предлагаем более простое решение. Во-первых, нужно договориться о единой структуре папок для общих файлов.

Структура папки assets

Предлагаем в папке templates для этих целей создавать папку assets, и одиночные файлы сваливать прямо в эту папку. Отдельные папки внутри assets, создавать только для пакетов файлов. См. древо.

Для простых сайтов раньше мы предлагали общие стилевые картинки сайта помещать в templates/images/. Теперь же, чтобы придерживаться единого принципа, мы рекомендуем использовать templates/assets/images/. 

templates/
    assets/
        bootstrap/
        fancybox/
        images/
        jquery/
        docs.min.css
        pagination.php

Внутрь папки templates, кроме папки assets, лучше вкладывать только папки с комплектами шаблонов.

Как контролировать зависимость шаблонов от общих файлов?

  • Допустим вы скопировали файлы шаблона news (файлы news.* и папка news) с одного сайта и вставили их на другой сайт, и забыли, при этом, забрать файл pagination.php, отвечающий за генерацию кнопок пагинации.

    После назначения шаблона news на другом сайте, должно возникнуть сообщение об отсутствии этого файла. Сделать это можно с помощью метода Blox::prompt():

    news.tpl 

    $paginationFile = 'templates/assets/pagination.php';
if ($edit) {
    if (file_exists($paginationFile))
        require_once $paginationFile;
    else
        Blox::prompt('Файл '.$paginationFile.' не существует!', true);
} else
    require_once $paginationFile;

  • Что касается файлов, подключаемых по URL (js, css, jpg, ...), то их нужно подключать с помощью описанных в данной статье методов Blox::addToHead() и Blox::addToFoot(), которые автоматически выдают сообщение об отсутствии файлов. Сообщения об ошибках можно посмотреть также в консоли браузера.

 

Примечания

  • Если не применены опции, коды, созданные методом Blox::addToHead(), выводятся до кодов подключения файлов шаблон.css, шаблон.js.
  • В принципе, с помощью массива Blox::addToHead() можно также задать титул страницы, ключевые слова и описание страницы. Однако для этих целей лучше воспользоваться окном: Страница > Настройки страницы

См. также