OCMOD Modifications in Opencart

18 January 2023
Comment :0
Views: 6813

Modifiers in OpenCart are a special type of modules that allow you to make changes to functionality or design without touching the original system files. This keeps OpenCart’s core files stable while letting you modify or extend the platform’s capabilities. This article describes how to create your own modifier for OpenCart and what possibilities modifiers provide.

Initially, the concept of modifiers was introduced with vQmod in OpenCart version 1.5, and then it was improved and turned into OCMOD, which became standard functionality of OpenCart starting from version 2.1. Thus, a modifier in OpenCart is a tool for making changes to the system without directly affecting the core files.

An OpenCart modifier is a module in the form of an XML file that contains a series of instructions on what changes need to be made to the code of the original OpenCart files: replace, add, or remove. OpenCart executes these instructions by creating duplicates of the source files in a separate folder (the modification cache) and applying changes to these copies. As a result, the site uses the modified files instead of the originals.

An OCMOD modifier can act as an independent module that modifies or extends standard capabilities, or be part of a full-featured module that includes additional php, twig, js, css, and other files.

File names and directories

Modifier file name - must follow the pattern <file_name>.ocmod.xml, where you put your own name instead of <file_name>. Thus, the file name must always end with ".ocmod.xml", otherwise the system will not “see” the modifier and will ignore it.
Exception: when the modifier is intended to be used as part of a complete module in an archive - in this case, the modifier file name inside the archive must be install.xml.

Modifier file location - the system folder in the site root. The modifier file can also be uploaded into the database for permanent placement via the extension installer. However, during development it is more convenient to save the file in system and edit it there to check the result, and when development is finished, upload the modifier as a module into the database.

Modification cache location - the /storage/modification folder with the same structure as the site root. That is, if you made a modifier for the file /admin/controller/catalog/product.php then its modified copy will be located at /storage/modification/admin/controller/catalog/product.php. There you will see the changes made by your modifier.

Log location - the /storage/logs folder. It contains 2 main log files: ocmod.log - shows how modifier files were processed, in what order, and how instructions were executed, and the error.log log file - contains errors that occurred during transformation.

Updating the modification cache

For the system to recognize modifier files and apply their instructions, you need to click the "Refresh" button on the modifications page.

Sometimes after updating the cache, changes are not displayed on the site. This usually happens because the site uses additional caching modules or performance tools where cache updates may also be required.

OCMOD modifier syntax

An OCMOD modifier file must contain a general descriptive section and file change instructions. I will start the syntax breakdown with a simple example that adds the word "Test" in the administrator header:

 <!--?xml version="1.0" encoding="utf-8"?--> <modification>   <name>Test</name>                <!-- Modifier name -->   <code>Test</code>                <!-- Unique modifier code -->   <version>1.0</version>           <!-- Version -->   <author>Test</author>            <!-- Author --><link />http://www.test.ru  <!-- Developer site -->   <file path="admin/view/template/common/header.twig">  <!-- Which file will be modified -->   <operation>     <search>                           <!-- Find code in the file -->       <!--[CDATA[         <div class="container-fluid"-->       ]]&gt;     </search>     <add position="after">             <!-- Add modification (after the found code) -->       <!--[CDATA[         <p-->Test<p>&nbsp;</p>       ]]&gt;     </add>   </operation> </file>   </modification>

So, this modifier example changes the header.twig file. It finds the line "<div class="container-fluid">" and adds "<p>Test</p>" after it.

A single xml file can contain any number of <file> sections, and therefore we can change many files with one modifier.

Let’s examine each modifier tag and its capabilities in more detail.

File

Specifies which file or files need to be changed. The required path attribute contains the path to the file being modified. It can point to one file or several. To specify multiple files, use the "|" character. For example, make changes to action.php and loader.php

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

To shorten the code, you can use curly braces to specify several values separated by commas:

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

You can also use the "*" and "?" characters to specify a path by a "mask". This is often useful for modifying template files.

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

Since we do not know in advance which themes are installed in OpenCart, we specified "*" after "theme" so all product.twig files in all themes will be modified.

Operation

Marks the start of a modification section. Inside File sections there can be several <operation> blocks. That is, we can make several changes in one file at once. The Operation tag can have an optional error attribute with the following values:

skip - in case of an error, skip the current <operation> section and proceed to the next <operation>
log (default) - in case of an error, skip the entire <file> section and proceed to the next <file>
abort - in case of an error, stop all modifications in the xml file

For example, find "navbar-rightnav" in header.twig and if it is not there, then skip and proceed to the next operation to find "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>

If you do not specify the error="skip" attribute, then on the first search for "navbar-rightnav" the entire <file> section would be interrupted and ignored.

Search

Specifies which text needs to be found in the current operation. There are several rules for using the tag:

The Search tag can be used only once within an Operation section.
You can search only for 1 full line or a part of a line at a time (you cannot search for multiple lines simultaneously).
The text to be found must be placed between <![CDATA[ and ]]>.
Spaces and line breaks before and after the target text are ignored (so the target text can be written right after CDATA or on a new line after CDATA, whichever you prefer), unless the trim="false" attribute is specified (described below).
Changes are applied to all matches found in the file unless the index attribute is specified (described below).

The special tags <![CDATA[ and ]]> are used in xml files to include any character data, which means any text can be placed between them, including brackets, less-than/greater-than signs, and others, including php code, html code, etc.

For more precise placement of changes, the Search tag can use the following attributes:

index - indicates in which occurrence the change should be made. If the target text appears multiple times in the file, index allows you to specify the occurrence number (0 - the first occurrence, 1 - the second, etc.). You can also specify several numbers separated by commas.
trim - indicates whether to ignore (true) or not (false) spaces and line breaks before and after the target text.
regex - if set to true, the target text is treated as a regular expression.

Example: add a "TEST" menu item.

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

In this example, we find the first occurrence of "$data['menus'][] = array(" and insert our code before it.

Add

The tag contains the text that will be added before/after the found text or will replace the found text.

Just like the Search tag, it must contain <![CDATA[ and ]]>, with the code to be added/replaced written between them.

The Add tag can use the following attributes:

position - can take the values:
- replace (default) - replace the found text
- before - add text before the found text
- after - add text after the found text
offset - means a shift relative to the found text by the specified number of lines. If position="before", the shift is upward from the found text, if position="after" or position="replace", the shift is downward from the found text.
trim - indicates whether to ignore (true) or not (false) spaces and line breaks before and after the target text.

Example: Add the word "Test" in the admin panel in the product list.

 <file path="admin/view/template/catalog/product_list.twig">   <operation>     <search index="1" trim="true"><![CDATA[       panel-body     ]]></search>     <add position="after" offset="1" trim="true"><![CDATA[       <p>Test</p>     ]]></add>   </operation> </file>

We find the 2nd occurrence of "panel-body" (the first is the filter to the right of the products, and the second is the product list itself) and then add the code "<p>Test</p>" one line below the found text.

Note: position="before" and position="after" add code not in the middle of the line where "panel-body" was found, but on the next (or previous) line. If you need to add in the middle of a line, use position="replace" and by repeating the same found text, add your own.

Example: Add text before the OpenCart version in the footer

 <file path="admin/view/template/common/footer.twig">   <operation>     <search><![CDATA[       {{ text_version }}     ]]></search>     <add position="replace" trim="true"><![CDATA[       <p>Test</p>{{ text_version }}     ]]></add>   </operation> </file>

By creating an OCMOD modifier in OpenCart, you can change almost the entire system, extend its capabilities, while the original files are not affected and you can revert everything to its original state simply by removing the modifier file (or disabling it if it was uploaded into the database).

Рекомендуем посмотреть