Переопределение шаблона в Joomla: layout overrides

В Joomla 5.x внешний вид статьи, модуля или системного блока можно изменить без редактирования файлов ядра: создайте override в шаблоне и меняйте его копию. Обычно такая работа занимает 10–20 минут, но ошибка в пути или кэше приводит к эффекту «файл изменил, а сайт остался прежним».

Что именно переопределяет Joomla

В Joomla есть два близких механизма, которые часто называют одним словом.

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

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

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

Layout¹ — отдельный PHP-файл разметки, который расширение может вызывать из разных мест. Его можно переопределить, не переписывая весь экран компонента.

Способ 1. Создать override из панели Joomla

Для Joomla 5.x используйте административный раздел Система → Шаблоны → Шаблоны сайта. Названия пунктов могут немного отличаться в локализации и в Joomla 4.x, но принцип тот же.

1. Откройте активный шаблон. В списке шаблонов выберите шаблон, который назначен нужному пункту меню. Если на сайте несколько шаблонов или стилей, проверьте назначение в разделе меню. Проверка: вы видите имя активного шаблона и его файлы.
2. Запустите создание переопределения. Нажмите кнопку создания overrides и выберите расширение: компонент, модуль или плагин, если он поддерживает шаблонный вывод. Проверка: Joomla показывает список представлений и доступных layout-файлов.
3. Выберите нужную точку вывода. Для стандартной статьи это обычно компонент материалов, представление статьи и файл default. Для списка материалов нужен другой view, поэтому не копируйте файл статьи наугад. Проверка: новый файл появляется в дереве файлов активного шаблона.
4. Откройте копию и внесите минимальное изменение. Например, добавьте класс к обёртке заголовка или переставьте блок даты. Сначала изменяйте один участок, чтобы было понятно, что именно сработало. Проверка: файл сохраняется без сообщения об ошибке.
5. Очистите кэш и проверьте страницу без кэша браузера. Откройте материал в режиме инкогнито или выполните жёсткое обновление. Проверка: в исходном HTML появляется новый класс или изменённая структура.

Панель удобна тем, что Joomla сама создаёт правильную структуру каталогов. Для первой правки это безопаснее ручного копирования: меньше риск перепутать компонент, view и layout.

Способ 2. Создать override вручную

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

templates/ИМЯ_АКТИВНОГО_ШАБЛОНА/html/com_content/article/default.php

Здесь com_content — компонент материалов, article — представление одной статьи, а default.php — выбранный layout. Для другого расширения путь будет другим. Не подставляйте этот путь для модуля: у модуля собственная структура, которую лучше сначала сгенерировать в панели Joomla.

Для переопределения отдельного layout обычно используется каталог html/layouts внутри активного шаблона. Точный вложенный путь зависит от того, как расширение подключает исходный layout. Откройте оригинальный файл в каталоге расширения и сохраните в шаблоне ту же относительную структуру. Если вы не уверены в расположении, сначала создайте override через админку: она покажет ожидаемый путь.

Безопасная правка PHP-файла

Не заменяйте весь файл коротким самодельным шаблоном, если не знаете, какие переменные и блоки передаёт представление. Сначала скопируйте оригинал, затем измените только нужный участок. Например, в override статьи Joomla 5.x можно добавить класс к заголовку, сохранив объект материала:

<h1 class="article-title article-title--compact">
    <?php echo $this->item->title; ?>
</h1>

Фрагмент предназначен для вставки в существующий PHP-шаблон, а не для публикации как отдельный файл. Синтаксис вывода и доступные свойства зависят от конкретного расширения. Перед заменой блока сравните его с оригиналом текущей версии Joomla и сохраните резервную копию.

Что выбрать: представление или отдельный layout

Критерий простой: если меняется конкретный экран, начинайте с view override. Если один и тот же фрагмент используется в нескольких местах и вы хотите изменить его везде, ищите layout.

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

Изменён неактивный шаблон

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

Выбран не тот view

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

Сработал кэш

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

После обновления исчезли переменные

Расширение могло изменить исходный layout. Сравните ваш override с новым оригинальным файлом. Особенно внимательно проверьте переименованные блоки, условия и обращения к свойствам объекта.

Белый экран или ошибка 500

Чаще всего причина — синтаксическая ошибка PHP или обращение к переменной, которой нет в этом представлении. Верните последнюю рабочую версию файла, включите журналирование ошибок только на тестовом сайте и исправляйте изменение по одному.

Как обновлять override без сюрпризов

Переопределение не копируется автоматически из обновлённого компонента. Именно поэтому оно одновременно защищает ядро и создаёт технический долг: оригинал развивается, а копия в шаблоне остаётся старой.

• Храните overrides в Git вместе с шаблоном.
• Записывайте в комментарии, какую версию Joomla и расширения вы проверяли.
• После обновления сравнивайте оригинальный файл с override, а не только проверяйте главную страницу.
• Тестируйте статью, категорию, мобильную ширину и страницы с незаполненными полями.

Не редактируйте файлы внутри administrator/components, components и modules ради постоянного изменения разметки. При обновлении расширения такая правка будет потеряна.

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

После первой правки добавьте override в репозиторий и создайте тестовую страницу, где видны все варианты данных: длинный заголовок, пустая дата, изображение и текст без вступления. Затем обновите Joomla на тестовом окружении и сравните оригинальный layout с вашей копией. В продакшене следите не только за внешним видом, но и за ошибками PHP после обновлений расширений.