Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 27 ยท Themes and APIs

Themes and Frontend Customisation

Customise the OpenCart storefront safely: theme extensions, template overrides, the theme table, event-based view changes, assets, caches and language overrides.

Almost every OpenCart store ends up with a customised storefront: a different header, a new block on the product page, other colours, other wording. The question is how to do it so that the next OpenCart update does not erase your work, and so that other extensions can still do their own changes. OpenCart gives you several layers for this, from a tiny stylesheet override to a complete theme extension, and choosing the lightest layer that works is the main skill of a theme developer.

In this lesson you will learn what a theme is in OpenCart 4, how a template file is found, how the theme table and events change views without editing core files, how to ship CSS and JavaScript, and what to watch for with caches and responsive layouts. The real OpenCart code is read-only here, because OpenCart cannot run on this site. The runnable examples are plain PHP stand-ins that copy the lookup logic. Twig syntax itself is covered in Twig Views and Language Files, and events in Events.

What a theme is

A theme is an extension of type theme. The store selects one in System > Settings > Edit store > Option. The default theme that comes with OpenCart contains every storefront template. Your own theme does not have to contain everything. OpenCart has no formal "child theme" feature like WordPress, but it works in a similar way: templates your theme does not supply fall back to the default theme's files.

Because this is only a convention that varies in detail between versions, treat these as the layers you can use, from lightest to heaviest:

Layer What you change Survives core updates?
Custom CSS in the theme editor or an extension stylesheet Look and feel Yes
Language overrides Wording Yes
Theme editor (templates saved in the theme table) One template for one store Yes, but it can go stale
Event on a view route Data or HTML of one page Yes
A theme extension with its own templates Many templates Yes, with merge work
OCMOD patch (OCMOD Modifications) Anything Fragile

Prefer a layer near the top. A theme that copies 60 templates will diverge from the default and make every upgrade a merge job.

How a template is found

When a controller ends with return $this->load->view('product/product', $data), the string product/product is a view route, not a file name. OpenCart turns it into catalog/view/template/product/product.twig for the active theme. The lookup works in this order (simplified, read-only):

  1. If the theme table has a row for this store, theme and route, its saved source code is used instead of any file. These rows are what the Design > Theme Editor produces.
  2. Otherwise OpenCart looks for the file belonging to the active theme.
  3. If there is none, it uses the default theme's file.

For templates of an extension (for example a module), the route is prefixed with the extension path, such as extension/acme/module/badge, and the file lives inside your extension folder under catalog/view/template/module/. Check the file lookup of your version in system/library/template/ and the events in catalog/controller/event/, because the details moved between 4.0.x and 4.1.x.

flowchart TD
    R["load->view('product/product')"] --> E["catalog/view/*/before event"]
    E --> T{"Row in theme table for store + route?"}
    T -->|"yes"| S["Use saved source from the database"]
    T -->|"no"| A{"File in the active theme?"}
    A -->|"yes"| F["Use theme file"]
    A -->|"no"| D["Use default theme file"]
    S --> O["Render Twig with data"]
    F --> O
    D --> O
    O --> AF["catalog/view/*/after event can edit the HTML"]

A view route is resolved through the theme table, then the active theme, then the default theme, with events before and after.

The database layer has a trap. A template saved through the theme editor is a copy. When you update OpenCart, the file changes but the saved copy does not, so the store keeps showing the old markup and may lose new features. The editor offers a reset for a reason; when you debug "my update did not change the page", check the theme table first.

A template resolver stand-in

The stand-in below mimics the three-step lookup with an in-memory "file system" and "database", so you can see which source wins. It is not OpenCart's code, only the logic described above.

PHP Theme to default fallback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The header comes from the Acme theme, the product page falls back to the default theme, the footer is taken from the database row until it is removed, and a route that exists nowhere is an error. This is the picture to keep in mind when a change "does nothing": something earlier in the chain is winning.

Changing a page without copying its template

Often you only want a small change on one page. Copying the whole template for that is the heaviest option. Two lighter ones exist.

Add data with a before event. Events on catalog/view/product/product/before receive the route, the data array and the template code by reference. Your handler can add a variable, for example a delivery estimate. The template still needs a place to print it, which can be done by editing it once in a theme, or by using the second option.

PHP
// read-only: an event handler registered for catalog/view/product/product/after
public function addBadge(string &$route, array &$data, mixed &$output): void {
    $badge = '<span class="acme-badge">New</span>';
    $output = str_replace('<h1>', $badge . '<h1>', $output);
}

Edit the HTML with an after event. The handler receives the finished HTML as $output and can insert markup with simple string work, as above. This avoids copying the template, but it depends on a marker in the HTML (here <h1>), so keep the search string short and stable, and do nothing when the marker is missing. If your event runs together with someone else's, order is decided by the event's sort_order.

The following stand-in applies the same idea: several handlers run on the rendered HTML in order, and a handler whose marker is not found leaves the page untouched.

PHP after-events edit the finished HTML

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Assets: CSS, JavaScript and cache busting

Add stylesheets and scripts from a controller with the document object, for example $this->document->addStyle('extension/acme/catalog/view/stylesheet/badge.css') and $this->document->addScript(...). The document collects them and the header template prints them. Some practical rules:

  • Put extension assets inside your extension folder so they are installed and removed with it.
  • Keep CSS small and namespaced (.acme-badge, not .badge), so it cannot clash with the store's theme or another extension.
  • Browsers keep static files in their cache. After a change, visitors may still see the old file. Add a version to the URL, such as badge.css?v=1.2.0, and increase it per release.
  • OpenCart also caches compiled Twig templates (under the storage/cache folder). While developing, switch the theme cache off in the developer settings (the gear button on the admin dashboard), or clear it after each change. Turn it back on for production.

A small helper that adds a version to asset URLs and removes duplicates is easy to write and test without the framework:

PHP Collecting assets with versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The badge stylesheet is registered twice, because the same module may appear in two layout positions, but is printed once.

Responsive pitfalls

OpenCart 4's default theme is built on Bootstrap 5, so your markup should use its grid classes and breakpoints and not fixed pixel widths. Typical mistakes in extension templates: fixed-width tables and iframes that overflow on phones, hover-only interactions that never trigger on touch screens, images without max-width: 100%, and text that is cut off in languages with longer words. Test each template at about 360 px wide and in a right-to-left language if your customers need one.

Language overrides

Wording in the storefront comes from language files with text_ keys. To change the wording of an existing page without editing core files, use Design > Language Editor, which stores a translation row for a route and key, or ship your own language file in the extension. Keep your own keys in your own files, so they cannot be replaced by a core update. Never hard-code visible text in a template, because the store may be multilingual.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the lightest way to change the colours of a storefront without touching templates?

    Styles survive updates and do not copy any template, which is why they sit at the top of the list of customisation layers.
  2. 2. A store owner says an OpenCart update did not change the footer. What should you check first?

    A template saved through the theme editor is a copy that wins over the file, so updates to the file do not show up.
  3. 3. What does an after event on a view route receive that a before event does not?

    After the view is rendered, the handler can edit the HTML. Before it, the handler can change the data or the template code.
  4. 4. Why should an extension keep its CSS class names prefixed, such as .acme-badge?

    Stylesheets are global on the page, so generic class names can accidentally restyle unrelated elements.

Summary

  • A theme is an extension of type theme; OpenCart has no formal child themes, but missing templates fall back to the default theme.
  • A view route is resolved through the theme table, then the active theme, then the default theme; stale theme-editor copies are a common cause of "my change does nothing".
  • Prefer light layers: CSS, language overrides, events on view routes, and only then copied templates.
  • Add assets through the document object, namespace your CSS, version asset URLs and mind the Twig cache while developing.
  • Build with Bootstrap's responsive grid, test narrow screens, and keep text in language files.

Next: Catalog and Admin APIs