Хуки-хухуки: Как создать свой компонент для хуков?

Часто в блогах и на форуме можно увидеть совет «для решения задачи нужно в таком-то хуке сделать так-то» и даже есть рабочий код, но куда его вставить?
Прямо как в анекдоте: Почему холостяки не готовят себе рецепты из интернета? Потому что каждый рецепт начинается со слов «Возьмите чистую кастрюлю».
Сделаем себе «чистую кастрюлю» — пустой компонент для своих хуков.

Небольшое отступление.
1. Заранее прошу прощения у моих коллег-программистов, за то, что я отбираю немного хлеба у богатых продвинутых программеров и отдаю его начинающим.
2. Я не претендую на звание «гуру». Просто делюсь тем, что уже изучил. Если у вас есть замечания или дополнения – смело пишите в комментариях.

Для начала дня три почитаем «Документацию по созданию компонентов» и посмотрим замечательные видео-туториалы от разработчиков…
Шутка. Изучать доки нужно обязательно, но для наших целей всё гораздо проще и быстрее. Дальше без шуток.

Создаём контроллер компонента

Придумаем название компонента. Вы можете выбрать любое и написать его латинскими буквами. Я назову – ‘Webman’. Не потому, что у меня мало скромности (у меня её вообще нет). А для того, чтобы вам захотелось подставить другое имя и вы поняли, что и как дальше делается.

Создаём папку с этим названием в папке /system/controllers. Название должно быть написано прописными (маленькими) буквами. Получаем папку /system/controllers/webman

Теперь создаём пустой файл контроллера (фронтенда) компонента /system/controllers/webman/frontend.php, открываем его в любимом редакторе PHP-файлов (Notepad++, NetBeans. PHPStorm и т.п.) и добавляем такие строки:

<?php
 
class webman extends cmsFrontend {
 
    protected $useOptions = true;
 
}

Обратите внимание, класс называется именем нашего компонента, полностью прописными буквами.
На самом деле можно было обойтись тремя строчками, но мы хотим в дальнейшем пользоваться удобством работы с опциями контроллера, поэтому задали свойство $useOptions.

Вы не поверите, но пустой компонент с контроллером уже готов! Можно пользоваться!
Но лично мне этого мало, я хочу иметь управляемый компонент. Поэтому сразу сделаем форму опций для него в Админке.

Добавляем опции компонента

Что мне очень нравится в Двойке – у неё очень продуманная структура и логика работы. От этого получается простота в использовании. Для добавления опций нужно всего два файла: бэкенд («админская» часть) и сама форма опций.

Пустой бэкенд делается так же просто, как и фронтенд. Создаём файл /system/controllers/webman/backend.php с кодом

<?php
 
class backendWebman extends cmsBackend {
 
    protected $useOptions = true;
 
    public $useDefaultOptionsAction = true;
 
    public function actionIndex() {
        $this->redirectToAction('options');
    }
 
    public function getBackendMenu() {
        return array(
            array(
                'title' => LANG_OPTIONS,
                'url'   => href_to($this->root_url, 'options')
            ),
        );
    }
}

Здесь название компонента пишем уже с заглавной буквы, чтобы отделить его от префикса ‘backend’.
Свойство $useOptions нам уже знакомо, а $useDefaultOptionsAction указывает бэкенду использовать стандартные методы работы с опциями.
Метод actionIndex() редиректит с ссылки site/admin/controllers/edit/webman на site/admin/controllers/edit/webman/options, чтобы из списка компонентов cразу открывать опции нашего компонента.
Метод getBackendMenu() добавляет кнопочку «Опции» над формой, чтобы видеть где мы находимся. Можно и без него, но с кнопочкой красивее.

В папке компонента создаём папку backend, в ней папку forms, а в ней файл опций form_options.php. Получаем такой путь /system/controllers/webman/backend/forms/form_options.php
Код для него:

<?php
 
class formWebmanOptions extends cmsForm {
 
    public $is_tabbed = true;
 
    public function init() {
 
        return array(
 
            array(
                'type' => 'fieldset',
                'title' => LANG_WEBMAN_OPT_TAB_TEST,
                'childs' => array(
 
                    new fieldCheckbox('is_it_works', array(
                        'title' => LANG_WEBMAN_OPT_IS_IT_WORKS,
                    )),
 
                )
            ),
 
        );
 
    }
 
}

По сути, в этом файле мы свойством $is_tabbed сказали, что форма опций будет с табами – так и красивее, и удобнее при большом количестве опций. А потом в методе init() возвращаем массив с полями нашей формы. В данном случае это одна вкладка (fieldset) с названием ‘TEST’ и одним полем типа сheckbox с именем 'is_it_works' и заголовком 'Заработало!'.
Подробнее про опции в документации «Стандартная форма опций в админке»

Файлы языков

Обратите внимание, в форме опций использованы две языковые константы (начинаются на ‘LANG_’). Понимаю, что хотелось бы сразу вписать нужные строки в код, но правильнее вынести их константами в языковые файлы. Это просто.

Создаём файл для русского языка /system/languages/ru/controllers/webman/webman.php и добавляем туда наши константы

 <?php
 
define('LANG_WEBMAN_CONTROLLER',      'Хуки-хухуки');
 
define('LANG_WEBMAN_OPT_TAB_TEST',    'Тест');
 
define('LANG_WEBMAN_OPT_IS_IT_WORKS', 'Заработало!');
 

В первой строке константа LANG_WEBMAN_CONTROLLER задаёт имя вашего компонента, отображаемое в Админке. Далее можете писать любые свои константы с именами, начинающимися на LANG_ИМЯКОМПОНЕНТА_

При необходимости можете создать такие же файлы с переводом на другие языки. Например, для английского /system/languages/en/controllers/webman/webman.php

Вы же помните, что везде имя webman нужно заменить на своё имя компонента с сохранением регистров символов?

Инсталляционный пакет

Компонент для хуков полностью готов. Осталось только зарегистрировать его в системе. Это можно сделать по-старинке, запросом в базу данных. Но мы сделаем правильно — инсталляционным пакетом.
Внимательно читаем «Создание пакета дополнения CMS»

Создаём отдельную папку (не в папках сайта!) webman_install_0.0.1. В ней создаём папку package, в которую с сохранением структуры папок копируем все добавленные нами файлы.

Рядом с папкой package создаём файл manifest.ru.ini с описанием нашего пакета:

[info]
title = "Хуки-хухуки"
 
[version]
major = "1"
minor = "0"
build = "0"
date = "20210125"
 
[depends]
core = "2.14.0"
 
[install]
type = "component"
name = "webman"
 
[author]
name = "WebMan"
url = "/users/WebMan"
 
[description]
text[] = "Мой компонент для хуков."
 

Имя пакета, название и автора меняете на свои. При необходимости можете создать такие же файлы манифеста и для других языков.
Запаковываем манифест и папку с файлами пакета (всё, что внутри папки webman_install_0.0.1, без неё самой) в архив webman_install_0.0.1.zip.

Устанавливаем полученный пакет стандартным образом через Админку. Если ставите на тот же сайт, где уже добавили все файлы, то шаг копирования на ftp пропускайте, чтобы только зарегистрировался компонент.
После этого открываем «Компоненты», находим свой компонент и кликом по названию открываем его опции. Теперь можем изменять и сохранять настройки компонента. Заработало!

Поздравляю с первым компонентом!

Ссылка на готовый пакет для ленивых webman_install_1.0.0.zip
Но всё же настоятельно рекомендую создать компонент с более подходящим для вас именем вручную, чтобы понять как это делается и чтобы потом вносить в него нужные вам хуки.

Примечание: для наших целей – обработка хуков – можно было и не создавать контроллер frontend.php – он нужен для обработки пользовательской части сайта или для основной логики компонента. Но мало ли что мы захотим делать в компоненте дальше, так что пусть будет.

А что мы будем с ним делать дальше — читайте в следующих выпусках. 😊