How OCMOD Works: Developer's Guide

How OCMOD Works

Recently, questions have become increasingly common: what is OCMOD? or how does OCMOD work? Let's try to figure it out.

OCMOD is a software package that allows you to change (add) an online store on OpenCart without changing or overwriting the source files of the online store. Yes! Change without changing! If the OCMOD add-on is created correctly, then when it is removed, the previous state of the online store is simply restored. Beauty!!!

After installation, the OCMOD modifier file creates a temporary file in the system/storage/modification/ folder, which is used by the OpenCart engine. These files are updated every time you click the "Update" button in the "Add-on Manager" of the administrative part.

Please note: if you make changes directly to files located in the system/storage/modification/ folder, you will lose all changes immediately after clicking the "Update" button! These files can be used to test the functionality of the changes you make, but then all changes must be transferred to the OCMOD file!

Installing OCMOD

OCMOD comes standard with OpenCart, starting with version 2 and does not need to be installed! The github branch is here.

What does the OCMOD modifier consist of?

An OCMOD modifier can consist of one file with an xml extension. In this case, nothing other than it is downloaded to the server, but only the instructions from this file are executed. There is a mandatory rule for the name of such a file: the file extension must be .ocmod.xml

If, in addition to instructions, we need to upload additional files to the server (for example, module files), then the file should be a zip archive with the extension .ocmod.zip. In this case, the structure of the archive must also obey certain rules:

• upload folder, which contains all files uploaded to the server in accordance with the OpenCart folder structure (up to version OpenCart 3, the upload folder is required and without it the archive cannot be uploaded through the installer in the admin panel. And even if the add-on does not have its own files and there is no need to upload files, it should must be present empty)
• install.xml file, which contains instructions for modifying the source files of the online store.
• install.sql file, which contains the SQL queries executed during the installation of the add-on.
• install.php file, which contains the PHP code that is executed during the installation of the add-on.

In addition, the OCMOD modifier may contain the necessary SQL and PHP instructions, but we will not consider them in this article.

Error in OCMOD Add-on Installer - Invalid file type

One of the ways to install a zip archive of the OCMOD add-on is to unzip the file on your computer, upload the contents of the uplod folder to the server via ftp or through the hosting panel, and then install the xml file through the add-on installer. However, if you try to load install.xml directly into the OCMOD Add-on Installer, you will receive an "invalid file type" error. How to avoid this? Easy - just rename the file to, for example, name.ocmod.xml that is, you should only install files with the extension .ocmod.xml

Let's move directly to the structure of the OCMOD XML file

 <?xml version="1.0" encoding="utf-8"?>
<modification>
 <name>Number of views per product</name>
 <code>product-page-views</code>
 <version>1.0</version>
 <author>https://ocmod.net</author>
 <link>https://ocmod.net</link>
 <file path="catalog/controller/product/product.php">
 <operation>
 <search>
 <![CDATA[$data['images'] = array();]]>
 </search>
 <add position="after">
 <![CDATA[
 	$data['view'] = $product_info['viewed'];
 ]]>
 </add>
 </operation>
 </file>
 <file path="catalog/language/en-gb/product/product.php">
 <operation>
 <search>
 <![CDATA[$_['text_search']]]>
 </search>
 <add position="before">
 <![CDATA[
 	$_['text_view'] = 'View: ';
 ]]>
 </add>
 </operation>
 </file>
 <file path="catalog/language/ru-ru/product/product.php">
 <operation>
 <search>
 <![CDATA[$_['text_search']]]>
 </search>
 <add position="before">
 <![CDATA[
 	$_['text_view'] = 'Views: ';
 ]]>
 </add>
 </operation>
 </file>
 <file path="catalog/language/uk-ua/product/product.php">
 <operation>
 <search>
 <![CDATA[$_['text_search']]]>
 </search>
 <add position="before">
 <![CDATA[
 	$_['text_view'] = 'Perspectives: ';
 ]]>
 </add>
 </operation>
 </file>
 <file path="catalog/view/theme/*/template/product/product.twig">
 <operation>
 <search index="2">
 <![CDATA[{% if review_status %}]]>
 </search>
 <add position="before">
 <![CDATA[
 	<h4>{{ text_view }}{{ view }}</h4>
 ]]></add>
 </operation>
 </file>
</modification>

The required elements of the OCMOD file structure include:

• header <?xml version="1.0″ encoding="utf-8″?>
• <modification> </modification> - no parameters
• <code> </code> - contains a unique code (you can come up with any one consisting of numbers and Latin letters)
• <name> </name> - contains the name of the modifier
• <version> </version> - modifier version
• <author> </author> - author of the modifier

Optional elements:

• <link> </link> - link to the author’s website or somewhere else.

Next is the code that is responsible for modifying files:

• <file path="catalog/controller/product/product.php"> </file> - specifies the path to the file in which changes need to be made. If you need to replace/change the same piece of code, you can use an asterisk (*), curly braces and commas:
  • <file path="catalog/view/theme/*/template/product/product.twig"> </file> (convenient to use as a replacement in all themes).
  • <file path="catalog/controller/module/{bestseller.php,featured.php,latest.php,special.php}"> </file> (Please note: the listing must be without spaces!!!)
• <operation> </operation> - since different operations can be applied to the same file, there can be several such tags in one file.

Tag <search> </search>

Next comes the search for an occurrence: <search> </search> .

Please note: the search is performed on one whole line; if more than one line needs to be replaced, you must use either the regex attribute for the <search> </search> tag or the offset attribute.

Let's take a closer look here. The question is often asked: how to adapt a module to a particular topic. This is where the answer to this question lies! <search> </search> searches for an occurrence of a piece of code. Here is part of the code from the install.xml file:

 <file path="catalog/view/theme/*/template/product/product.twig">
 <operation>
 <search index="2">
 <![CDATA[{% if review_status %}]]>
 </search>
 <add position="before">
 <![CDATA[
 	<h4>{{ text_view }}{{ view }}</h4>
 ]]></add>
 </operation>
</file>

This code searches the file catalog/view/theme/*/template/product/product.twig for part of the code:

 {% if review_status %}

This is the code for checking whether a product has reviews. It appears 3 times in the standard template.

In other templates/themes this code may appear more or less times. This is why the modifier cannot find the required occurrence of the code and add the Number of views in the product in the place we need.

An optional attribute of the <search> </search> tag: index, which must be used if the code you are looking for is not unique in a given file , as in our case. We can find the first occurrence of this code by specifying <search index="0″> </search> .

Note that the first occurrence has index="0″, not index="1″.

Optional attribute for the <search> </search> tag: regex, which allows you to search a piece of code using a regular expression.

We recommend using this regular expression tester http://uvsoftium.ru/php/regexp.php

Tag <add> </add>:

It specifies the code that will be added to the source file. Moreover, it has an important and required position attribute, which can take the following values:

• before - as the name suggests, the added code will be inserted before the code found by the <search> </search> tag
• after - as the name suggests, the added code will be inserted after the code found by the <search> </search> tag
• replace - as the name suggests, the added code will be inserted instead of the code found by the <search> </search> tag

Let's look at the code again:

 <file path="catalog/view/theme/*/template/product/product.twig">
 <operation>
 <search index="2">
 <![CDATA[{% if review_status %}]]>
 </search>
 <add position="before">
 <![CDATA[
 	<h4>{{ text_view }}{{ view }}</h4>
 ]]></add>
 </operation>
</file>

As you can see: in this case, the number of views code is added before (before) the third occurrence of the code to check for the presence of reviews

An optional attribute of the <add> </add> tag: offset , which allows you to indent the found part of the code.

 <file path="catalog/view/theme/*/template/product/product.twig">
 <operation>
 <search index="2">
 <![CDATA[{% if review_status %}]]>
 </search>
 <add position="before" offset="4">
 <![CDATA[
 	<h4>{{ text_view }}{{ view }}</h4>
 ]]></add>
 </operation>
</file>

In simple terms, find the occurrence of the code

 {% if review_status %}

and, indenting 4 lines, add the code

 <h4>{{ text_view }}{{ view }}</h4>