157  /  430

Шаблоны компонента

Цитатник веб-разработчиков.

Роман Петров: Не все знают, что у стандартных компонентов "1С-Битрикс" есть много других красивых штатных шаблонов, которые практически никогда не используются. Для любопытствующих вопрос: знаете ли вы, что шаблон постраничной навигации имеет аж пять шаблонов: .default, arrows, js, modern, orange?

Шаблон компонента - программный код, преобразующий данные, подготовленные компонентом, непосредственно в HTML-код.

  • Переменные
  • Шаблон простого компонента
  • Шаблон комплексного компонента
  • Как система ищет шаблон
  • Подключение шаблона
  • Редактирование шаблона
  • Особенности работы с ajax
  • Пример шаблона
  • Шаблоны компонента делятся на системные и пользовательские:

    • Системные шаблоны поставляются вместе с компонентом и лежат в подпапке templates папки компонента.
    • Пользовательские шаблоны компонента - шаблоны, которые изменены под нужды конкретного сайта. Они должны лежать в папках шаблонов сайтов (т.е. в /bitrix/templates/шаблон_сайта/). При копировании шаблона компонента средствами системы, они будут расположены по следующему пути: /bitrix/templates/шаблон_сайта/components/namespace/название_компонента/название_шаблона.

    Шаблоны компонента определяются по именам. Шаблон по умолчанию имеет имя .default. Если в настройках параметра компонента не указывается имя шаблона, вызывается шаблон по умолчанию. Остальные шаблоны могут называться произвольно.

    Шаблоны компонента могут быть папками или файлами. Если шаблону не требуется перевод на другие языки, собственные стили и прочие ресурсы, такой шаблон можно расположить в файле. В противном случае шаблон следует располагать в папке.

    Каждый шаблон компонента является неделимым целым. Если требуется изменить системный шаблон компонента под конкретный сайт, то этот шаблон компонента нужно целиком скопировать в папку шаблона сайта.

    Например, у компонента bitrix:main.site.selector есть системный шаблон dropdown, который лежит в подпапке templates папки компонента. Если этот шаблон компонента требуется изменить под конкретный сайт, то папку шаблона dropdown следует скопировать в папку /bitrix/templates/шаблон_сайта/components/bitrix/main.site.selector/ и изменить по своему усмотрению.

    При включении компонента на страницу сайта администратор настраивает, какой именно шаблон вывода будет использоваться в данном конкретном случае.


    Переменные, доступные в шаблоне компонента

    В шаблоне используются следующие переменные:

    • $templateFile – путь к шаблону относительно корня сайта, например /bitrix/components/bitrix/iblock.list/templates/.default/template.php).
    • $arResult – массив результатов работы компонента.
    • $arParams – массив входящих параметров компонента, может использоваться для учета заданных параметров при выводе шаблона (например, отображении детальных изображений или ссылок).
    • $arLangMessages – массив языковых сообщений шаблона (для php шаблонов не устанавливается).
    • $templateFolder - путь к папке с шаблоном от DOCUMENT_ROOT (например /bitrix/components/bitrix/iblock.list/templates/.default).
    • $parentTemplateFolder - путь относительно корня сайта к папке шаблона комплексного компонента, в составе которого подключается данный компонент (если компонент подключается самостоятельно, то эта переменная пуста).
    • $component — ссылка на текущий вызванный компонент (тип CBitrixComponent).
    • $this - ссылка на текущий шаблон (объект, описывающий шаблон, тип CBitrixComponentTemplate)
    • $templateName — имя шаблона компонента (например: .dеfault)
    • $componentPath - путь к папке с компонентом от DOCUMENT_ROOT (напр. /bitrix/components/bitrix/iblock.list)
    • $templateData — массив для записи, обратите внимание, таким образом можно передать данные из template.php в файл component_epilog.php, причем эти данные попадают в кеш, т.к. файл component_epilog.php исполняется на каждом хите.

    Кроме того внутри PHP шаблона объявлены глобальными переменные $APPLICATION, $USER, $DB.


    Шаблон простого компонента

    Папка шаблона простого компонента может содержать следующие подпапки и файлы:

    • подпапку /lang, в которой расположены файлы языковых сообщений (переводов) шаблона компонента;
    • файл result_modifier.php, который подключается непосредственно перед подключением шаблона компонента. Этот файл получает на вход массив результатов работы компонента $arResult и массив параметров вызова компонента $arParams. Таким образом, можно, например, изменить массив результатов работы компонента под конкретный шаблон.
    • файл component_epilog.php, который подключается после исполнения шаблона.
    • файл style.css, который определяет стили, необходимые данному шаблону.
    • файл script.js, который определяет и подключает яваскрипты, необходимые данному шаблону. Этот файл может отсутствовать.
    • файл .description.php, который содержит название и описание шаблона для визуального редактора.
      Пример файла .description.php
    • файл .parameters.php, который содержит описание дополнительных входных параметров шаблона для визуального редактора.
      Пример файла .parameters.php
    • файл template.ext, который и является собственно шаблоном. Расширение ext зависит от того, какой движок шаблонизации нужно подключать. По умолчанию расширение равно php. Этот файл должен обязательно присутствовать.
    • любые другие папки и файлы с ресурсами, необходимыми шаблону компонента. Например, папка image, содержащая изображения, необходимые шаблону.

    Шаблон комплексного компонента


    Шаблон комплексного компонента содержит все те же папки, что и шаблон простого компонента, и дополнительно:

    • шаблоны простых компонентов, которые входят в состав комплексного. Эти шаблоны располагаются в папках вида /пространство_имен/название_простого_компонента/ относительно папки шаблона комплексного компонента.
    • простые компоненты, входящие в состав комплексного, подключаются на шаблонах страниц комплексного компонента.

    Как система ищет шаблон

    Применяется следующий алгоритм поиска подходящего шаблона для компонента:

    • Берется папка /bitrix/templates/текущий_шаблон_сайта/components/. В этой папке в пути /пространство_имен_компонента/название_компонента/ проверяется последовательно наличие файла или папки с именем шаблона. Если таковых нет, то проверяется наличие файла имя_шаблона.ext, где в качестве ext берутся последовательно все доступные расширения всех установленых на сайте движков шаблонизации. Если шаблон найден, то алгоритм завершается.
    • Если на шаге 1 шаблон не найден, то берется папка /bitrix/templates/.default/components/. И применяется алгоритм, описанный в шаге 1. Если шаблон найден, то алгоритм завершается.
    • Если на шаге 2 шаблон не найден, то производится поиск среди системных (т.е. поставляемых с компонентом) шаблонов.

    Особенности поиска:

    • Если имя шаблона не задано, то ищется шаблон с именем .default.
    • Если шаблон задан именем папки, то в случае простого компонента в этой папке ищется файл template.ext, а в случае комплексного - название_страницы.ext. Расширение ext сначала принимается равным php, а затем расширениям других доступных на сайте движков шаблонизации.

    Например, требуется показать компонент bitrix:catalog.list с помощью шаблона table. Пусть на сайте, кроме стандартного движка шаблонизации (файлы с расширением php), доступен так же движок Smarty (файлы с расширением tpl). Система проверит сначала папку /bitrix/templates/текущий_шаблон_сайта/components/bitrix/catalog.list/ на наличие файла или папки с именем table. Если таковых нет, система проверит указанную выше папку на наличие файлов table.php и table.tpl. Если ничего не найдено, система изучит папки /bitrix/templates/.default/components/bitrix/catalog.list/ и /bitrix/components/bitrix/catalog.list/templates/.

    Если папка компонента найдена, в этой папке сначала ищется файл template.php, и если этот файл не найден, то ищется template.tpl. Если шаблон задан в виде table/template.php, то сразу берется указанный файл.

    Если простой компонент вызывается в составе комплексного, то шаблон простого компонента сначала ищется в составе шаблона комплексного компонента, а потом (если не найден) в собственных шаблонах. Чтобы это правило работало, при вызове простых компонентов в составе комплексного не забывайте указывать четвертым параметром переменную $component, указывающую на родительский компонент. Т.е. код вызова простого компонента должен иметь вид:

    $APPLICATION->IncludeComponent("custom:catalog.element", "", array(...), $component);

    Примечание:

    В одной папке (например, /bitrix/templates/текущий_шаблон_сайта/components/) есть шаблоны двух компонентов, комплексного и простого:

    • catalog (комплексный, к котором есть еще простой catalog.section)
    • catalog.section (простой)
    По условиям работы сайта необходимо чтобы для двух вхождений catalog.section использовался один единственный шаблон. В этом случае нужно, чтобы этот шаблон имел имя, отличное от .default, иначе он не будет подхвачен.


    Подключение шаблона

    В коде подключения указывается только <namespace>, имя компонента, имя шаблона (и параметры самого компонента). При обработке кода ядро сначала проверяет наличие шаблона компонента в шаблоне текущего сайта: /bitrix/templates/<имя шаблона сайта>/components/<namespace>/<имя компонента>/<имя шаблона>/template.php.

    Если - bitrix (/bitrix/components/bitrix), то это папка для шаблонов стандартных компонентов. Если - выбранное вами <имя> (/bitrix/components/<имя>), то это папка для шаблонов ваших компонентов.

    Если файла шаблона нет, проверяется шаблон сайта по умолчанию: /bitrix/templates/.default/components/<namespace>/<имя компонента>/<имя шаблона>/template.php.

    И только после этого происходит подключение шаблона компонента из папки компонента.

    Шаблон подключается командой:

    $this->IncludeComponentTemplate($templatePage = "");

    Где $templatePage – для комплексного компонента имя текущей страницы, для обычного компонента пустая строка.

    Примеры подключения шаблона компонента:

    1. Подключим шаблон текущего комплексного компонента для страницы section:

      $this->IncludeComponentTemplate("section");

    2. Подключим шаблон текущего простого компонента:

      $this->IncludeComponentTemplate();


    Редактирование шаблона

    Редактирование шаблона - один из способов получения нужного результата работы компонента под требования сайта. Редактировать системный шаблон не рекомендуется в силу того, что при первом же обновлении системный шаблон восстановит свое прежнее состояние. Редактировать и применять можно только пользовательский шаблон.

    Копирование шаблона выполняется по команде Копировать шаблон компонента при включенном режиме Правка:

    При копировании шаблона можно сразу задать его применение к компоненту и открыть форму для редактирования шаблона:

    При отмеченной опции Перейти к редактированию шаблона сразу будет осуществлен переход на страницу редактирования шаблона компонента. (В версиях продукта до 9.5 переход к редактированию осуществляется с помощью менеджера файлов либо при помощи команды Редактировать шаблон компонента.)

    Редактирование шаблона допускает добавление в него логики действий, но такую модификацию лучше выносить в файлы result_modifier.php и component_epilog.php (которые должны быть расположены в папке шаблона) для более сложного изменения результата работы.


    Особенности работы с ajax

    Использование режима ajax имеет свои особенности. Чтобы строка навигации в открываемой по ajax странице имела в цепочке навигации своё название, необходимо, что бы в шаблоне компонента обязательно присутствовал элемент с id="navigation". Это необязательно должен быть div, это может быть span, h1, p и так далее.

    Аналогично, для заголовка обязательно наличие элемента с id="pagetitle".


    Пример шаблона

    Шаблон компонента Меню
    Проверка включения <?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>
    Старт скрипта <?if (!empty($arResult)):?>
    Открытие тега <ul> — ненумерованный список <ul class="…">
    Старт цикла поиска <?foreach ($arResult as $arItem):?>
    Ссылка активная <?if($arItem["SELECTED"]):?>
    Вывод ссылки <li><a href="<?=$arItem["LINK"]?>" class= "selected"><?=$arItem["TEXT"]?></a></li>
    Проверка на продолжение цикла <?else:?>
    Ссылка неактивная <li><a href="<?=$arItem["LINK"]?>"> <?=$arItem["TEXT"]?></a></li>
    Завершение вывода ссылки <?endif?>
    Завершение цикла поиска <?endforeach?>
    Закрытие тега <ul> — ненумерованный список </ul>
    Завершение скрипта <?endif?>

    Список ссылок по теме:


    26

    Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
    Развернуть комментарии