How to Create Joomla 4.x Module

A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page.

It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.

Part 1: File Structure

There are a basic files that are used in the standard pattern of module development:

mod_hello.php: This file is the main entry point for the module. It performs any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.

Helper/HelloHelper.php: This file contains the helper class that is used to retrieve the data to be displayed in the module output.

mod_hello.xml: This file contains information about the module. It defines the files that need to be installed by the Joomla installer and specifies configuration parameters for the module.

tmpl/default.php: This is the module template. This file takes the data collected by mod_hello.php and generate the HTML to be displayed on the page.

language/en-GB/en-GB.mod_hello.ini and language/en-GB/en-GB.mod_hello.sys.ini: This are the files that provide the text in United Kingdom English.

1. mod_hello.php

The mod_hello.php file performs following tasks:

  1. Import the class ModuleHelper to the current scope. You need it later for displaying the output.
  2. Import the helper class of the module to current scope at the beginning of the file.
  3. Include the template to display the output.

The helper class is imported to current scope at the begin of the file.

use Joomla\CMS\Helper\ModuleHelper;

Next, import the helper class of the module.

use Joomla\Module\Hello\Site\Helper\HelloHelper;

Next, you include the template to display the output.

require ModuleHelper::getLayoutPath('mod_hello', $params->get('layout', 'default'));

Completed mod_hello.php file

<?php
/**
 * @package [PACKAGE_NAME]
 *
 * @author [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright [COPYRIGHT]
 * @license GNU General Public License version 2 or later; see LICENSE.txt
 * @link [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Hello\Site\Helper\HelloHelper;

$test = HelloHelper::getText();

require ModuleHelper::getLayoutPath('mod_hello', $params->get('layout', 'default'));

The first line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.

2. Helper/HelloHelper.php

The helper class should belong to a namespace. It is important, that this line is at the beginning of the file.

namespace Joomla\Module\Hello\Site\Helper;

Then you create a class with methods.

<?php
/**
 * @package Joomla.Site
 * @subpackage mod_hello
 *
 * @copyright Copyright (C) 2005 - 2019 Open Source Matters, Inc. All rights reserved.
 * @license GNU General Public License version 2 or later; see LICENSE.txt
 */

namespace Joomla\Module\Hello\Site\Helper;

// No direct access to this file
defined('_JEXEC') or die;

class HelloHelper
{
 public static function getText()
 {
 return 'FooHelpertest';
 }
}

3. tmpl/default.php

The default.php file is the template which displays the module output.

<?php
/**
 * @package [PACKAGE_NAME]
 *
 * @author [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright [COPYRIGHT]
 * @license GNU General Public License version 2 or later; see LICENSE.txt
 * @link [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

echo '[PROJECT_NAME]' . $test;

The template file has the same scope as the mod_hello.php file. It means that a variable can be defined in the mod_hello.php file and then used in the template file without any extra declarations or function calls.

4. mod_hello.xml

The mod_hello.xml file is the installation file. You have to add a line for the namespace that is set automatically in Joomla. After inserting and installing, the namespace is known by the loader JPATH_LIBRARIES . '/autoload_psr4.php'.

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
 <name>MOD_HELLO</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; see LICENSE.txt</license>
 <version>1.0</version>
 <description>MOD_HELLO_XML_DESCRIPTION</description>
 <namespace>Joomla\Module\Hello</namespace>
 <files>
 <filename module="mod_hello">mod_hello.php</filename>
 <folder>tmpl</folder>
 <folder>Helper</folder>
 <folder>language</folder>
 <filename>mod_hello.xml</filename>
 </files>
</extension>

5. Language files

The files are used to translate text in the frontend and in the backend. 

MOD_HELLO="[PROJECT_NAME]"
MOD_HELLO_XML_DESCRIPTION="Hello Module"

Part 2: 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">

 </fields>
</config>

For example, custom parameter:

<fieldset name="basic">
 <field
 name="domain"
 type="url"
 label="MOD_HELLO_FIELD_URL_LABEL"
 filter="url"
 />
</fieldset>

Joomla default fields

<fieldset name="advanced">

<field
 name="layout"
 type="modulelayout"
 label="JFIELD_ALT_LAYOUT_LABEL"
 class="custom-select"
/>

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

<field
 name="cache"
 type="list"
 label="COM_MODULES_FIELD_CACHING_LABEL"
 default="0"
>
 <option value="1">JGLOBAL_USE_GLOBAL</option>
 <option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
 name="cache_time"
 type="number"
 label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
 default="0"
/>

<field
 name="cachemode"
 type="hidden"
 default="itemid"
>
 <option value="itemid"></option>
</field>

</fieldset> 

Where and How to Get Value of Parameters

You can access the value via the variable $params in the file tmpl/default.php.

$domain = $params->get('domain', 'https://www.joomla.org');

The, you use this value.

<a href="/<?php echo $domain; ?>">
 <?php echo '[PROJECT_NAME]' . $test; ?>
</a>