Шаблон в Joomla: типичные грабли и как их избежать

В Joomla 5.x шаблон может выглядеть правильно в редакторе и разваливаться на опубликованной странице: модуль исчезает, CSS не загружается, переопределение не срабатывает, а после обновления CMS правки пропадают. Ниже — практический разбор этих сбоев на уровне шаблона сайта, с примерами для Joomla 5.x и оговорками для проектов на Joomla 4.4.

Сначала проверьте версию и границы шаблона

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

Для работы понадобятся:

• доступ к файлам сайта через SSH, SFTP или файловый менеджер хостинга;
• резервная копия базы данных и каталога шаблона;
• название активного шаблона сайта и его папка в templates/;
• включённый режим отладки только на тестовом стенде, а не на публичном сайте.

В Joomla 5.x основной файл шаблона обычно находится в templates/имя_шаблона/index.php. Не редактируйте файлы расширений и ядра: обновление может заменить их без предупреждения.

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

Грабля первая: правка не того шаблона

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

1. Откройте «Система → Шаблоны → Стили шаблонов». Найдите стиль с пометкой по умолчанию для сайта.
2. Проверьте назначение. Откройте другие стили и посмотрите, к каким пунктам меню они привязаны.
3. Сравните имя папки с путём к файлу. Стиль может называться «Главный сайт», а папка — например, cassiopeia.
4. Сделайте заметную тестовую правку. Например, временно измените цвет фона локального блока, а не всего сайта.

Проверка простая: откройте страницу в приватном окне и убедитесь, что правка появилась именно там. Если её нет, сначала ищите другой стиль, кэш или переопределение, а не переписывайте CSS.

Грабля вторая: позиция модуля существует только в XML

Позиция, объявленная в файле описания шаблона, не появляется на странице сама по себе. Шаблон должен вывести её через тег jdoc:include, а модуль должен быть опубликован и назначен этой позиции.

Минимальный вывод позиции в index.php Joomla 5.x выглядит так:

<jdoc:include type="modules" name="sidebar" style="none" />

Имя sidebar здесь должно совпадать с позицией, выбранной в настройках модуля. Регистр и написание важны: sidebar и SideBar — разные значения.

Проверяйте проблему в таком порядке:

• модуль опубликован;
• у него выбрана нужная позиция;
• позиция назначена текущему пункту меню;
• в index.php есть вывод этой позиции;
• в шаблоне нет условия, которое скрывает блок на мобильной ширине или для конкретного типа страницы.

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

Грабля третья: CSS подключён, но браузер его не видит

Частая ошибка — положить файл в templates/mytemplate/css/ и ожидать, что Joomla подключит его автоматически. Наличие файла на диске не означает, что он попадёт в HTML страницы.

В Joomla 5.x для шаблона лучше использовать Web Asset Manager. Один из рабочих вариантов для файла media/templates/site/mytemplate/css/user.css:

<?php
defined('_JEXEC') or die;

$wa = $this->getWebAssetManager();

$wa->registerAndUseStyle(
    'template.user',
    'media/templates/site/mytemplate/css/user.css'
);
?>

Путь должен соответствовать реальному расположению файла и имени шаблона. Не копируйте этот фрагмент в расширение без проверки контекста: в модуле или компоненте объект $this может быть другим.

Откройте исходный HTML страницы и найдите ссылку на user.css. Затем откройте её напрямую в браузере. Статус 404 означает ошибку пути или публикации файла, а загруженный CSS без эффекта чаще указывает на порядок правил, специфичность селекторов или кэш.

Грабля четвёртая: кэш маскирует результат

После изменения шаблона могут одновременно работать кэш Joomla, кэш браузера, CDN и оптимизатор CSS. Из-за этого вы видите старую версию файла и меняете код, который уже работает, но не отображается.

Проверяйте изменения по цепочке:

1. откройте страницу в приватном окне;
2. в инструментах разработчика включите отключение кэша на время открытой панели;
3. перезагрузите страницу с принудительным обновлением;
4. очистите кэш Joomla через административную панель;
5. если используется CDN или серверный кэш, очистите его отдельно.

Не оставляйте отключённый кэш на боевом сайте как постоянное решение. Сначала определите, какой слой отдаёт старый файл.

Грабля пятая: переопределение лежит не там

Переопределение¹ — копия вида или макета расширения в каталоге шаблона, которую Joomla использует вместо оригинала. Оно позволяет менять разметку без правки самого расширения, но путь должен повторять структуру расширения.

Например, переопределение вывода модуля должно находиться внутри каталога шаблона в структуре, которую Joomla создаёт инструментом переопределений. Если файл просто положить в templates/mytemplate/html/ без нужного подкаталога, CMS его не найдёт.

Надёжнее создавать переопределение через административный раздел «Система → Шаблоны → Шаблоны сайта», если нужное расширение предлагает такую возможность. После создания сравните путь нового файла с путём оригинального layout в каталоге расширения.

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

Грабля шестая: шаблон зависит от случайной разметки

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

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

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

Что сравнить перед выбором способа правки

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

Изменения пропали после обновления

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

На одной странице всё работает, на другой нет

Сравните назначение стилей шаблона, пункт меню и набор опубликованных модулей. Часто это не ошибка CSS, а разные шаблоны или условия публикации.

Вместо страницы отображается PHP-ошибка

Верните последнюю правку и проверьте синтаксис файла. На тестовом сайте включите отладку Joomla, а на рабочем не выводите подробности ошибок посетителям.

Переопределение не обновляет данные

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

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

Составьте карту шаблона: активный стиль, файл index.php, подключённые CSS и JavaScript, позиции модулей и каталог переопределений. Для каждого изменения записывайте версию Joomla, расширения и путь к файлу. Перед обновлением сравнивайте переопределения с оригиналами, а после обновления проверяйте главную страницу, формы, меню, мобильную версию и страницы с ошибками.

Первый полезный показатель в проде — не только внешний вид, но и ошибки загрузки ресурсов в браузере: 404 для CSS, JavaScript, шрифтов и изображений быстро показывают, где шаблон перестал совпадать со структурой сайта.

¹ Переопределение, или override, — файл шаблона, который заменяет стандартную разметку расширения, не изменяя его исходные файлы.