Модификаторы - OCMOD
OCMOD - Модификаторы в OpenCart - это разновидность расширений, позволяющих вносить изменения в функционал или внешний вид, не затрагивая оригинальные файлы. Тем самым обеспечивается неизменность оригинальных файлов самого OpenCart, при том, что появляется возможность заменять или расширять необходимый функционал.
История появления модификаторов началась с vQmod в opencart версии 1.5х, и уже в версии opencart 2x он был усовершенствоваван и преобразован в OCMOD. В отличии от vQmod который устанавливался отдельно, OCMOD внедрён по умолчанию как стандартный функционал в CMS OpenCart2х и выше.
OCMOD - Модификатор в OpenCart - расширение представляющее из себя XML файл, которое содержит набор инструкций о том, в каких оригинальных файлах OpenCart-а, в каких местах, какой код нужно заменить, добавить или удалить. OpenCart при выполнении инструкций xml файла создает копии исходных файлов в специальную директорию кэша модификаторов с внесёнными изменениями в этих копиях. В результате, при работе сайта используются измененные файлы, а не их оригинальные файлы.
Модификатор OCMOD может быть как самостоятельным модулем, изменяющим или расширяющим стандартный функционал, так и входить в состав полноценного модуля с дополнительными php, tpl или twig и прочими файлами.
Структура архива OCMOD модификатора
image/catalog/doc/ru/ocmod/ocmod.jpg
Название архива модификатора - должно быть задано в соответствии с требованиямя OCMOD - "название_файла".ocmod.zip , где вместо "название_файла" вы пишите свое название без кавычек. Таким образом, название архива всегда должно заканчиваться ".ocmod.zip", иначе система проигнорирует модификатор.
Начиная с версии OpenCart 3x предполагается, что модификатор будет использоваться в составе полного модуля в виде архива - в отличии от OpenCart2x, где файл модификатора в виде "название_файла".ocmod.xml можно было загружать через установщик расщирений прямо в папку system, расположенную в корне сайта. Соответственно, при использовании файла модификатора в составе полного модуля и при его загрузке через административную часть в разделе Расширения > Установка расширений название файла-модификатора в архиве должно быть install.xml.
В OpenCart 3x файл-модификатор также можно загрузить в папку system на постоянное размещение, используя FTP клиент, при условии, что название файла модификатора будет соответствовать требованиям OCMOD в виде "название_файла".ocmod.xml .
Директории
Кэш модификаторов - все изменённые модификатором файлы располагаются в папке system/storage/modification с такой же точно структурой папок, как и корень сайта, кроме папки image. Т.е. если вы сделали модификатор для файла /admin/controller/catalog/product.php то его измененная копия будет находится по пути system/storage/modification/admin/controller/catalog/product.php.
Логи модификаторов - распалагаются в папке system/storage/logs , в ней находятся 2 основных лог-файла:
- ocmod.log - ведет запись об оработке и последовательности выполнении инструкций модификаторов,
- error.log - содержит ошибки, произошедшие при преобразовании.
Обновление кэша модификаторов
Чтобы система увидела файлы-модификаторы и выполнила их инструкции, необходимо нажать кнопку "Обновить" в правом верхнем углу на странице Модификаторы.
Возможны ситуации, когда кэш обновлён, но изменения на сайте не вступили в силу. Обычно это связано с тем, что на сайте используются дополнительные модули кэширования, ускорители загрузки и т.п., в которых также необходимо обновить кэш.
Синтаксис модификатора OCMOD
Файл модификатора OCMOD обязательно должен содержать общую описательную часть и инструкции по изменению файлов:
<?xml version="1.0" encoding="utf-8"?> <modification> <name>Мod</name> <!-- Название модификатора --> <code>mod_dev</code> <!-- Уникальный код модификатора --> <version>1.0</version> <!-- Версия модификатора --> <author>Develop</author> <!-- Автор модификатора --> <link>https://opencart.club</link> <!-- Сайт разработчика --> <file path="catalog/controller/product/category.php"> <!-- Файл который будет модифицироваться --> <operation> <search> <!-- Поиск кода в файле --> <![CDATA[ $result['name'], ]]> </search> <add position="after"> <!-- Добавление модификации (после найденного куска кода) --> <![CDATA[ 'sku' => $result['sku'], ]]> </add> </operation> </file> </modification>
Данный пример модификатора меняет файл category.php.
Он находит кусок строчки кода "$result['name']," и сразу за ним добавляет "'sku' => $result['sku'],".
В одном xml файле может быть любое количество секций <file> и возможность менять любое количество файлов одним модификатором.
Теги модификатора OCMOD и их функциональность
Тег - File
Указывает, в каком файле или файлах нужно внести изменения. Обязательный атрибут path содержит путь до изменяемого файла. Может указывать на один файл или на несколько. Для указания нескольких файлов, расположенных в разных папках, используется символ "|". Например, внести изменения в category.php, manufacturer.php, search.php и в special.php .
<file path="catalog/controller/product/category.php|catalog/controller/extension/module/special.php">
Для сокращения кода можно использовать фигурные скобки, которые позволяют указать несколько значений через запятую: Например, внести изменения сразу в четыре файла category.php, manufacturer.php, search.php и в special.php. при этом суфикс .php можно вынести за фигурные скобки.
.
<file path="catalog/controller/product/{category,manufacturer,search,special}.php">
Так же можно использовать символы "*" и "?", чтобы указать путь по "маске". Бывает полезно для модификации файлов шаблонов.
<file path="catalog/view/theme/*/template/product/category.twig">
Т.к. мы не знаем заранее, какие именно темы установлены в OpenCart, мы указали "*" после "theme", тогда будут модифицироваться все category.twig во всех шаблонах, находящихся в папке "theme".
Тег - Operation
Указывает начало секции производимой модификации. Внутри file секций <operation> может быть несколько. Т.е мы можем делать сразу несколько изменений в одном файле. Тег operation может иметь необязательный атрибут error, который может принимать значения:
- skip - в случае ошибки пропустить текущую секцию <operation> и перейти к следующей <operation>
- log (по умолчанию) - в случае ошибки пропустить всю секцию <file> и перейти к следующему <file>
- abort - в случае ошибки прервать все модификации в xml файле
Например, найти в файле category.twig код "<div class="caption">" и если его нет, тогда пропустить и перейти к следующей операции
<file path="catalog/view/theme/*/template/product/category.twig"> <operation error="skip"> <search><![CDATA[<div class="caption">]]></search> <add position="after"><![CDATA[ <span class="sku">{{ product.sku}}</span> ]]></add> </operation> <operation error="skip"> <search><![CDATA[<p class="price">]]></search> <add position="before"><![CDATA[ <span class="sku">{{ product.sku}}</span> ]]></add> </operation> </file>
Если не указать атрибут error="skip", тогда на первом поиске текста "<div class="caption">" вся секция <file> будет прервана и проигнорирована.
Тег - Search
Указывает, какой текст необходимо найти в текущей операции. Содержит несколько правил использования тега:
- Тег search может быть использован только 1 раз внутри секции operation.
- Поиск можно делать только 1 строки целиком или части строки (нельзя искать несколько строк одновременно).
- Искомый текст необходимо размещать строго между <![CDATA[ и ]]>.
- Пробелы и переносы строки до искомого текста и после искомого текста игнорируются, текст можно написать или сразу после CDATA или с новой строки после CDATA, если только не указан атрибут trim="false".
- Изменения применятся ко всем найденным в файле строчкам кода или их частям, если не указан атрибут index .
Специальные теги <![CDATA[ и ]]> - используются в xml файлах для указания любых символьных данных, что означает, что между ними может находиться любой текст, содержащий скобки, значки больше, меньше и прочие, в том числе html и php код.
Тег search содержит следующие атрибуты, которые используются для наиболее точного определения места внесения изменения:
- index - указывает, в каком по порядку найденном тексте внести изменения. Т.е. если в файле искомый текст встречается несколько раз, тогда index позволяет указать номер найденного по порядку текста (0 всегда первый найденный текст, 1 - второй и т.д.) Можно также указать несколько номеров через запятую.
- trim - указывает игнорировать (true) или нет (false) пробелы и переносы строк до и после искомого текста.
- regex - если установлено значении true, значит искомый текст представляет собой регулярное выражение для поиска.
Пример: поиск атрибутом index среди схожих строчек кода.
<file path="admin/controller/common/column_left.php"> <operation> <search index="0" trim="true"><![CDATA[ $data['menus'][] = array( ]]></search> <add position="before"><![CDATA[ $data['menus'][] = array( 'id' => 'new_menu', 'icon' => 'fa-menu', 'name' => 'New Menu', 'href' => 'new-menu/' ); ]]></add> </operation> </file>
В примере по index найдена первая строчка кода "$data['menus'][] = array(" и перед ней добавляем свой код.
Тег - Add
Тег add содержит текст, который будет заменён или добавлен до или после искомого текста.
Так же, как и тег search, тег add должен содержать <![CDATA[ и ]]>, между которыми вставляется текст кода, который будет добавлен или на который будет заменён искомый текст.
Тег add имеет свои атрибуты:
-
position - может принимать значения:
- replace (по умолчанию) - замена найденного текста
- before - добавить текст перед найденным текстом
- after - добавить текст после найденного текста
- offset - означает смещение относительно найденного текста на указанное количество строк. Если position="before", тогда смещение будет вверх от найденного текста, если position="after" или position="replace", тогда смещение будет вниз от найденного текста.
- trim - указывает игнорировать (true) или нет (false) пробелы и переносы строк до и после искомого текста.
Пример: Добавим ссылку "Link" в футер на фронтальной части.
<file path="catalog/view/theme/default/template/common/footer.twig"> <operation> <search index="1" trim="true"><![CDATA[ <ul class="list-unstyled"> ]]></search> <add position="after" offset="1" trim="true"><![CDATA[ <li><a href="#">Link</a></li> ]]></add> </operation> </file>
Атрибут index="1" находит 2-й по порядку код <ul class="list-unstyled">, затем используя атрибут offset="1" на одну строку ниже найденного текста добавляет код <li><a href="#">Link</a></li>.
Модификатор OCMOD позволяет в OpenCart расширить возможности, не затрагивая оригинальные файлы, а для возврата в исходное состояние вам просто будет достаточно удалить его.