# Revolution 5.x: свои стили и скрипты

> Канонический контекст сущности `revolution.custom_code` для OpenCart 3.x. Проверен по форме админки, открытому PHP-генератору CSS, OCMOD и Twig шаблона Revolution 5.x.

## Инструкция агенту

1. Применяй этот контекст только к совместимой версии Revolution. Для другой версии сначала перепроверь исходники.
2. Не превращай неопределённости в факты.
3. До изменения выполни предусловия безопасности и сохрани несвязанный код.
4. Не изменяй production без явного разрешения пользователя.
5. После изменения выполни проверки результата и критических сценариев магазина.
6. При расхождении документации с исходниками приоритет имеют исходники установленной версии.

Каноническая HTML-страница: https://rev.uask.pro/settings/custom-code.html

- DOC: https://rev.uask.pro/settings/custom-code.html#doc
- DEV: https://rev.uask.pro/settings/custom-code.html#dev
- AI: https://rev.uask.pro/settings/custom-code.html#ai
- JSON: https://rev.uask.pro/ai/revolution.custom-code.json

## Назначение

Раздел позволяет администратору:

- добавить глобальный пользовательский CSS;
- вывести доверенный HTML/JavaScript-фрагмент в подвале витрины;
- выбрать CSS- или JavaScript-стратегию выравнивания товарных карточек.

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

Уровень риска изменения: **высокий**. CSS и JavaScript действуют глобально на витрине.

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

### styles

- Form name: `revtheme_footer_user_set[styles]`
- UI: `textarea`, `rows="20"`
- Тип: строка с чистым CSS
- Обёртка `<style>`: запрещена
- Пустое значение: пользовательский CSS не добавляется
- Область действия: страницы витрины, подключающие стили Revolution

Поток данных:

```text
POST styles
→ html_entity_decode(ENT_QUOTES, UTF-8)
→ добавление в конец $tcss
→ catalog/view/theme/revolution/stylesheet/stylesheet_change.css
```

### max_height

- Form name: `revtheme_footer_user_set[max_height]`
- UI: два `radio`
- Допустимые значения: строка `0` или `1`
- Значение по умолчанию при отсутствии ключа: `0`

Значения:

- `0` — **Авто (js)**: элементы измеряются функцией `max_height_div()`;
- `1` — **Стилями**: генератор добавляет Flexbox-правила в итоговый CSS.

### scripts

- Form name: `revtheme_footer_user_set[scripts]`
- UI: `textarea`, `rows="20"`
- Тип: доверенный HTML-фрагмент
- Для исполнения JavaScript обязательна обёртка `<script>...</script>`
- Секреты и API-ключи хранить запрещено
- Область действия: все страницы, использующие подвал Revolution

Поток данных:

```text
config revtheme_footer_user_set.scripts
→ html_entity_decode(ENT_QUOTES, UTF-8)
→ $data['user_scripts']
→ raw output в common/footer.twig
```

## Кеширование

- Основной генерируемый файл: `catalog/view/theme/revolution/stylesheet/stylesheet_change.css`.
- При минификации он входит в сборку `catalog/view/theme/revolution/stylesheet/stylesheet_min.css`.
- Устаревший `stylesheet_min.css` может скрыть сохранённое изменение.
- Поле `scripts` не входит в найденный список файлов для сборки `js_min.js`.
- Ручное редактирование генерируемого CSS не является устойчивым источником изменений.

## Безопасное изменение

Предусловия:

1. Подтвердить целевое окружение.
2. Прочитать и сохранить полную резервную копию `revtheme_footer_user_set`.
3. Определить один уникальный маркированный блок и его версию.
4. Не передавать и не сохранять секреты.

Правила изменения:

- менять один независимый блок за раз;
- сохранять весь несвязанный существующий код;
- ограничивать CSS целевым компонентом;
- делать JavaScript обёрнутым и идемпотентным;
- для AJAX-контента использовать делегированные именованные события;
- не использовать генерируемый CSS как исходник.

Постусловия:

- ожидаемый маркер присутствует в итоговом CSS или HTML;
- в консоли нет новых ошибок;
- desktop и mobile не получили неожиданного переполнения;
- меню, корзина, формы и checkout продолжают работать.

Откат: удалить только версионированный маркированный блок. Если точечный откат невозможен — восстановить полную резервную копию группы настроек.

## Диагностика

### CSS сохранён, но отсутствует

1. Найти уникальный маркер в `stylesheet_change.css`.
2. Проверить права записи и владельца файла.
3. Очистить кеш темы и браузера.
4. При минификации пересобрать `stylesheet_min.css`.

### CSS присутствует, но не действует

Проверить совпадение селектора, специфичность, порядок источников, медиазапрос и состояние элемента.

### JavaScript отображается текстом

Причина: отсутствует `<script>`-обёртка.

### JavaScript не выполняется

Проверить синтаксис, консоль, существование целевого элемента, доступность jQuery и момент инициализации.

### Обработчик выполняется повторно

Проверить дублирование фрагмента; использовать пространство имён события и `.off()` перед `.on()`.

### Карточки разной высоты

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

## Доказательства

| Утверждение | Файл | Строки в Revolution 5.x |
|---|---|---|
| Поля UI и значения по умолчанию | `admin/view/template/revolution/revtheme.twig` | 9328–9357 |
| Декодирование/добавление CSS и Flexbox | `admin/controller/revolution/revstylesheet.php` | 293–295, 314–320 |
| Чтение и декодирование scripts | `system/revolution.ocmod.xml` | 6090–6091 |
| Raw-вывод `user_scripts` | `catalog/view/theme/revolution/template/common/footer.twig` | 775–777 |

Номера строк являются подсказками только для Revolution 5.x.

## Неопределённости

- Серверная валидация при сохранении не подтверждена: основной контроллер настроек поставляется в закодированном виде.
- Политика ответа: сообщать как `unverified`, не утверждать, что валидация отсутствует.