Перейти к содержанию
  • Инструкция - Модификаторы OCMOD в OpenCart


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



×
×
  • Создать...