How To Create Joomla 5.x Module

Modules are lightweight and flexible extensions that are displayed in pages at different module positions. These modules are displayed like boxes arranged around a component in top, sidebar or footer positions. For example, login module or html module.

Directory Structure and Files

The mod_example directory will have three folders and XML manifest file.

• services
  • provider.php
• src
  • Dispatcher
    • Dispatcher.php
  • Helper
    • ExampleHelper.php
• tmpl
  • default.php
• mod_example.xml

How Module Works

The default module Extension class is defined in libraries/src/Extension/Module.php. it provides a mechanism to get to other classes:

• Dispatcher class
• Module's own helper class

Similar to the components, the module Dispatcher class contains the dispatch()  method, which is used to run the module's code.

$module = $app->bootModule($moduleName, $applicationName);
$module->getDispatcher($mod, $app)->dispatch();

The $moduleName is the name of the module (mod_example) and $applicationName is site or administrator. The $mod is a PHP stdClass object representing the module, including data such as the module name, module id, module title, template position, and $app is the Application instance.

The default module Dispatcher class is defined in libraries/src/Dispatcher/ModuleDispatcher.php

1. provider.php

This file registers the service provider with a DI container. It basically registers ModuleDispatcherFactory and HelperFactory.

use Joomla\CMS\Extension\Service\Provider\HelperFactory;
use Joomla\CMS\Extension\Service\Provider\Module;
use Joomla\CMS\Extension\Service\Provider\ModuleDispatcherFactory;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;

return new class () implements ServiceProviderInterface {

    public function register(Container $container)
    {
        $container->registerServiceProvider(new ModuleDispatcherFactory('\\<Brand>\\Module\\Example'));
        $container->registerServiceProvider(new HelperFactory('\\<Brand>\\Module\\Example\\Site\\Helper'));

        $container->registerServiceProvider(new Module());
    }
};

2. ExampleHelper.php

This file contains the module helper class that is used to retrieve the data (from database or other sources) by the Dispatcher to be displayed in the module output.

use Joomla\CMS\Application\SiteApplication;
use Joomla\Registry\Registry;

class ExampleHelper
{
    public function getMsg(Registry $params, SiteApplication $app)
    {
        $message = $params->get('msg', 'Hello World!');
        return $message;
    }
}

3. Dispatcher.php

The Dispatcher class gets data from the Helper class.

use Joomla\CMS\Dispatcher\AbstractModuleDispatcher;
use Joomla\CMS\Helper\HelperFactoryAwareInterface;
use Joomla\CMS\Helper\HelperFactoryAwareTrait;

class Dispatcher extends AbstractModuleDispatcher implements HelperFactoryAwareInterface
{
    use HelperFactoryAwareTrait;

    protected function getLayoutData()
    {
        $data = parent::getLayoutData();

        $data['msg'] = $this->getHelperFactory()->getHelper('ExampleHelper')->getData($data['params'], $this->getApplication());

        return $data;
    }
}

4. default.php

This is the module template or layout file. This file generates the Html to be displayed on the page or module.

echo $msg;

5. mod_example.xml

This file is the installation manifest file. You have to add a line for the namespace that is set automatically in Joomla.

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>mod_example</name>
    <creationDate>[DATE]</creationDate>
    <author>[AUTHOR]</author>
    <authorEmail>[AUTHOR_EMAIL]</authorEmail>
    <authorUrl>[AUTHOR_URL]</authorUrl>
    <copyright>[COPYRIGHT]</copyright>
    <license>GNU General Public License version 2 or later</license>
    <version>1.0</version>
    <description>This is example module for Joomla! 5</description>
    <namespace><Brand>\Module\Example</namespace>   

    <files>
        <folder module="mod_example">services</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
     </files>
</extension>

5. Adding Parameters

Parameters are inserted in the XML file using form fields. First, you set a custom parameters. Then, you insert Joomla default fields, so that you can use cache, moduleclass-suffix and layouts.

The parameters are inserted between:

<config>
    <fields name="params">
    <fieldset name="basic">
        <field name="msg" type="text" label="Message" />  
    </fieldset>

    <fieldset name="advanced">
        <field
         name="layout"
         type="modulelayout"
         label="JFIELD_ALT_LAYOUT_LABEL"
         class="form-select"
         validate="moduleLayout" />

         <field
          name="moduleclass_sfx"
          type="textarea"
          label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
          rows="3"
          validate="CssIdentifier" />

    </fields>
</config>

You can get these parameters in the Helper methods.

$params->get('msg', 'Hellow World');