Модифікатори OCMOD в Opencart

<!--?xml version="1.0" encoding="utf-8"?-->
<modification>
  <name>Test</name>                <!-- Назва модифікатора -->
  <code>Test</code>                <!-- Унікальний код модифікатора -->
  <version>1.0</version>          <!-- Версія -->
  <author>Test</author>          <!-- Автор --><link />http://www.test.ru  <!-- Сайт розробника -->
 
<file path="admin/view/template/common/header.twig">  <!-- Який файл буде модифікуватися -->
  <operation>
    <search>                            <!-- Знайти код у файлі -->
      <!--[CDATA[
        <div class="container-fluid"-->
      ]]&gt;
    </search>
    <add position="after">             <!-- Додавання модифікації (після знайденого коду) -->
      <!--[CDATA[
        <p-->Тест<p>&nbsp;</p>
      ]]&gt;
    </add>
  </operation>
</file>
 
</modification>

Отже, цей приклад модифікатора змінює файл header.twig. Він знаходить рядок "<div class="container-fluid">" і після нього додає "<p>Тест</p>".

В одному xml-файлі може бути будь-яка кількість секцій <file> і, відповідно, ми можемо змінювати безліч файлів одним модифікатором.

Розберемо кожен тег модифікатора та його можливості детальніше.

File

Вказує, у якому файлі чи файлах потрібно внести зміни. Обов’язковий атрибут path містить шлях до змінюваного файлу. Може вказувати на один файл або на кілька. Для вказання кількох файлів використовується символ "|". Наприклад, внести зміни в action.php і в loader.php

<file path="system/engine/action.php|system/engine/loader.php">

Для скорочення коду можна використовувати фігурні дужки, які дозволяють вказати кілька значень через кому:

<file path="system/engine/{action,loader}.php">

Також можна використовувати символи "*" і "?", щоб вказати шлях за "маскою". Це часто буває корисно для модифікації файлів-шаблонів.

<file path="catalog/view/theme/*/template/product/product.twig">

Оскільки ми не знаємо заздалегідь, які саме теми встановлені в OpenCart, ми вказали "*" після "theme" і тоді будуть модифікуватися всі product.twig у всіх темах.

Operation

Вказує початок секції здійснюваної модифікації. Всередині File секцій <operation> може бути кілька. Тобто ми можемо робити одразу кілька змін в одному файлі. Тег Operation може мати необов’язковий атрибут error, який може приймати значення:

• skip - у разі помилки пропустити поточну секцію <operation> і перейти до наступної <operation>
• log (за замовчуванням) - у разі помилки пропустити всю секцію <file> і перейти до наступного <file>
• abort - у разі помилки перервати всі модифікації в xml-файлі

Наприклад, знайти у файлі header.twig текст "navbar-rightnav" і якщо його немає, тоді пропустити та перейти до наступної операції і знайти "navbar-right":

<file path="admin/view/template/common/header.twig">
  <operation error="skip">
    <search><![CDATA[ navbar-rightnav ]]></search>
    <add position="after"><![CDATA[
       <li>Test1</li>
    ]]></add>
  </operation>
  <operation error="skip">
    <search><![CDATA[ navbar-right ]]></search>
    <add position="after"><![CDATA[
       <li>Test2</li>
    ]]></add>
  </operation>
</file>

Якщо не вказувати атрибут error="skip", тоді на першому пошуку тексту "navbar-rightnav" вся секція <file> була б перервана і проігнорована.

Search

Вказує який текст потрібно знайти в поточній операції. Є кілька правил використання тега:

• Тег Search може бути використаний лише 1 раз усередині секції Operation.
• Пошук можна робити лише одного рядка цілком або частини рядка (не можна шукати кілька рядків одночасно).
• Текст, який шукається, потрібно розміщувати між <![CDATA[ і ]]>.
• Пробіли та переноси рядка до шуканого тексту і після шуканого тексту ігноруються (тому текст можна написати або одразу після CDATA, або з нового рядка після CDATA, як зручніше), якщо тільки не вказаний атрибут trim="false" (опис нижче).
• Зміни виконуються над усіма знайденими у файлі рядками (або частинами рядків), якщо тільки не вказаний атрибут index (опис нижче).

Спеціальні теги <![CDATA[ і ]]> - використовуються у xml-файлах для вказівки будь-яких символьних даних, що означає, що між ними може бути який завгодно текст, що містить дужки, знаки більше, менше й інші, у т.ч. і php-код, html-код тощо.

Для більш точного визначення місця внесення змін у тегі Search можуть використовуватись атрибути:

• index - вказує у якому за порядком знайденому тексті зробити зміни. Тобто якщо у файлі шуканий текст зустрічається кілька разів, тоді index дозволяє вказати номер знайденого тексту за порядком (0 - перший знайдений текст, 1 - другий тощо). Можна також вказати кілька номерів через кому.
• trim - вказує ігнорувати (true) чи ні (false) пробіли та переноси рядків до і після шуканого тексту.
• regex - якщо встановлено значення true, це означає, що шуканий текст являє собою регулярний вираз для пошуку.

Приклад: додати пункт меню "ТЕСТ".

<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'       => 'menu-test',
        'icon'     => 'fa-play',
        'name'     => 'TEST',
        'href'     => '#'
      );
    ]]></add>
  </operation>
</file>

У цьому прикладі знаходимо перше "$data['menus'][] = array(" і перед ним додаємо свій код.

Add

Тег містить текст, який буде доданий до/після знайденого або яким буде замінений знайдений текст.

Так само, як і тег Search, він має містити <![CDATA[ і ]]> між якими пишеться текст коду, що дода ється/замінюється.

У тегі Add можуть використовуватися атрибути:

• position - може приймати значення:
  • replace (за замовчуванням) - заміна знайденого тексту
  • before - додати текст перед знайденим текстом
  • after - додати текст після знайденого тексту
• offset - означає зсув щодо знайденого тексту на вказану кількість рядків. Якщо position="before", тоді зсув буде вгору від знайденого тексту, якщо position="after" або position="replace", тоді зсув буде вниз від знайденого тексту.
• trim - вказує ігнорувати (true) чи ні (false) пробіли та переноси рядків до і після шуканого тексту.

Приклад: Додати слово "Test" в адмін-панелі у списку товарів.

\
  \
    \\\
    \\Test\
 
    ]]>\
  \
\

Знаходимо 2-й за порядком текст "panel-body" (перший - це фільтр праворуч від товарів, а другий - сам список товарів) і потім додаємо код "\

Test\

Зверніть увагу: position="before" і position="after" додають код не в середину рядка, де було знайдено "panel-body", а в наступний (чи попередній) рядок. Якщо потрібно зробити додавання в середині рядка, слід використовувати position="replace" і повторивши той самий знайдений текст, ми додаємо свій.

Приклад: Додати текст перед версією opencart-а у футері

\
  \
    \\\
    \\Test\
 
{{ text\_version }}
    ]]>\
  \
\

Створивши модифікатор OCMOD в OpenCart можна змінити практично всю систему, розширити її можливості, при цьому вихідні файли не будуть зачеплені, і ви можете все повернути в початковий вигляд, просто видаливши файл-модифікатор (або відключивши його, якщо він був завантажений у базу даних).