Версия: 6.x
burger close
Хуки в шаблонах

Оглавление

Хуки(или зоны) в шаблонах позволяют вставлять через сторонний модуль собственный HTML-код "до", "вместо" или "после" той области, которая обернута конструкцией {hook}...{/hook}. Хуки могут использоваться как веб-мастерами, чтобы изменить часть какой-то страницы и сохранить при этом обновление шаблона, так и производителями сторонних модулей, чтобы автоматически внедрять необходимые функциональные блоки во внешний вид сайта.

Наиболее яркий пример, где могут потребоваться хуки - это модуль покупки в кредит. После установки такого модуля, под кнопкой "Купить" в карточке товара должна появиться еще одна кнопка "Купить в кредит". Но как ей автоматически встроиться в стандартный шаблон карточки товара product.tpl? Здесь на помощь приходят хуки. Модулю достаточно добавить шаблон-обработчик хука, который дополнит заранее определенное место в карточке товара.

Объявление хуков в исходном шаблоне

Чтобы объявить в шаблоне зону для модификации извне, достаточно обернуть часть имеющегося HTML-кода конструкцией {hook name="...." title="...."}...{/hook}. Обернутый HTML-код будет отображаться пользователю по умолчанию, если ни один модуль не перезаписывает данную область. У каждого хука необходимо указать его идентификатор в атрибуте name и произвольное пояснение в атрибуте title. Идентификатор строится по следующему принципу: 

<ИДЕНТИФИКАТОР ИМЕНИ ШАБЛОНА>:<ИДЕНТИФИКАТОР ЗОНЫ ВНУТРИ ШАБЛОНА>, где
  • ИДЕНТИФИКАТОР ИМЕНИ ШАБЛОНА - строка, по которой однозначно можно понять, в каком шаблоне располагается хук. Обычно это название модуля - путь к шаблону - имя файла шаблона, все спец.символы (слеши) заменяются на знак -(минус).
  • ИДЕНТИФИКАТОР ЗОНЫ ВНУТРИ ШАБЛОНА - строка, произвольное название области, которую представляет хук.

Пример именования хуков:

Предположим, хук, оборачивающий зону изображений, располагается в шаблоне /modules/catalog/view/product.tpl, соответственно имя хука следует построить так: catalog-product:images. Мы вырезали из пути к шаблону все лишние, повторяющиеся элементы (-view), и оставили только уникальные части, позволяющие идентифицировать шаблон.

Рассмотрим второй пример. Предположим хук, оборачивающий зону вывода элементов категорий, располагается в шаблоне /modules/catalog/view/blocks/category/category.tpl, соответственно имя хука следует построить так: catalog-blocks-category:list-item. Аналогично предыдущему примеру, мы вырезли дублирующиеся элементы и отразили все необходимое, чтобы однозначно идентифицировать место расположения хука.

Посмотрим, как хуки выглядят в шаблоне:

<div class="product">
{hook name="catalog-product:images" title="Карточка товара:изображения"}
<div class="images">
....
</div>
{/hook}
{hook name="catalog-product:rating" title="Карточка товара:рейтинг"}
<div class="rating">
...
</div>
{/hook}
</div
Заметки
Вы можете пользоваться хуками в собственных больших проектах, для обеспечения взаимодействия ваших шаблонов и ваших модулей. В шаблонах, публикуемых в Marketplace для всеобщего пользования, настоятельно рекомендуем размещать только те хуки, что имеются в стандартных шаблонах и представлены ниже в данном материале.

Обработка хуков в собственном модуле

Обработка хуков возможна из сторонних модулей. Для этого достаточно разместить шаблоны-обработчики по специальному пути в модуле: 

/modules/{ВАШ МОДУЛЬ}/view/hooks/<ИДЕНТИФИКАТОР ИМЕНИ ШАБЛОНА ХУКА>/<ИДЕНТИФИКАТОР ЗОНЫ ВНУТРИ ШАБЛОНА>[.ТИП ОБРАБОТКИ].tpl

где:

  • ВАШ МОДУЛЬ - папка вашего модуля
  • ИДЕНТИФИКАТОР ИМЕНИ ШАБЛОНА ХУКА - часть названия хука до двоеточия. Например, если название хука catalog-product:images, то имя папки должно быть catalog-product.
  • ИДЕНТИФИКАТОР ЗОНЫ ВНУТРИ ШАБЛОНА - часть названия хука после двоеточия. Например, если название хука catalog-product:images, то имя файла должно быть images.
  • ТИП ОБРАБОТКИ - Может быть "pre", "post" или пустая строка. pre - означает, что шаблон будет добавлен до хука, post - после. Пустая строка означает, что шаблон-обработчик заменит HTML-код хука по умолчанию.

Пример:

Допустим мы хотим обрабатывать в нашем модуле ModuleName хук catalog-product:images. Что для этого нужно? Создать базовую структуру модуля с двумя обязательными файлами конфигурации и папкой с шаблонами-обработчиками хуков.

  • modulename //название модуля
    • config //Здесь должны находиться конфигурационные классы модуля
      • file.inc.php //Конфигурационный файл модуля
      • module.xml //Файл со сведениями о модуле и его настройках по умолчанию
    • view //Корневая папка для шаблонов отображения
      • hooks //Папка с шаблонами-обработчиками хуков
        • catalog-product //идентификатор имени шаблона хука
          • images.pre.tpl//Данный шаблон добавит свой HTML до зоны хука
          • images.tpl //Данный шаблон добавит свой HTML вместо стандартного содержимого хука
          • images.post.tpl //Данный шаблон добавит свой HTML после зоны хука
        • ... //Другие идентификаторы шаблонов хуков

Рассмотрим подробнее состав каждого из файлов:

Содержимое файла /config/file.inc.php:

namespace ModuleName\Config;
class File extends \RS\Orm\ConfigObject
{}

Содержимое файла /config/module.xml:

<?xml version="1.0" encoding="utf-8"?>
<config>
<defaultValues>
<name multilanguage="true">Название модуля</name>
<description multilanguage="true">Описание модуля</description>
<version>1.0.0.0</version>
<author>Автор модуля</author>
</defaultValues>
</config>

Содержимое файла /view/hooks/catalog-product/images.pre.tpl

<p>здесь может быть любой HTML, который модуль ModuleName вставит перед зоной хука</p>

Содержимое файла /view/hooks/catalog-product/images.tpl

<p>здесь может быть любой HTML, который модуль ModuleName вставит вместо содержимого по умолчанию, обернутого хуком</p>

Содержимое файла /view/hooks/catalog-product/images.post.tpl

<p>здесь может быть любой HTML, который модуль ModuleName вставит после зоны хука</p>
Заметки
В шаблонах-обработчиках хуков доступны все переменные, передаваемые в шаблон источник.

Благодаря возможности дополнять/заменять содержимое "до", "вместо" или "после" хука, по сути один хук заменяет собой три хука, что значительно визуально облегчает разметку шаблона.

Если несколько модулей будут обрабатывать один и тот же хук, то используется следующая логика:

  • в зону "до" и "после" хука будет последовательно добавлен HTML-код от всех обработчиков.
  • зону "вместо" будет определять самый последний по приоритету модуль.
Заметки
Исходя из указанной выше логики, не рекомендуем использовать хуки, выводящие свой контент "вместо" контента хука по умолчанию, если можно обойтись обработкой зоны "до" или "после", так как только один модуль может заменять контент хука по умолчанию.

Настройка приоритетов среди обработчиков хуков

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

Для этого:

  1. Перейдите на нужную страницу сайта, будучи авторизованным под администратором.
  2. Включите режим отладки с помощью верхней панели администратора.
  3. Наведите мышь на нужный блок, выберите инструмент "Порядок модулей". Откроется окно со списком модулей, обрабатывающих зоны шаблона.
  4. С помощью перетаскивания мышью, установите нужный порядок обработки зон модулями.
hook_sort.png
Сортировка модулей-обработчиков хуков
Заметки
Приоритеты модулей-обработчиков хуков экспортируются и импортируются вместе с информацией о расположении блоков в Конструкторе сайта через файл blocks.xml.

Полный перечень хуков в стандартных шаблонах

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

Страница, шаблон Название хука Описание
Карточка товара, catalog/view/product.tpl catalog-product:images Изображения в карточке товара
– || – catalog-product:rating Рейтинг в карточке товара
– || – catalog-product:offers Комплектации в карточке товара
– || – catalog-product:price Вывод цены в карточке товара
– || – catalog-product:action-buttons Область кнопок "В корзину", "купить в 1 клик", "заказать" в карточке товара
– || – catalog-product:information Вывод кратких сведений в карточке товара: Артикул, Бренд
– || – catalog-product:stock Остатки на складах в карточке товара
– || – catalog-product:properties Характеристики в карточке товара
– || – catalog-product:description Описание в карточке товара
Каталог товаров, catalog/view/list_products.tpl catalog-list_products:options Строка выбора сортировки и вида отображения товаров
– || – catalog-list_products:blockview-buttons Кнопки "В корзину", "сравнить" в блочном отображении товара в списке
– || – catalog-list_products:blockview-title Название товара в блочном отображении товара
– || – catalog-list_products:tableview-title Название товара в табличном отображении товара
– || – catalog-list_products:tableview-buttons Кнопки "В корзину", "сравнить" в табличном отображении товара в списке
Блок авторизованного пользователя, users/view/authblock/authblock.tpl users-blocks-authblock:balance Сведения о балансе пользователя
– || – users-blocks-authblock:username Имя авторизованного пользователя
– || – users-blocks-authblock:cabinet-menu-items Пункты меню личного кабинета авторизованного пользователя
Корзина, shop/view/cartpage.tpl shop-cartpage:products Список товаров в корзине
– || – shop-cartpage:summary Итоговые сведения в корзине
– || – shop-cartpage:bottom Нижняя часть корзины с кнопками "Оформить заказ", "Продолжить покупки" и сведениями об ошибках
Личный кабинет > Мои заказы, shop/view/myorders.tpl shop-myorders:products Товары одного заказа на странице со списком заказов
– || – shop-myorders:actions Ссылки действия одного заказа на странице со списком заказов
Личный кабинет > Мои заказы > Просмотр одного заказа, shop/view/myorder_view.tpl shop-myorder_view:product-info-items Область с информацией об одном товаре в заказе
– || – shop-myorder_view:order-info-items Область с информацией о параметрах заказа
Авторизация, users/view/authorization.tpl users-authorization:form Форма авторизации пользователя
Регистрация, users/view/register.tpl users-registers:form Форма регистрации пользователя
Подтверждение заказа, shop/view/checkout/confirm.tpl shop-checkout-confirm:products Список товаров на странице подтверждения заказов

Рекомендации по использованию хуков

Хуки - это лишь один из видов расширения функциональности сайта, его необходимо использовать только в случае, если та или иная функциональность модуля однозначно должна быть добавлена в ту зону, которую предоставляет хук. (Например, модуль "Купить в кредит", добавляющий дополнительную кнопку ниже стандартной кнопки "Купить".)

Если функциональность модуля теоретически может быть добавлена в разные места, то лучше просто привнести в систему Блок, который пользователь сможет разместить с помощью Конструктора сайта в любом месте. (Например, модуль - "Аналогичные товары", блок которого, можно добавить как в левую колонку, так и ниже карточки товара)

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

<!-- Блок добавлен с помощью шаблона '%modulename%/hooks/catalog-product/images.pre.tpl' -->
Здесь будет HTML, который добавляет модуль
<!-- Конец блока, добавленного с помощью шаблона '%modulename%/hooks/catalog-product/images.pre.tpl' -->



Если при разработке индивидуального проекта вы не обнаружили хук в необходимой зоне или в необходимом шаблоне, вы всегда можете клонировать целиком тему оформления с помощью раздела Управление → Шаблоны и внести изменения непосредственно в необходимый файл шаблона.