Module Extensions

Module extensions control what content is displayed in your store and where it appears. Unlike payment or shipping extensions that handle specific transactions, modules are responsible for displaying products, categories, banners, and other content blocks throughout your site.

What Are Modules?

Modules are display components that can be positioned in various layouts throughout your store. They typically:

Display dynamic content (products, categories, banners)
Can be added to multiple layouts
Support multiple instances with different settings
Are managed through Extensions → Extensions → Modules

Modules can be assigned to specific layouts and positions using Design → Layouts in the admin panel.

Built-in Modules

OpenCart includes these default modules in upload/extension/opencart/:

Account

Displays customer account links in a sidebar

Banner

Image carousel/slider for promotional banners

Bestseller

Shows your best-selling products

Featured

Showcase hand-picked featured products

Filter

Product filtering by attributes

HTML Content

Display custom HTML/text content

Information

Links to information pages

Latest

Recently added products

Special

Products currently on special offer

Store

Display store locations (multi-store)

Blog/Topic

Blog post listings and topics

Module Architecture

Admin Controller

Location: admin/controller/extension/[vendor]/module/[name].php

namespace Opencart\Admin\Controller\Extension\Opencart\Module;

class Banner extends \Opencart\System\Engine\Controller {
    public function index(): void {
        // Load language
        $this->load->language('extension/opencart/module/banner');
        
        // Get module settings if editing existing instance
        if (isset($this->request->get['module_id'])) {
            $this->load->model('setting/module');
            $module_info = $this->model_setting_module->getModule(
                $this->request->get['module_id']
            );
        }
        
        // Prepare data for view
        $data['name'] = $module_info['name'] ?? '';
        $data['status'] = $module_info['status'] ?? '';
        
        // Display configuration form
        $this->response->setOutput(
            $this->load->view('extension/opencart/module/banner', $data)
        );
    }
    
    public function save(): void {
        // Validate and save settings
        $this->load->model('setting/module');
        
        if (!$this->request->post['module_id']) {
            // Add new module instance
            $json['module_id'] = $this->model_setting_module->addModule(
                'opencart.banner', 
                $this->request->post
            );
        } else {
            // Update existing instance
            $this->model_setting_module->editModule(
                $this->request->post['module_id'], 
                $this->request->post
            );
        }
    }
}

Catalog Controller

Location: catalog/controller/extension/[vendor]/module/[name].php

namespace Opencart\Catalog\Controller\Extension\Opencart\Module;

class Banner extends \Opencart\System\Engine\Controller {
    public function index(array $setting): string {
        // Load data based on settings
        $this->load->model('design/banner');
        $this->load->model('tool/image');
        
        $data['banners'] = [];
        
        // Get banner items
        $results = $this->model_design_banner->getBanner(
            $setting['banner_id']
        );
        
        foreach ($results as $result) {
            $data['banners'][] = [
                'title' => $result['title'],
                'link'  => $result['link'],
                'image' => $result['image']
            ];
        }
        
        // Pass settings to view
        $data['effect'] = $setting['effect'];
        $data['interval'] = $setting['interval'];
        $data['width'] = $setting['width'];
        $data['height'] = $setting['height'];
        
        // Return rendered view
        return $this->load->view('extension/opencart/module/banner', $data);
    }
}

Catalog module controllers must accept a $setting array parameter and return a string (rendered HTML).

Multiple Module Instances

Unlike other extension types, modules can have multiple instances with different configurations:

Creating Instances

Go to Extensions → Extensions → Modules
Find your module and click Edit
Some modules have an Add button to create new instances
Configure each instance with unique settings

// Banner Module #1: Homepage Hero
[
    'name' => 'Homepage Hero Banner',
    'banner_id' => 7,
    'width' => 1200,
    'height' => 400,
    'status' => 1
]

// Banner Module #2: Sidebar Promo  
[
    'name' => 'Sidebar Promotional',
    'banner_id' => 8,
    'width' => 300,
    'height' => 250,
    'status' => 1
]

Module Instance Storage

Module instances are stored in the module table:

module_id | name                  | code            | setting
----------|-----------------------|-----------------|----------
42        | Homepage Hero Banner  | opencart.banner | {...}
43        | Sidebar Promotional   | opencart.banner | {...}

Common Module Features

Location: admin/controller/extension/opencart/module/banner.php:1 Configuration Options:

Banner: Select from pre-configured banners
Effect: Slide, fade, or other transition effects
Items: Number of items to display at once
Controls: Show previous/next buttons
Indicators: Show dot navigation
Interval: Auto-advance timing (milliseconds)
Width/Height: Image dimensions

Use Cases:

Homepage hero sliders
Promotional banners
Category page headers
Sidebar advertisements

Product Display Modules

Three modules display products with similar functionality:

HTML Content Module

Location: admin/controller/extension/opencart/module/html.php:1 Purpose: Display custom HTML/text content blocks Features:

Multi-language support
Full HTML editor
Can contain text, images, links, or custom code
Multiple instances for different content blocks

Use Cases:

Custom promotional text
Store policies
Social media links
Custom widgets

Category Module

Location: admin/controller/extension/opencart/module/category.php:1 Purpose: Display category navigation tree Configuration:

Status enable/disable
Typically displayed in sidebar
Shows category hierarchy
Highlights current category

Assigning Modules to Layouts

After configuring a module, assign it to layouts:

Go to Design → Layouts
Select a layout (e.g., “Homepage”, “Product”, “Category”)
Click Edit
Add module to desired position:
- Content Top
- Content Bottom
- Column Left
- Column Right

Modules must be installed and configured before they can be assigned to layouts.

Developing Custom Modules

Basic Module Structure

// admin/controller/extension/myvendor/module/custom.php
namespace Opencart\Admin\Controller\Extension\Myvendor\Module;

class Custom extends \Opencart\System\Engine\Controller {
    public function index(): void {
        $this->load->language('extension/myvendor/module/custom');
        
        // Build breadcrumbs
        $data['breadcrumbs'] = [];
        $data['breadcrumbs'][] = [
            'text' => $this->language->get('text_home'),
            'href' => $this->url->link('common/dashboard')
        ];
        
        // Form action URLs
        $data['save'] = $this->url->link(
            'extension/myvendor/module/custom.save'
        );
        
        // Load existing settings
        if (isset($this->request->get['module_id'])) {
            $this->load->model('setting/module');
            $module_info = $this->model_setting_module->getModule(
                $this->request->get['module_id']
            );
        }
        
        // Prepare form data
        $data['name'] = $module_info['name'] ?? '';
        $data['status'] = $module_info['status'] ?? 0;
        
        // Render view
        $data['header'] = $this->load->controller('common/header');
        $data['column_left'] = $this->load->controller('common/column_left');
        $data['footer'] = $this->load->controller('common/footer');
        
        $this->response->setOutput(
            $this->load->view('extension/myvendor/module/custom', $data)
        );
    }
    
    public function save(): void {
        $this->load->language('extension/myvendor/module/custom');
        
        $json = [];
        
        // Validate permissions
        if (!$this->user->hasPermission('modify', 'extension/myvendor/module/custom')) {
            $json['error']['warning'] = $this->language->get('error_permission');
        }
        
        // Validate required fields
        if (!$this->request->post['name']) {
            $json['error']['name'] = $this->language->get('error_name');
        }
        
        if (!$json) {
            $this->load->model('setting/module');
            
            if (!$this->request->post['module_id']) {
                $json['module_id'] = $this->model_setting_module->addModule(
                    'myvendor.custom',
                    $this->request->post
                );
            } else {
                $this->model_setting_module->editModule(
                    $this->request->post['module_id'],
                    $this->request->post
                );
            }
            
            $json['success'] = $this->language->get('text_success');
        }
        
        $this->response->addHeader('Content-Type: application/json');
        $this->response->setOutput(json_encode($json));
    }
    
    // Optional: Allow creating new instances
    public function add(): void {
        $this->load->model('setting/module');
        $this->model_setting_module->addModule(
            'myvendor.custom',
            ['name' => 'New Custom Module']
        );
    }
    
    // Optional: Handle deletion
    public function delete(): void {
        $this->load->model('setting/module');
        $module_id = $this->request->get['module_id'] ?? 0;
        $this->model_setting_module->deleteModule($module_id);
    }
}

Catalog Display Controller

// catalog/controller/extension/myvendor/module/custom.php
namespace Opencart\Catalog\Controller\Extension\Myvendor\Module;

class Custom extends \Opencart\System\Engine\Controller {
    public function index(array $setting): string {
        // Check if module is enabled
        if (!$setting['status']) {
            return '';
        }
        
        // Load language
        $this->load->language('extension/myvendor/module/custom');
        
        // Load models if needed
        $this->load->model('catalog/product');
        
        // Prepare data from settings
        $data['heading_title'] = $this->language->get('heading_title');
        $data['text_custom'] = $setting['custom_text'] ?? '';
        
        // Fetch and prepare content
        $data['products'] = [];
        // ... your logic here ...
        
        // Return rendered HTML
        return $this->load->view('extension/myvendor/module/custom', $data);
    }
}

Module Best Practices

Cache-Friendly

Design modules to work with OpenCart’s caching system for better performance

Responsive Design

Ensure module views work on all screen sizes

Language Support

Use language files for all user-facing text

Settings Validation

Always validate user input in the save method

Troubleshooting

Module Not Displaying

Check installation: Is the module installed?
Check status: Is the module enabled in settings?
Check layout: Is the module assigned to the current layout?
Check position: Is the module in a visible position?
Check cache: Clear the cache (Dashboard → Developer Settings → Refresh)

Module Not Saving Settings

Check permissions: Does the user have modify permission?
Check validation: Are all required fields filled?
Check browser console: Look for JavaScript errors
Check error log: Review system/storage/logs/error.log

Next Steps

Payment Extensions - Payment gateway integration
Shipping Extensions - Shipping calculators
Theme Extensions - Visual customization
Extensions Overview - Extension system basics

Get Started

Store Management

Design & Layout

Extensions

Configuration

Marketing

​What Are Modules?

​Built-in Modules

Account

Banner

Bestseller

Category

Featured

Filter

HTML Content

Information

Latest

Special

Store

Blog/Topic

​Module Architecture

​Admin Controller

​Catalog Controller

​Multiple Module Instances

​Creating Instances

​Example: Multiple Banner Modules

​Module Instance Storage

​Common Module Features

​Banner Module

​Product Display Modules

​HTML Content Module

​Category Module

​Assigning Modules to Layouts

​Developing Custom Modules

​Basic Module Structure

​Catalog Display Controller

​Module Best Practices

Cache-Friendly

Responsive Design

Language Support

Settings Validation

​Troubleshooting

​Module Not Displaying

​Module Not Saving Settings

​Next Steps

Build docs developers (and LLMs) love

What Are Modules?

Built-in Modules

Module Architecture

Admin Controller

Catalog Controller

Multiple Module Instances

Creating Instances

Example: Multiple Banner Modules

Module Instance Storage

Common Module Features

Banner Module

Product Display Modules

HTML Content Module

Category Module

Assigning Modules to Layouts

Developing Custom Modules

Basic Module Structure

Catalog Display Controller

Module Best Practices

Troubleshooting

Module Not Displaying

Module Not Saving Settings

Next Steps