Events System
(Still working on the documentation)
Since the Opencart release, v2.2+, a new Engine has been added to the core. An event is a built-in mechanism launch automated tasks either from the admin or on the store-front end of the platform.
An event completes the tasks that:
- a controller
- a model
- a theme override
- a language
- a config
needs to achieve in the back-end of the store.
A store owner may want to provide promotional features to customers or to receive email notifications that the core does not specifically provide out-of-the-box.
One of the service request that store owners may post frequently about are sending back-end notifications while customers fills the information during checkout. An event can fulfill the task by capturing the expected results during checkout for, almost, unlimited features.
One scenario would be about adding a product to the store from the admin - > catalog - > products page. As we all should know, by now, core files should never be edited. However, event files can either be captured before or after an action occurred which means core files do not need to be edited in the store anymore.
The system/engine/event.php file is the Engine core file where all events are being called once an event being initiated in the oc_event database table with an active status. This engine file can do the following:
- Register a trigger and action
- Trigger an event and arguments
- Unregister a trigger and a route
- Clear a trigger
The admin/controller/startup/event.php and catalog/controller/startup/event.php files are both locations where the triggers, actions and sort orders are being automatically registered by the Engine upon startup. The admin/controller/event and catalog/controller/event folders are the core events being initiated automatically by default once Opencart has been installed successfully.
A code is a technical identity tag or title that identifies the purpose of its use. An example similar to the admin - > catalog - > products page with the meta titles but in more technical terms.
A trigger is a defined route from a sourced location where, either; a controller, a model, a language or theme override might be queried from. For instance, one scenario where a store owner might need to specify a trigger regarding newsletters that needs to be sent to particular groups of customers. A model is being queried but, either, ** before ** or ** after ** the load of that model being completed, a store owner might want to add one or more aspects to notify their customers while the sourced trigger is being executed from the local database or from a reliable service provider.
An action is defined route to its destination from where the sourced route needs to send the event notification to. For instance, by creating an extension module in admin/controller/extension/module or in the catalog/controller/extension/module folders, a method name needs to be assigned with the route location.
For e.g:
- admin/controller/extension/module/your_module.php would contain the method name: notify()
The defined action being captured from the Engine would then initiate that particular action being received by the trigger to complete the request electronically.
The status field is what defines the activeness of a particular event.
The sort order field is what defines the priority of an event before being initiated. It has no relations with a before or an after event. It simply describes the ordering task based on a set-list standpoint.
When initiating a before event, there are two parameters that needs to be entered. Following the example with the notify() method, the two parameters would be:
- $route: Originates from the query route (route=x). It can also be passed as a referenced variable.
- $args: The scalar array using index numbers originating from the sourced method. For instance, when adding an order record to the history: $this->model_checkout_order->addOrderHistory($order_id, $order_status_id). It can also be passed as a referenced variable.
The $args scalar array would then contain: $args[0] (order_id), $args[1] (order_status_id) . More information can be found in the catalog;/controller/mail/order.php file where the email order notifications between the store owner and the customer is located.
When initiating an after event, there are three parameters that needs to be entered. Following the example with the notify() method, the third parameter would be:
- $output: The output of the unique index from the scalar array. For instance, an event override has been created and an output result can be outputted from the theme file source codes and viewable on the browser. It can also be passed as a referenced variable.
In system/config/catalog.php file, at the bottom of the file, a debug key and value in an array are being commented by default as they should only be active for debug purposes. Once the debug activated, the codes can be tested in the catalog/controller/event/debug.php file. It is highly recommended to revert the change in the system/config/catalog.php file once the test is complete. If the store is running live, it is also recommended to set the store under maintenance mode from the admin - > systems - > settings - > edit settings - > server tab - > maintenance mode: On before completing the tests.
The events can be monitored in the admin - > extensions - > events page.
In the admin-end and catalog-end side, events are running independently. Which means, events being created on the admin-end does not reflect an event created on the catalog-end side as well. They both run separately. Both sides of the events can run on their separate sides without interfering on each other.
Followed is an example code that can be initiated as a before event, from a controller in order to call a model, in this case, about handling products automatically, with referenced variables in the method's parameters, in the admin/controller/extension/module/product_notification.php file (needs to be created):
<?php
class ControllerExtensionModuleProductNotification extends Controller {
// admin/model/catalog/product/addProduct/before
public function addProduct(&$route, &$args) {
$this->load->model('catalog/product');
// While the product being added, we add the next statement below by loading the catalog product model
// by using the route (optional) and the scalar array of $args.
}
}
The same method could be used with an after event by simply replacing:
// admin/model/catalog/product/addProduct/before
public function addProduct(&$route, &$args) {
with:
// admin/model/catalog/product/addProduct/after
public function addProduct(&$route, &$args, &$output) {
NOTE
Since the release of Opencart, v2.2 and above, the events system has been updated so that controllers, models, views, language and config can have an event attached to them. In previous versions only model data could be overridden.
When your module is installed you will want to register all events that your script needs.
Load the model
$this->load->model('setting/event');
Register your Event
$this->model_setting_event->addEvent($code, string $description, $trigger, $action);
- To initiate the before event.
$this->model_setting_event->addEvent('product_notification', 'admin/model/catalog/product/addProduct/before', 'extension/module/product_notification/addProduct');
- To initiate an after event, simply change it to:
$this->model_setting_event->addEvent('product_notification', 'admin/model/catalog/product/addProduct/after', 'extension/module/product_notification/addProduct');
Code should be a unique code that is unique only to your extensions. you could use your OpenCart username then the name of the extension.
Example
username_theme
The code is also used to delete the event you have added should the user decide to uninstall your extension.
Trigger is the call being made to the controller, model, view, language or config file being called or loaded.
The trigger is made up of many parts:
application / type / folder / file / method / before or after
Needs to be set to catalog or admin.
- controller
- model
- view
- language
- config
Folder is optional depending if the path of the file being loaded is within a sub-folder or not.
File name being called.
Method is only used with controllers and models.
The event trigger when a controller or model method is called. Controllers dont always require method but models do.
Sets weather the event is triggered before or after the file is loaded or method called.
Action is an object that has in its constructor the route to the action controller being called. Within the controller you can manipulate the route, data, arguments and return of data of the controller, model, view being called.
Example
folder/file/method
If no method is set then it will call index.
When your module is uninstalled you will need to ensure that you remove all of the events that you registered.
Remove your Event
$this->model_setting_event->deleteEventByCode('my_theme');
To use and event you must:
- Set a trigger.
- Ensure that the action (controller) being called by the event trigger exists.
Only controllers can be called by the action. This means if you attach an action to be triggered when a model event is called it can only call a controller and not another model.
Depending if a class being loaded or called controller, model, view, language or config file is being called action being called arguments have to be supplied to the action.
Examples:
| Tables | Type | Description |
|---|---|---|
| $route | string | gets the library object by key |
| $data | array | The data being being fed into the controller |
If you return the data it will stop any other event actions that are set to be called.
The route that is being called.
The data being being fed into the controller.
If you return the data it will stop any other actions that are
Input Parameters
View the view being loaded
data the data
The route that is being called.
In the example we have added an event that is triggered when a product is added. The file called would be admin/controller/module/demo.php and the method inside the demo controller class would be eventSendAdminAlert() and if you wanted to add an event to the front end (catalog) use catalog/controller/module/demo.php
OpenCart homepage | OpenCart forums | OpenCart blog | How to documents | Newsletter
OpenCart is created under the GNU General Public License version 3 (GPLv3)