OpenCart Development Notes

August 25, 2020

Overview

The OpenCart system follows the MVC (Model, View, Controller) pattern. A simple description of how this works is that a View determines the layout and appearance of a Web site, whereas the content itself is generated and inserted into the View by a Controller. A Model contains data objects that represent database entities being processed by the Controller.

With OpenCart, we have a more complicated implementation of the MVC pattern, mainly because a site’s appearance isn’t actually determined by a set of HTML/CSHTML files in the /views directory. Also, the pattern is mirrored in the /admin and /catalog directories.

There are a collection of .twig files in /view/theme/default/template/common. These, as I understand, are template files that define the general sections of the Web site’s interface, such as right column, left column, header and footer. Beyond the general layout, they don’t determine the appearance of an opencart site.

Most users will modify the appearance of an opencart site by adding, removing and configuring modules, through the dashboard. These modules are inserted into the page sections defined by the .twig template files. The views for these modules are found in /view/theme/default/template/extension/module. Styling is determined by stylesheet.css in /view/theme/default/stylesheet. This means, of course, user cannot modify the site by adding arbitrary HTML/JavaScript code, but is limited to what the installed modules allow.

In order to change the site’s content or add functionality, we must develop at least one module to be installed through the opencart dashboard - i.e. insert a controller, view and template file.

Overview

OpenCart is essentially an e-commerce platform that’s typically installed on a LAMP stack - that is, it’s developed in the PHP language, and works in conjunction with the Apache server and MySQL. Anyone should be able to install OpenCart on a typical standard Web hosting plan, and use it as a platform for an online store. The dashboard is very easy to navigate, and managing an online store should be straightforward.

In my experience, however, actually getting an OpenCart store running required some expertise and eperience with the MVC Web application development, plus some time spent studying the files that make up the platform.

This page is intended to be a guide for those without the expertise.

Disadvantages

You definitely need the support of developers versed in PHP and LAMP.
The platform must be installed on a Web server, under your own hosting plan. This means backups, business continuity and disaster recovery and security are the business’ responsibility.
You will need to develop or install modules in order to make any significant changes to an OpenCart site or add extra features.
A good understanding of the MVC pattern is required.

Here is a case study in what could go wrong:

A dodgy module was installed from a non-oficial source.
The dodgy module screwed up several core files. To this day I still don’t fully know what was overwritten.
One thing I needed to do was repair a broken reference to a system file in the vqmod cache.
Next I needed to repair the model.
Thirdly, I needed to copy a specific file from a backup to the current installation.

Moral of the story is that mistakes will happen, and you’ll need access to the expertise to fix things.

Backup and Disaster Recovery

Personally I make a backup of the home directory in the cPanel, the option for which is found under Partial Backups.

Also, you’ll want to make backups through the dashboard, under the System - Maintenance - Backup / Restore tab. Here I’ll backup everything listed - these are the database tables for the OpenCart store.

Troubleshooting

See the error log in /home/[user]/logs. This will indicate the cause of the error.
Sometimes the log entries indicate a PHP error. Fixing this shouldn’t require more than a very minor change to the file and line of code indicated in the relevant log entry.
Another useful diagnostic resource is the Developer feature in the Web browser. This will reveal the server response codes and which files might have failed to load.

Status codes are: 200 - Content served successfully. 3xx - Usually a routing/redirect problem. 4xx - Missing file(s), or files could not be found, or incorrect file paths. 5xx - Typically indicates a server configuration issue.

Interface Changes

The first concept to grasp is that of .twig files and modules, as, together, they determine what appears in the user interface. The .twig files determine the general layout of the page.

Any additional JavaScript functions and AJAX calls should be placed in the common.js file.

The theme cache must be reloaded. In the Dashboard tab, click the blue cog button at the top-right. In the Developer Settings modal, click the Refresh button for the theme.

Repurposing a Module

Deals with the modification and installation of a duplicated module. This is the best way to get started with OpenCart module development.

This is specific to version 3.0.2 of OpenCart, and assumes you have access to the server’s filesystem (e.g. through cPanel).

What I am going to do here is copy the code for an HTML editor module. Since there is one module installed that enables the insertion of arbitrary HTML, and cannot be repurposed through the dashboard.

Essentially all I’m going to do here is copy all the files for the HTML content module, do some renaming and repackage it as an additional module that can be repurposed in the opencart dashboard.

The original module is simply called ‘HTML’. The module duplicate I’ll call ‘GenericHTML’.

1. Copy Existing Module File System

Files needed:

/admin/controller/extension/module/[filename].php
/admin/language/en-gb/extension/module/[filename].php
/admin/view/template/extension/module/[filename].twig
/catalog/controller/extension/module/[filename].php
/catalog/view/theme/default/template/extension/module/[filename].twig

You want to copy the files into the same file structure within the clone directory.

2. Basics of Operation

As this is a separate module, we’ll need to add a controller for it. As it doesn’t do anything much, beyond display the HTML defined by the user, we only need the generic PHP functions.

It is probably a good idea to explain something about what these files do. As OpenCart is based on the MVC code pattern. A client’s browser sends a request to the server, and the request is routed to a controller within /admin/controller or /catalog/controller, depending on whether the application is being accessed through the home page or dashboard.

This controller would look something like:

    return $this->load->view('extension/module/myview', $data);
}

}

The function executes whatever code, and returns a ‘Web page’ defined by /extension/module/myview along with whatever content is generated by the controller.

The controller and view in /admin determine what the site admin sees, and the controller-view in /catalog determine what’s displayed to others visiting the site.

3. Modifying the Cloned Files

The important thing to change in /admin/controller/extension/module/[filename].php and /catalog/controller/extension/module/[filename].php are the names for the controller classes,