Showing a module on the storefront

A module is a block that can be placed on storefront pages: a banner, a product list, a greeting. The code of the block is the storefront controller of the extension. Where the block appears is decided not in code but in the admin panel, through layouts.

Files

extension/acme_hello/catalog/
├── controller/module/acme_hello.php
├── language/en-gb/module/acme_hello.php
└── view/template/module/acme_hello.twig

The controller

Unlike a page, a module does not send a response — it returns a string with HTML:

// extension/acme_hello/catalog/controller/module/acme_hello.php
namespace Opencart\Catalog\Controller\Extension\AcmeHello\Module;
 
class AcmeHello extends \Opencart\System\Engine\Controller
{
    public function index(): string
    {
        $this->load->language('extension/acme_hello/module/acme_hello');
 
        $data['text'] = $this->config->get('module_acme_hello_text');
 
        return $this->load->view('extension/acme_hello/module/acme_hello', $data);
    }
}

The text is the setting saved on the settings page of the module.

Texts and the template

// extension/acme_hello/catalog/language/en-gb/module/acme_hello.php
$_['heading_title'] = 'Welcome';

{# extension/acme_hello/catalog/view/template/module/acme_hello.twig #}
<div class="card mb-3">
  <div class="card-header">{{ heading_title }}</div>
  <div class="card-body">{{ text }}</div>
</div>

A module template has no header and footer — it is a fragment inserted into a page.

Layouts

A layout is a named set of pages with the same arrangement of blocks: «Home», «Product», «Category», «Account». Each layout has four positions:

Placing the module

1. On the settings page of the module turn the status on and enter the greeting text.
2. Open Design → Layouts and edit the layout «Home».
3. In the position Content Top choose «Acme Hello» in the list, press the add button and save.

Open the home page http://shop.test/ — the card with the heading «Welcome» and your text is above the content.

The page controller calls common/content_top, that controller finds the modules of the current layout and calls the index() method of each.

Which page belongs to which layout

A layout is tied to routes: on the layout edit page there is a list of routes, for example product/product for the layout «Product». To show the module on your own page, create a new layout and enter its route.

Calling a module by hand

A module is an ordinary controller, so a page can call it directly:

$data['hello'] = $this->load->controller('extension/acme_hello/module/acme_hello');

Common mistake

The module is added to a layout, but the page does not show it. The core skips modules whose setting module_acme_hello_status is off. Open the settings of the module, turn the switch on and save.