Как проверять и обновлять переопределения Joomla

После обновления Joomla в панели управления может появиться уведомление об обновлении переопределений. Разберём, что оно означает, как проверить работу сайта и когда менять код. Пройдём весь процесс на Helix Ultimate: от настоящего уведомления до исправления макета изображения.

Что означает уведомление

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

Во время обновления Joomla или расширения система отслеживает изменения исходников, для которых найдены переопределения. Если исходный файл изменился, соответствующий файл шаблона попадает в список проверки.

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

Joomla не объединяет эти изменения автоматически. После обновления сайт продолжает использовать переопределение, пока вы или разработчик шаблона не измените его.

Уведомление доступно и в модуле Notifications на странице Панель управления. Нажмите плитку Есть обновления переопределений!, чтобы перейти к списку шаблонов и открыть файлы для проверки.

Подготовьте тестовую копию

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

Для примера использован Helix Ultimate 2.2.11. Шаблон и системный плагин установлены на тестовую Joomla 6.1.4, после чего Joomla обновлена до 6.2.0.

Для установки Helix на существующий сайт нужен пакет Template, а не QuickStart с готовым сайтом. Откройте Система → Установка → Расширения и установите пакет. Затем проверьте, что установлены шаблон и системный плагин Helix одной версии.

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

Откройте список и сравните файлы

Перейдите по ссылке из уведомления или откройте Система → Шаблоны → Шаблоны сайта. Выберите Helix Ultimate и вкладку Обновление переопределений.

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

Откройте файл. Переключатели Показать исходный файл и Показать различия кода позволяют посмотреть текущий оригинал и сравнение.

Это сравнение текущего оригинала с текущим переопределением. Оно не показывает отдельно, что изменилось между старой и новой Joomla. Для этого нужны исходник из резервной копии, пакет предыдущей версии или история изменений проекта.

Сначала найдите изменения между старым и новым оригиналом. Затем определите, учтены ли они в переопределении. Отличия оформления, добавленные автором шаблона, могут быть намеренными.

Учитывайте механизм Helix Ultimate

В проверенной версии Helix файл html/layouts/joomla/content/full_image.php содержит короткий загрузчик. Основная строка выглядит так:

require HelixUltimate\Framework\Platform\HTMLOverride::loadTemplate();

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

Поэтому встроенное сравнение загрузчика с оригиналом Joomla может показывать почти полностью разные файлы. Для анализа поведения откройте реализацию, которую подключает Helix. Не заменяйте загрузчик всем исходником Joomla только ради исчезновения различий.

Штатная проверка Joomla ориентируется на стандартные переопределения в папке html. Она не заменяет проверку пользовательской папки Helix overrides и файлов, которые подключаются через загрузчик.

Проверьте влияние на конкретную функцию

В Joomla 6.2 изменился макет изображения полного текста: он учитывает отдельный CSS-класс самого изображения. Проверим эту настройку на одном материале.

1. Создайте тестовый материал и откройте вкладку Изображения и ссылки.
2. В группе Изображение полного текста выберите изображение, заполните описание и подпись.
3. В поле CSS-класс введите border border-5 border-danger rounded-3. В используемом Helix эти классы Bootstrap должны добавить красную рамку и скругление. Не путайте это поле с отдельным полем Figure Class для контейнера.
4. Сохраните материал и откройте его на сайте в стиле Helix.

На тестовом сайте изображение появилось, но рамка не отобразилась. Проверка HTML показала, что Helix вывел для изображения только класс caption. Значение нового поля не попало в разметку.

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

Сравните с исходным макетом

Чтобы проверить связь с переопределением, временно отключите только нужный файл на тестовой копии. В нашем случае это загрузчик html/layouts/joomla/content/full_image.php.

В редакторе шаблона нажмите Переименовать файл и временно задайте имя full_image-check. Расширение .php Joomla добавляет отдельно. После переименования обновите страницу материала.

Без этого переопределения Joomla вывела классы из поля материала. Рамка появилась. После возврата загрузчика Helix рамка снова исчезла. При одинаковых настройках это подтверждает, что различие связано с переопределённым макетом.

Если временно отключить только пользовательский файл из папки Helix overrides, загрузчик вернётся к реализации плагина Helix. Это другой тест. Чтобы сравнить с оригиналом Joomla, важно понимать всю цепочку подключения.

Когда нужно менять код

Решение зависит от того, что изменилось в оригинале и как это влияет на используемую возможность.

В этом же обновлении у исходного radiobasic.php изменился только комментарий @deprecated со сроками переноса и удаления старого макета. Исполняемый код до и после обновления совпадает. Этот файл можно отметить проверенным без изменения реализации Helix.

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

Исправьте пользовательскую копию Helix

В проверенной связке Joomla 6.2.0 и Helix Ultimate 2.2.11 поддержка нового класса в штатном макете отсутствует. Добавим её в пользовательскую копию, сохранив остальную реализацию Helix.

Скопируйте файл plugins/system/helixultimate/overrides/layouts/joomla/content/full_image.php в templates/shaper_helixultimate/overrides/layouts/joomla/content/full_image.php. Если пользовательский файл уже существует, сначала сохраните и изучите его доработки, а затем объединяйте изменения.

Каталоги можно создать через Создать каталог в редакторе шаблона. Создавайте вложенность последовательно: overrides → layouts → joomla → content. Через Создать файл можно загрузить подготовленную копию в выбранную папку.

В копии перед присваиванием $captionText добавьте чтение класса изображения. Если поле материала пустое, используется значение из параметров:

$imageClass = empty($images->imgclass_fulltext)
    ? (string) ($params ? $params->get('imgclass_fulltext', '') : '')
    : (string) $images->imgclass_fulltext;

В массив $layoutAttr, который передаётся в LayoutHelper::render('joomla.html.image', $layoutAttr), добавьте:

'class' => $imageClass,

В условии, которое обрабатывает подпись, замените присваивание класса caption на объединение классов:

$layoutAttr['class'] = trim($imageClass . ' caption');

Это важно: прежнее присваивание $layoutAttr['class'] = 'caption'; перезаписало бы только что добавленные пользовательские классы.

Сохраните файл. Эти изменения относятся к показанной версии макета. В другой версии Helix сначала найдите соответствующие участки фактического кода.

Повторите проверку после исправления

Откройте тот же материал с теми же настройками. В нашем примере изображение получило классы border border-5 border-danger rounded-3 caption. Красная рамка появилась, подпись и разметка Helix сохранились.

Дополнительно проверены варианты с пустым CSS-классом и с пустой подписью. В первом случае рамка исчезла, а подпись осталась. Во втором рамка сохранилась, а подпись не выводилась. Исправленный вариант также проверен для гостя и после входа под Admin.

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

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

Зафиксируйте результат проверки

Если запись осталась в списке, после проверки или исправления вернитесь на вкладку Обновление переопределений. Выберите нужную строку и нажмите Действия → Отметить как проверенный.

В нашем примере так отмечен radiobasic.php, которому функциональная правка не потребовалась. Остальные записи не отмечены автоматически.

Команда Отметить как непроверенный возвращает запись в очередь. Команда Удалить из списка удаляет запись учёта, а не PHP-файл. Ни одна из этих команд не исправляет код.

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

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

Что делать после следующего обновления

Сохраните, какие файлы проверены, что изменено и какими сценариями подтверждён результат. При следующем обновлении Joomla или Helix повторите проверку затронутых макетов, включая собственные файлы вне стандартной папки html.

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