OCMOD in version 4
OCMOD is a way to change core code without editing the files themselves. An XML file describes the change: in which file to find which line and what to add next to it. The shop builds a modified copy of the file and uses it instead of the original. In versions 2 and 3 this was the main way to extend the shop; in version 4 events took its place.
When it is needed
| Task | Tool |
|---|---|
| Change data of a template, HTML, arguments or the result of a method | An event |
| Replace a template | An event that changes the template path |
| Change a line in the middle of a core method where no event reaches | OCMOD |
OCMOD is the last resort: only when there is no trigger at the place you need.
Availability
The first releases of version 4 — 4.0.0 and 4.0.1 — had no OCMOD at all. It returned in 4.0.2. If your release has it, the admin panel has the item Extensions → Modifications.
A modification file
<?xml version="1.0" encoding="utf-8"?>
<modification>
<name>Acme Hello: note in the cart</name>
<code>acme_hello_cart</code>
<version>1.0.0</version>
<author>Acme</author>
<link>https://example.com</link>
<file path="catalog/controller/checkout/cart.php">
<operation>
<search><![CDATA[$data['footer'] = $this->load->controller('common/footer');]]></search>
<add position="before"><![CDATA[
$data['acme_note'] = $this->config->get('module_acme_hello_text');
]]></add>
</operation>
</file>
</modification>The file says: in the cart controller find the line that loads the footer and insert a new line before it. The variable acme_note becomes available in the cart template.
| Tag | Meaning |
|---|---|
code | A unique code of the modification |
file path | The file to change, from the site root |
search | The line to find, exactly as in the file |
add position | Where to put the new code: before, after or replace |
Where the file goes
The file has a name ending with .ocmod.xml and is included in the archive of the extension. Where exactly in the archive it must be and what it must be called is decided by the installer, and this differs between releases — look at the documentation of your release or at a working extension with OCMOD for it.
Applying
After the package is installed, open Extensions → Modifications and press the refresh button. The shop rereads all modification files and builds modified copies in system/storage/ — the original files in catalog/ and admin/ stay unchanged. Open the cart page — the new variable is available in its template.
The same refresh is needed after every change of the XML file and after an update of the shop.
The same task with an event
The example above does not need OCMOD. A handler of the trigger catalog/view/checkout/cart/before adds the same variable to $data — without searching for a line of code that may change in the next release.
Common mistake
The search line contains a fragment that differs in another release — an extra space, a renamed variable. The line is not found, the modification is silently skipped, and the feature disappears after an update. Search for the shortest stable fragment, and after every update check the modification log on the same page.