Developing Modules
Writing OpenCart modules can be a very good way to learn how the fundamentals of OpenCart actually work. Just as the rest of OpenCart, modules follow the MVCL design pattern. This documentation guide will describe how you use each of the MVC-L components to create the admin and frontend parts of your module. The easiest way to create a module is to download the DIY Module Builder skeleton from HostJars. This module contains the directory structure, files, and instructions on how to understand and build your own modules. This page is a more theoretical guide.
Basic directory structure
The basic file structure for your module will be divided into two sections, the admin and the catalog folders. The contents of each folder will follow the MVC-L framework respectively, with the difference that the admin will deal solely with backend functionality, and the catalog with frontend functionality. Users of your module will interact and configure its settings in the administration side of the store. Therefore, the files in the admin folder will handle any changes to its settings, the way the module is displayed in the administration, install/uninstalling the module, etc. Likewise, the way the module is displayed and how it works in the front end of the store will be handled by the files in the catalog folder.
The image above displays a skeleton of the directory structure that your module should follow. A good way to get started with your module is to duplicate the folder structure and create the files above. What will go in those files is determined by what your module is trying to accomplish, but the basic functionality is detailed in the sections below.
Admin module functionality
When a store owner uses your module, they will want to edit the module's configuration options in the admin in order to decide which layouts to display the module on, whether it is enabled or disabled, and any module specific options. As the module developer, you will need to create the admin page where the module may be edited and the configuration options added or adjusted.
All admin files are located in the admin/ folder. You will find four folders within the admin/ folder:
- controller
- view
- language
- model
All modules will require at least a single file in each of the view and controller folders. Most will require a file in each of the model and language folders. Usually the files have the same name, except the view file has a different suffix (.twig). We will go through these files one by one.
Controller
The first file you make will be the controller for your module's admin interface page. OpenCart identifies existing modules automatically, simply by reading the admin/controller/module folder of your store. Any modules existing in this folder will automatically be shown on the Modules page, and on the User Permissions, page. You may call your controller file my_module.php.
The controller file is the place where you can load the language files to convert text into variables to be utilized in the template file. In the diagram above, you can see the $_['text'] variable being handled by the controller, then sent as $text to the view. You will also utilize multiple model files and their class functions here, including your module's model file if it has one. For more information on loading files see Loading files in the controller.
You may also have a function defined as public function install(). This function will be triggered when the install link is clicked on the Extensions > Modules page. Similarly, a function defined as public function uninstall() will be triggered when the uninstall link is clicked. You can use these functions to create and remove any structures (such as database tables or config settings) required by your module. It is good practice to create an uninstall function to clean up any changes your module has made. To see the specific code for an install(), uninstall(), visit Install/Uninstall a module.
Accessed via URL
The controller is the only file in the MVC-L framework to be accessed by URL in OpenCart. In the administration, the URL will look like /admin/index.php?route=module/my_module&token. The admin adds a token to the URL, whereas the link in the catalog will not have it. As a result, the controller file will have a function defined as public function index(). This is a publicly accessible 'page' that is loaded by the URL, which will be shown when the Edit button is clicked, and where the view form will submit to. The submitted data will be processed in this function and saved to the `settings` database table through the controller's config object.
View
The second required file for your module's admin interface is the view file. This will be created in the admin/view/template/module folder, and will have the suffix .twig. This is standard for OpenCart view files. In this file you will create a form for the user to fill out and submit. It will be submitted to the module controller's index function. The easiest way to create your view file is to copy and paste an existing, similar view file, and edit the form to contain the correct fields for your module's configuration options. You may call your view file my_module.twig.
In the view, you will be able to access the text from the language that the controller file stored as a PHP variable. See Loading Files in the Controller for the code on how to do so.
Model
It is uncommon for modules to require a model file on the admin side. However, if your module relies on its own database table, or a custom query to create data of a particular format, then you may find yourself writing a model file. An example of this may be if you are writing a visitor counter module, where each visitor is stored in a database table with their IP address and number of visits. You may then create a model file, with a function to define and create this extra table in the OpenCart database. The model file will live in the admin/model/module folder. You may call your model file my_module.php, the same as your controller and language files.
Frontend module functionality
The frontend of your module follows the same pattern as the admin interface just described. What you will include in each of your frontend files will largely depend on what your module is supposed to do. A module can access any model files that already exist in OpenCart, you do not need to write your own database queries if the same query already exists. For example, the catalog/product model contains many useful queries for fetching products. Using these model functions should be preferred over reinventing the wheel.
A key difference in the frontend of your module, is that your view file will be in the catalog/view/theme/(themename)/template/module folder. This is a significantly deeper folder structure to the admin view file because of themes. An OpenCart store may have many different frontend themes available, but only one admin template. (themename)
On the frontend part of your module you will have access to the configuration options saved by your module, through both the controller's config object, and the $settings variable passed to the module controller's index function. You can control aspects of the frontend display on the basis of these settings.