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

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

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

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

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

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

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

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

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

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

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

Маршрут CSS ​

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
  → подключение на витрине

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

$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.

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

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

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

Маршрут JavaScript ​

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 добавляет в контроллер подвала:

$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>-обёртки:

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

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

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

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

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

<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 могут иметь собственный кеш, а браузер — кешировать связанные внешние ресурсы.

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

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

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

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

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

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

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