Custom Joomla Module Development

Joomla Custom Module Development

A Joomla module is a small block of content, placed in template positions. Displays data from database, external APIs, calculates and outputs anything. Examples: latest articles, search form, visit statistics, exchange rates.

Module Structure

mod_product_highlights/
├── mod_product_highlights.php   # Entry point
├── mod_product_highlights.xml   # Manifest
├── src/
│   ├── Dispatcher/
│   │   └── Dispatcher.php
│   └── Helper/
│       └── ProductHighlightsHelper.php
├── tmpl/
│   └── default.php              # Template
└── language/
    └── en-GB/
        └── mod_product_highlights.ini

Manifest

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" client="site" version="4.0">
    <name>mod_product_highlights</name>
    <author>Your Company</author>
    <version>1.0.0</version>
    <description>Featured products catalog</description>
    <namespace path="src">MyCompany\Module\ProductHighlights</namespace>

    <files>
        <filename module="mod_product_highlights">mod_product_highlights.php</filename>
        <folder>src</folder>
        <folder>tmpl</folder>
    </files>

    <config>
        <fields name="params">
            <fieldset name="basic">
                <field name="count" type="number" label="Number of Products"
                    default="4" min="1" max="12" />
                <field name="category_id" type="sql"
                    label="Category"
                    query="SELECT id AS value, title AS text FROM #__catalog_categories WHERE published = 1"
                    default="" />
                <field name="show_price" type="radio" label="Show Price" default="1">
                    <option value="1">Yes</option>
                    <option value="0">No</option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

Entry Point

// mod_product_highlights.php
\defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;

// Joomla 4/5 style — via Dispatcher
$app = \Joomla\CMS\Factory::getApplication();
$module = $module ?? null;

echo ModuleHelper::renderModule($module, $params);

Helper

// src/Helper/ProductHighlightsHelper.php
namespace MyCompany\Module\ProductHighlights\Site\Helper;

use Joomla\CMS\Factory;

class ProductHighlightsHelper {
    public static function getProducts(object $params): array {
        $db    = Factory::getDbo();
        $count = (int) $params->get('count', 4);
        $catId = (int) $params->get('category_id', 0);

        $query = $db->getQuery(true)
            ->select(['id', 'title', 'price', 'image', 'alias'])
            ->from($db->quoteName('#__catalog_products'))
            ->where($db->quoteName('published') . ' = 1')
            ->where($db->quoteName('featured') . ' = 1');

        if ($catId) {
            $query->where($db->quoteName('category_id') . ' = ' . $catId);
        }

        $query->order('ordering ASC')->setLimit($count);

        $db->setQuery($query);
        return $db->loadObjectList() ?: [];
    }
}

Dispatcher

// src/Dispatcher/Dispatcher.php
namespace MyCompany\Module\ProductHighlights\Site\Dispatcher;

use Joomla\CMS\Dispatcher\AbstractModuleDispatcher;
use MyCompany\Module\ProductHighlights\Site\Helper\ProductHighlightsHelper;

class Dispatcher extends AbstractModuleDispatcher {
    protected function getLayoutData(): array {
        $data     = parent::getLayoutData();
        $products = ProductHighlightsHelper::getProducts($data['params']);
        $data['products']  = $products;
        $data['showPrice'] = (bool) $data['params']->get('show_price', true);
        return $data;
    }
}

Template

// tmpl/default.php
defined('_JEXEC') or die;
use Joomla\CMS\Router\Route;
?>
<div class="mod-product-highlights">
    <?php foreach ($products as $product) : ?>
    <div class="product-card">
        <?php if ($product->image) : ?>
            <img src="<?php echo $product->image; ?>"
                 alt="<?php echo htmlspecialchars($product->title); ?>"
                 loading="lazy">
        <?php endif; ?>

        <h4 class="product-card__title">
            <a href="<?php echo Route::_('index.php?option=com_catalog&view=product&alias=' . $product->alias); ?>">
                <?php echo htmlspecialchars($product->title); ?>
            </a>
        </h4>

        <?php if ($showPrice && $product->price) : ?>
            <p class="product-card__price"><?php echo number_format($product->price, 0, '.', ' '); ?> ₽</p>
        <?php endif; ?>
    </div>
    <?php endforeach; ?>
</div>

Module Caching

// In Helper — cache result
public static function getProducts(object $params): array {
    $cacheId = md5('product_highlights_' . json_encode($params));

    $cache = Factory::getCache('mod_product_highlights', 'callback');
    $cache->setCaching(true);
    $cache->setLifeTime(15); // minutes

    return $cache->get([static::class, '_fetchProducts'], [$params], $cacheId) ?: [];
}

Timeline

Custom module development with configurable parameters, database query, template and caching — 1–3 days.