Свои стили и скрипты

DOC · руководство пользователя · Revolution 5.x

Путь: Настройки шаблона → Основные настройки → Свои стили и скрипты

А как мне…

добавить свои стили изменить внешний вид сайта добавить свой скрипт

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

Код действует на всей витрине

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

Стили CSS

Поле Стили принимает обычные правила CSS. Обёртка <style>...</style> не нужна.

css

/* Хорошо: правило ограничено нужным компонентом */
.product-thumb .product_buttons .btn {
  border-radius: 12px;
}

Не вставляйте в поле HTML:

html

<!-- Неправильно для поля «Стили» -->
<style>
  .product-thumb { border-radius: 8px; }
</style>

Как организовать свои правила

Разделяйте независимые изменения маркированными блоками:

css

/* === REV-CUSTOM-HEADER 1.0.0 BEGIN === */
/* правила шапки */
/* === REV-CUSTOM-HEADER 1.0.0 END === */

/* === REV-CUSTOM-CATALOG 1.0.0 BEGIN === */
/* правила каталога */
/* === REV-CUSTOM-CATALOG 1.0.0 END === */

Так отдельную доработку можно найти, обновить или удалить, не затрагивая остальные.

Ограничивайте область действия

Общее правило .btn изменит кнопки по всему магазину. Чем точнее селектор, тем ниже риск побочных эффектов.

css

/* Слишком широко */
.btn { border-radius: 12px; }

/* Безопаснее */
.product-thumb .product_buttons .btn { border-radius: 12px; }

Выравнивание карточек товаров

Переключатель расположен под редактором CSS.

Режим	Что происходит	Когда выбирать
Стилями	Карточки выравниваются правилами CSS	Стандартная сетка Revolution, меньше вычислений JavaScript
Авто (js)	Высота элементов рассчитывается после загрузки страницы	Слайдеры и динамически появляющиеся карточки

Если настройка ещё не сохранялась, выбран режим Авто (js).

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

Состояние тестового магазина при проверке

Выбран режим Авто (js). Поле CSS заполнено пользовательскими стилями, поле JavaScript пустое. Это пример текущего состояния, а не универсальная рекомендация.

Скрипты

В это поле код нужно помещать вместе с тегами <script>...</script>.

html

<script>
(function ($) {
  'use strict';

  $(function () {
    document.documentElement.classList.add('rev-custom-ready');
  });
})(jQuery);
</script>

Для элементов, которые могут появиться после AJAX-загрузки, используйте делегированный обработчик:

html

<script>
(function ($) {
  'use strict';

  $(document)
    .off('click.revCustom', '[data-rev-custom-action]')
    .on('click.revCustom', '[data-rev-custom-action]', function () {
      document.documentElement.classList.toggle('rev-custom-active');
    });
})(jQuery);
</script>

Не помещайте сюда пароли, API-ключи и другие секреты: содержимое страницы доступно посетителям магазина. Не используйте непроверенный код, document.write() и общие глобальные переменные.

Безопасный порядок изменения

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

Если изменение не появилось

Симптом	Что проверить
CSS сохранён, но не действует	Кеш браузера и шаблона, правильность селектора
Правило видно, но перечёркнуто	Более точный селектор или `!important` в другом правиле
Сломана только мобильная версия	Медиазапросы и ширины 320, 375, 768 и 992 px
JavaScript отображается текстом	Наличие тегов `<script>...</script>`
Скрипт не выполняется	Консоль браузера, синтаксис, наличие целевого элемента
Действие выполняется дважды	Повторное подключение обработчика; используйте пространство имён и `.off()`

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

Откат

Удалите целиком добавленный блок между комментариями BEGIN и END, сохраните настройки и очистите соответствующий кеш. Если результат непредсказуем, восстановите полное содержимое поля из резервной копии.

Связанные разделы

DEV · техническая спецификация

DEV · техническая спецификация · Revolution 5.x

Эта версия описывает контракт данных и подтверждённый маршрут значений от формы Revolution до витрины OpenCart 3.x.

Контракт полей

Поле UI	Имя элемента формы	Тип UI	Значения / формат	Значение по умолчанию
Стили	`revtheme_footer_user_set[styles]`	`textarea`, `rows="20"`	Строка с чистым CSS, без `<style>`	Пустая строка
Выравнивание карточек	`revtheme_footer_user_set[max_height]`	Два `radio`	Строка `1` или `0` в POST; после загрузки конфигурации трактуется как truthy/falsy	`0` / «Авто (js)»
Скрипты	`revtheme_footer_user_set[scripts]`	`textarea`, `rows="20"`	HTML-фрагмент; исполняемый JS требует `<script>`	Пустая строка

Оба редактора занимают Bootstrap-колонку col-sm-11; подпись — col-sm-1. Атрибуты maxlength, pattern, required и клиентский редактор кода в исходной Twig-разметке отсутствуют.

Граница проверки валидации

Основной PHP-контроллер настроек поставляется в закодированном виде. В открытой Twig-разметке и доступном генераторе CSS отдельная проверка синтаксиса, длины или допустимых тегов не обнаружена. Это означает «валидация не подтверждена», а не гарантированное отсутствие серверной проверки.

Модель хранения

Поля отправляются одной вложенной группой revtheme_footer_user_set. В рантайме группа читается стандартным вызовом OpenCart:

php

$setting_footer_user_set = $this->config->get('revtheme_footer_user_set');

Контракт группы:

php

[
    'styles'     => string,
    'max_height' => '0' | '1',
    'scripts'    => string,
]

Физическое имя таблицы зависит от префикса БД OpenCart, поэтому в интеграциях нельзя жёстко использовать oc_setting. Работать следует через модель настроек OpenCart или определять активный префикс из конфигурации.

Маршрут CSS

text

POST revtheme_footer_user_set[styles]
  → admin/controller/revolution/revstylesheet.php
  → html_entity_decode(..., ENT_QUOTES, 'UTF-8')
  → добавление в конец $tcss
  → catalog/view/theme/revolution/stylesheet/stylesheet_change.css
  → подключение на витрине

Подтверждённая обработка:

php

$user_styles = html_entity_decode(
    $revtheme_footer_user_set['styles'],
    ENT_QUOTES,
    'UTF-8'
);

if ($user_styles) {
    $tcss .= $user_styles . "\n";
}

Следствия:

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

Выравнивание через CSS

При truthy-значении max_height генератор добавляет Flexbox-правила для контейнеров категорий, .product-layout.product-grid, .product-thumb, .caption и .description_options.

Проверка в генераторе выполнена как:

php

if ($this->request->post['revtheme_footer_user_set']['max_height']) {
    $tcss .= '/* flex rules */' . "\n";
}

Для POST-контракта безопасны только значения 0 и 1. Не передавайте произвольные truthy-строки: PHP также воспримет их как включённое состояние.

Маршрут JavaScript

text

revtheme_footer_user_set[scripts]
  → $this->config->get('revtheme_footer_user_set')
  → html_entity_decode(..., ENT_QUOTES, 'UTF-8')
  → $data['user_scripts']
  → catalog/view/theme/revolution/template/common/footer.twig
  → сырой HTML-фрагмент в нижней части страницы

OCMOD добавляет в контроллер подвала:

php

$setting_footer_user_set = $this->config->get('revtheme_footer_user_set');
$data['user_scripts'] = html_entity_decode(
    $setting_footer_user_set['scripts'],
    ENT_QUOTES,
    'UTF-8'
);

Twig выводит значение без собственной <script>-обёртки:

twig

{% if (user_scripts) %}
  {{ user_scripts }}
{% endif %}

Поэтому значение является HTML-фрагментом, а не строкой «чистого JavaScript». Для исполнения кода теги <script> обязательны. Доверять ввод этого поля можно только администраторам с правом изменять настройки темы: поле по назначению допускает выполнение произвольного клиентского кода на всей витрине.

Порядок выполнения

Пользовательский фрагмент расположен в common/footer.twig после крупного блока штатной логики подвала и до части последующей разметки Revolution. На момент исполнения обычно доступны jQuery и основные скрипты темы, но интеграция не должна полагаться на неявный порядок сторонних OCMOD-модификаций.

Рекомендуемый шаблон:

html

<script>
(function ($, window, document) {
  'use strict';

  $(function () {
    // Инициализация после готовности DOM.
  });
})(jQuery, window, document);
</script>

Для повторной инициализации и AJAX-контента применяйте именованные события и идемпотентные операции.

Кеширование и минификация

В OCMOD Revolution файл stylesheet_change.css входит в список источников для создания stylesheet_min.css. Минифицированный файл формируется, только если его ещё нет. Следовательно, после изменения CSS при включённой минификации устаревший stylesheet_min.css может потребовать удаления штатным механизмом очистки кеша.

Пользовательское поле scripts выводится как HTML в подвале и не входит в найденный список файлов, из которых собирается js_min.js. Однако HTML страницы и модификаторы OpenCart могут иметь собственный кеш, а браузер — кешировать связанные внешние ресурсы.

Матрица инвалидации

Изменение	Минимальная проверка
`styles` без минификации	Время изменения и содержимое `stylesheet_change.css`, кеш браузера
`styles` с минификацией	Перегенерация `stylesheet_change.css`, затем `stylesheet_min.css`
`max_height: 1`	Наличие Flexbox-правил в итоговом CSS
`max_height: 0`	Отсутствие генерируемого Flexbox-блока; выполнение `max_height_div()` в нужных представлениях
`scripts`	Исходный HTML страницы, консоль и сетевые ошибки

Файлы реализации

Назначение	Путь	Проверенные места в 5.x
Форма админки	`admin/view/template/revolution/revtheme.twig`	9328–9357
Генератор CSS	`admin/controller/revolution/revstylesheet.php`	293–295, 314–320
Передача скриптов в подвал	`system/revolution.ocmod.xml`	6090–6091
Вывод пользовательских скриптов	`catalog/view/theme/revolution/template/common/footer.twig`	775–777
Итоговый CSS	`catalog/view/theme/revolution/stylesheet/stylesheet_change.css`	генерируемый файл
Минифицированный CSS	`catalog/view/theme/revolution/stylesheet/stylesheet_min.css`	кешируемый результат сборки

Номера строк относятся к дистрибутиву Revolution 5.x для OpenCart 3.x и могут измениться в другой версии.

Риски интеграции

styles имеет глобальную область действия и способен менять административно не связанные компоненты витрины.
scripts — намеренная точка выполнения произвольного HTML/JS; ошибки и XSS здесь являются следствием доверенного административного ввода.
Сторонние OCMOD могут изменить порядок вывода user_scripts или версионировать URL CSS.
Сохранение всей группы может перезаписать параллельные изменения другого администратора.
Обновление Revolution может заменить Twig, OCMOD и генератор; после обновления нужно повторно сверить контракт.

Программа проверки

Сохранить резервную копию всей группы revtheme_footer_user_set.
Добавить уникальный CSS-маркер и проверить его в итоговом CSS.
Добавить безопасный JS-маркер и проверить однократное выполнение.
Проверить режимы max_height=0 и max_height=1 на категориях и слайдерах.
Повторить проверки при включённой и выключенной минификации.
Проверить desktop и mobile, консоль, корзину и checkout.
Восстановить исходную группу и подтвердить удаление маркеров.

Свои стили и скрипты ​

Стили CSS ​

Как организовать свои правила ​

Ограничивайте область действия ​

Выравнивание карточек товаров ​

Скрипты ​

Безопасный порядок изменения ​

Если изменение не появилось ​

Откат ​

Связанные разделы ​

DEV · техническая спецификация ​

Контракт полей ​

Модель хранения ​

Маршрут CSS ​

Выравнивание через CSS ​

Маршрут JavaScript ​

Порядок выполнения ​

Кеширование и минификация ​

Матрица инвалидации ​

Файлы реализации ​

Риски интеграции ​

Программа проверки ​

Свои стили и скрипты

Стили CSS

Как организовать свои правила

Ограничивайте область действия

Выравнивание карточек товаров

Скрипты

Безопасный порядок изменения

Если изменение не появилось

Откат

Связанные разделы

DEV · техническая спецификация

Контракт полей

Модель хранения

Маршрут CSS

Выравнивание через CSS

Маршрут JavaScript

Порядок выполнения

Кеширование и минификация

Матрица инвалидации

Файлы реализации

Риски интеграции

Программа проверки