10 Secrets that will make you a master of Opencart Events

10 Secrets that will make you a master of Opencart Events

If you are an Opencart Developer, you have probably heard about events. If you come from wordpress like me, you would definitely relate this to their hooks API and when Opencart Events first arrived in opencart they were very similar in terms of the naming approach. This changed in the version when the Opencart team changed the way events where triggered and this we believe will revolutionize Opencart forever.

What are events?

First of all, what are ¨events〃 in the opencart core understanding? Events are methods that are called when an action takes place. In other words, you can define specifically the moment when you want your custom function to run in the opencart store.

You can find more information here and here

10 Secrets that will make you a master of Opencart Events?

Why not use VQMOD/OCMOD?

Before ¨events〃 for a long time we have been using VQMOD, a modification system that uses an XML file to add changes to files of opencart. It would run in the beginning, creating vqmod cache files with the modifications and then the opencart core system would use those new files to make the changes. In other words, you would change the codebase, but the changes would be added on the fly.

The idea was great at that moment and it really boosted opencart since it allowed for the developer to create any kind of modification without altering the actually core files, making installation of modules and the future opencart upgrade easier.

As good as it sounds, it created a whole level of conflicts between custom modules, leading to hours and even days of work to fix. Mostly, due to poorly created modifications.

Still, even with this drawback, VQMOD, and further OCMOD, a native implementation of VQMOD concept directly in Opencart, gives us, developers, a great tool.

So how can Events help me better then VQMOD/OCMOD?

Events are simple functions that execute at a specific moment in your opencart runtime and modify the output  not the codebase. For example, if you want to run a function before the common/header controller is loaded, you can do that. Or if you want to add some html to the output of the common/header view  you can do that as well. There is no file manipulation so you wonˇt need to worry about creating conflicts by altering the code  the code base stays the same.

Sound interesting, but how do I actually use it?

Lets try an example. Say, you have another tpl file for the header and you need the header controller to load my_custom_header.tpl.

VQMOD/OCMOD solution:

Create a modification that would edit the $this->load->view method in the controller.

  1. <file name="catalog/controller/common/header.php">
  2.   <operation>
  3.     <search position="replace"><![CDATA return $this->load->view('common/header', $data);]]></search>
  4.     <add><![CDATA return $this->load->view('common/my_custom_header', $data);]]></add>
  5.   </operation>
  6. </file>

This works perfectly until another extension comes along and needs this line of code to work. Now you have a conflict.

Eventˇs Solution:

With events you will not alter the code, you will change the $route parameter, that is passed into the $this-load->view($route, $data) like so.

Create a file (use descriptive names  saves the time of finding the right event file):


  1. <?php
  2.   class ControllerEventChangeViewCommonHeader extends Controller {
  3.     public function before_view(&$route, &$data, &$output){
  4.       $route = str_replace('common/header', 'common/my_custom_header', $route);
  5.     }
  6.   }

Now add the trigger:

  1. $this->load->model('extension/event');
  2. $this->model_extension_event->addEvent(ˉmy_custom_header', 'catalog/view/common/header/beforeˇ,ˇ event/change_view_common_header/before_viewˇ);

You would need to add the trigger yourself during the installation of your module or use the Event Manager to do it manually

10 Secrets that will make you a master of Opencart Events?

Of course there could be an extension that also wants to change the tpl file and load its second_custom_header.tpl  so there are always a possibility of conflicts, yet with events the chances are dramatically reduced.

You can find more information in the documentation here

10 Tips that will make you events rock!

There are some rules you should know about events and trigger naming before diving into events.

1. The trigger name starts with admin or catalog. Even if you are calling a config file,which is in systemfolder, you will call it either in admin or catalog.Ex: trigger: admin/config/admin/after

2. Actions are defined only in the controllers. So even if you want to trigger them for a model, you still must define them in a controller. Ex: file location will be admin/controller/event/admin_config_modification.php

3. The Catalog View trigger before and after are different. This is not necessarily a bug, yet is not obvious from the start. Ex: before trigger: catalog/view/common/header/before Ex: after trigger: catalog/view/default/template/common/header/after

The reason this happens, is that the controller passes the $route value of ‘common/header’ yet opencart builds up the $route with the theme settings using an event action located in catalog/controller/event/theme.php. This only happens in the

catalog (frontend) and not in the admin since admin does not have a theme option.

4. You can use the wildcard symbol (*) in your trigger. This will save you the time creatingalmost the same triggers for different paths.

5. You will need to set the events upfront in your admin using the event model from your admin/model/extension/event.php. The perfect way of adding is when someone is installing your extension.

6. You can not create events from the catalog, only admin. There is no method in the catalog/model for that. Well, why would you, right?

7. Remember, that the $this-&gt;load- &gt;config does not return anything, so you can’t actually modify the $output of the config file, yet you can still add modify with $this-&gt;config-&gt;set() method.

8. Same goes for Language files, the only difference is the language $output is returned and you can evaluate it. But you still need $this-&gt;language- &gt;set() method to modify.

9. To avoid theme conflicts, you can alter the html $output of the view with simple html DOM library. You can also move the selectors to the module config and allow edit in the admin panel for the user to set it in case the custom theme differs from the default.

10. Remember that your event action is not he only one in the loop. Try to return the$output that the next action can safely use. This is probably the most important rule of them all.

Leave a Reply