Creating a Custom Module for Joomla 5

In this guide, we will explore creating a custom module for Joomla 5. We'll use the example of the mod_hello module, which displays a dynamic list of items and leverages modern framework features like namespaces, traits, and dependency injection containers.

With this guide, you can create your own custom module, taking advantage of the powerful modern tools in Joomla 5. Organize your project, use helpers and traits for reusable functionality, and implement dynamic layouts to display data efficiently.

Project Structure

Here is the standard structure of a module in Joomla:

mod_hello/
|
├── language/ # Language files
│   └── en-GB/ # Directory for translations
│       ├── mod_hello.ini # Text displayed by the module
│       └── mod_hello.sys.ini # Metadata (name and description)
|
├── media/ # Static resources
│   ├── css/ # CSS styles for the module
│   ├── images/ # Images used by the module
│   └── js/ # JavaScript scripts
│
├── services/ # Services for dependency injection
│   └── provider.php # Service configuration
│
├── src/ # Core logic files for the module
│   ├── Dispatcher/
│   │   └── Dispatcher.php # Controller to handle requests
│   └── Helper/
│       └── HelloHelper.php # Module helper functions
│
├── tmpl/ # Layouts and templates
│   └── default.php # Default display file
│
├── mod_hello.xml # Module manifest (configuration and structure)

Main Components

Dispatcher.php (src/Dispatcher)

Responsible for processing module requests and preparing data for display.

• Namespace: Joomla\Module\Hello\Site\Dispatcher
• Class: Extends AbstractModuleDispatcher to reuse functionality.
• Method getLayoutData:

$data['list'] = $this->getHelperFactory()
                    ->getHelper('HelloHelper')
                    ->getItems($data['params'], $this->getApplication());

This method retrieves dynamic data for display using the HelloHelper.

provider.php (services/)

A service provider that registers dependencies for the module.

• Implementation: A PHP file with an anonymous class implementing ServiceProviderInterface.
• Registered Services:
  • ModuleDispatcherFactory
  • HelperFactory
  • The module itself.

HelloHelper.php (src/Helper)

A helper that retrieves data from the database.

• Namespace: Joomla\Module\Hello\Site\Helper
• Database: Uses DatabaseAwareTrait for database interactions.
• Method getItems:

$query->select('*')
      ->from('#__content')
      ->order('title ASC')
      ->setLimit((int) $params->get('count', 5));

Returns articles from the #__content table based on parameters.

default.php (tmpl/)

The module's default layout, responsible for displaying data.

Example HTML output:

Manifest XML (mod_hello.xml)

The module manifest describes the project structure and settings.

To download the module generator and example module, click here.