Свой модуль для Joomla: сравнение подходов и выбор

В Joomla 5.x один и тот же блок можно собрать тремя способами: вставить разметку через Custom HTML, написать отдельный модуль или вынести данные в компонент и оставить модулю только вывод. Первый вариант запускается за минуты, второй даёт нормальную точку расширения, третий выдерживает сложную бизнес-логику, но стоит дороже в разработке и сопровождении.

Сначала определите, что именно должен делать блок

Модуль в Joomla — это расширение, которое выводится в позиции шаблона и обычно отвечает за конкретный фрагмент страницы: меню, список материалов, форму, баннер или небольшой виджет. Он не должен превращаться в скрытый компонент с собственной админкой, десятком таблиц и несколькими маршрутами.

Перед выбором ответьте на четыре вопроса:

• Нужна ли только фиксированная HTML-разметка или данные нужно получать из базы, API либо Joomla Content API.
• Должен ли редактор менять содержимое через админ-панель.
• Нужны ли фильтры, пагинация, отдельные страницы и сохранение записей.
• Будет ли один экземпляр блока или несколько экземпляров с разными настройками.

Сноска. Позиция модуля — область шаблона Joomla, например боковая колонка или блок над контентом. Конкретные названия зависят от установленного шаблона.

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

Три рабочих подхода

1. Custom HTML: когда PHP не нужен

Стандартный модуль Custom HTML подходит для текста, изображения, ссылки или простой разметки. Вы создаёте модуль в административной панели, выбираете позиции и пункты меню, затем вставляете содержимое в редактор.

Цена решения — зависимость от редактора и шаблона. PHP-код в таком модуле обычно не исполняется, сложные данные он сам не загрузит, а повторяемая разметка быстро превратится в ручную копипасту. Это хороший выбор для блока «Доставка», промо-баннера или контактной информации, но не для каталога и личного кабинета.

2. Отдельный модуль: подходящий вариант для виджета

Собственный модуль получает настройки, шаблон вывода и отдельную папку расширения. Это уже код, который можно хранить в Git, устанавливать на тестовый и рабочий сайт и менять без ручного редактирования каждой страницы.

Классическая структура модуля ниже подходит для небольшого серверного блока в Joomla 5.x. Она не содержит внешних библиотек и не использует внутренние API, имена которых могут меняться между версиями.

<!-- mod_catalogbadge.xml -->
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" client="site" method="upgrade">
    <name>MOD_CATALOGBADGE</name>
    <version>1.0.0</version>
    <description>Simple catalog badge module</description>
    <files>
        <filename module="mod_catalogbadge">mod_catalogbadge.php</filename>
        <folder>tmpl</folder>
    </files>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field name="title" type="text" label="MOD_CATALOGBADGE_TITLE" />
            </fieldset>
        </fields>
    </config>
</extension>

Точка входа получает параметры экземпляра и передаёт управление шаблону:

<?php
// mod_catalogbadge.php

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;

$title = (string) $params->get('title', 'Каталог');

require ModuleHelper::getLayoutPath(
    'mod_catalogbadge',
    $params->get('layout', 'default')
);

<?php
// tmpl/default.php

defined('_JEXEC') or die;

$safeTitle = htmlspecialchars($title, ENT_QUOTES, 'UTF-8');
?>
<div class="catalog-badge">
    <span><?php echo $safeTitle; ?></span>
</div>

Важная деталь — экранирование значения перед выводом. Параметр модуля редактирует пользователь с административным доступом, и доверять его содержимому без обработки не стоит.

3. Компонент плюс модуль: для данных и сложных сценариев

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

Преимущество — разделение ответственности: компонент владеет данными и страницами, модуль отвечает за короткую презентацию. Недостаток — две точки расширения, больше файлов, тестов и настроек. Для одного счётчика заказов такая архитектура избыточна, для каталога — обычно безопаснее, чем попытка поместить всё в файл модуля.

Сравнение по цене и рискам

В таблице нет универсального победителя. Custom HTML дешевле только до первого повторяющегося изменения. Собственный модуль дешевле компонента, пока ему не нужны полноценное хранение данных и навигация.

Что выбрать в типичных ситуациях

Нужен один рекламный блок

Берите Custom HTML. Создайте модуль, укажите позицию, ограничьте вывод нужными пунктами меню и проверьте мобильную версию. Писать расширение ради двух ссылок — лишняя поверхность для ошибок и обновлений.

Нужен список из Joomla или внешнего источника

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

Нужны записи, поиск и отдельные страницы

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

Что чаще всего ломается

• Модуль установлен, но не виден. Проверьте публикацию, позицию шаблона, привязку к пунктам меню и наличие самой позиции в активном шаблоне.
• Вместо вывода появляется ошибка 500. Посмотрите журнал PHP и режим отладки Joomla. Частые причины — синтаксическая ошибка, неверный путь к шаблону или обращение к переменной до её создания.
• Текст выводится с неожиданными символами. Проверьте кодировку файлов и экранирование HTML. Не вставляйте непроверенные значения через прямую конкатенацию разметки.
• Один модуль работает, два экземпляра конфликтуют. Не используйте одинаковые глобальные идентификаторы HTML и CSS-классы, если экземпляры могут появиться на одной странице. Настройки должны читаться из параметров конкретного экземпляра.
• Обновление удаляет ручные изменения. Не редактируйте файлы установленного расширения на сервере. Храните исходники в репозитории и собирайте установочный архив из них.

Когда подход ломается

Классический небольшой модуль удобен для вывода, но плохо подходит для долгих операций, сложной авторизации и больших выборок. Не выполняйте тяжёлый внешний запрос на каждой загрузке страницы без кеширования или другого контроля частоты. Если результат зависит от пользователя, языка и группы доступа, правила кеширования нужно проверить отдельно: неверный ключ может показать одному посетителю данные другого.

Не смешивайте в одном шаблоне запросы к базе, бизнес-правила и HTML. На старте это экономит несколько строк, но при следующем изменении превращает поиск ошибки в ручной аудит всего файла. Инвалидация кеша и безопасная работа с внешними API — отдельные темы, здесь важен сам критерий выбора архитектуры.

Что делать дальше

Для простого блока сначала соберите минимальный собственный модуль на Joomla 5.x: манифест, точку входа, шаблон и один параметр. Установите его на копию сайта, создайте два экземпляра с разными настройками и проверьте, что они не влияют друг на друга.

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