Инструкция - Модификаторы OCMOD в OpenCart

[admin]

Модификаторы - 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://open-cart.dev</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">"  и если его нет, тогда пропустить и перейти к следующей операции и найти "<p class="price">".

<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 расширить возможности, не затрагивая оригинальные файлы, а для возврата в исходное состояние вам просто будет достаточно удалить его.