Joomla: частые ошибки при работе с шаблоном

Большинство проблем новичка в Joomla начинается не с плохого CSS, а с неверного места для правки: изменили неактивный стиль, отредактировали файл ядра, забыли очистить кеш или написали селектор, которого нет на странице. Ниже — практический маршрут для Joomla 5.x и стандартного шаблона Cassiopeia: от проверки активного стиля до безопасного CSS и поиска причин, если результат не появился. На базовую настройку закладывайте 30–60 минут.

Что подготовить до начала

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

Названия пунктов меню зависят от языка панели и версии Joomla. В русской локализации нужный раздел обычно находится в области Система → Шаблоны сайта. В статье используется Cassiopeia из Joomla 5.x; сторонний шаблон может иметь другой путь к CSS и собственные настройки.

Главное правило новичка: сначала выясните, какой файл реально загружается на странице, и только потом меняйте его.

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

Пошаговая настройка без опасных правок

1. Определите активный шаблон и стиль

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

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

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

2. Не редактируйте файлы ядра Cassiopeia

Не меняйте файлы в каталоге шаблона, если это не временная диагностика и у вас нет копии. При обновлении Joomla или шаблона такие изменения могут исчезнуть. Для собственных CSS-правок используйте user.css, а для вывода компонентов — штатное переопределение шаблона.

У Cassiopeia пользовательский CSS обычно размещают по пути media/templates/site/cassiopeia/css/user.css. Если на сайте установлен другой шаблон, не копируйте этот путь вслепую: сначала откройте его документацию или список файлов в панели Joomla.

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

3. Создайте user.css для собственных стилей

В редакторе файлов активного стиля найдите каталог CSS и создайте файл user.css, если его ещё нет. В некоторых сборках файл удобнее создать через файловый менеджер хостинга. Не помещайте пользовательские правила в минифицированный файл шаблона: его содержимое может пересобраться или измениться после обновления.

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

/* user.css для Joomla 5.x и шаблона Cassiopeia */
:root {
  --site-brand-color: #164e63;
}

.header {
  background: var(--site-brand-color);
}

.container-header .mod-menu a,
.container-header .mod-menu span {
  color: #ffffff;
}

.btn-primary {
  background-color: var(--site-brand-color);
  border-color: var(--site-brand-color);
}

@media (min-width: 992px) {
  .site-grid {
    column-gap: 2rem;
  }
}

Классы Cassiopeia могут отличаться после изменения разметки или версии. Если правило не сработало, не добавляйте сразу десять !important. Сначала найдите фактический класс элемента в инструментах разработчика.

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

4. Найдите элемент через инструменты разработчика

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

Если правило отображается зачёркнутым, проблема не в кеше. Обычно оно проигрывает по специфичности или загружается раньше более точного правила. Скопируйте реальный класс из DOM и ограничьте правило областью блока, например .container-header .mod-menu a, но не копируйте длинный случайный путь из всех родительских элементов.

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

5. Очистите кеш Joomla и браузера

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

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

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

6. Проверьте мобильную версию и обновление

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

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

Частые ошибки и их исправление

«Я изменил CSS, но ничего не произошло»

Проверьте активный стиль страницы, путь к файлу, наличие ссылки на CSS в HTML и кеш. Частая причина — редактирование user.css одного шаблона, когда нужный пункт меню назначен другому стилю. Вторая причина — селектор из старого шаблона, которого нет в текущей разметке.

Правило есть, но браузер его зачёркивает

Ваше правило проиграло более специфичному селектору или появилось раньше другого файла. Сначала увеличьте точность селектора только для конкретного блока. !important оставляйте для редких исключений: если использовать его повсюду, следующую правку станет сложнее объяснить и отменить.

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

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

После редактирования PHP сайт показывает ошибку

Белый экран или сообщение о синтаксической ошибке обычно означает ошибку в PHP-файле шаблона, а не в CSS. Верните последнюю рабочую копию, включите подробный вывод ошибок только на тестовом сайте и посмотрите журнал PHP. Не исправляйте такой файл на рабочем сайте вслепую через встроенный редактор, если у вас нет доступа к резервной копии.

Изменение видно администратору, но не посетителю

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

Когда нужен не CSS, а переопределение

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

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

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

Создайте тестовую копию сайта или отдельную тестовую страницу, перенесите в неё один небольшой стиль и проверьте его в Joomla 5.x на компьютере и телефоне. Затем добавьте контрольную точку: после обновления Joomla открывайте страницу, проверяйте наличие user.css, отсутствие горизонтальной прокрутки и ошибки в консоли браузера. Для следующего шага изучите официальное руководство по переопределениям шаблона, если вам нужно менять не внешний вид, а HTML вывода компонента.