Joomla Modules

Official Documentation: https://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module

Modules are the simplest kind of Joomla extension because they are focused on displaying content in the front end. If you just want some PHP code to do something and then echo something then you want a module. When you install a module then you have a module type and then you can make module instances in the admin interface.

Where do they display?

A Module instance can be assigned a position within the template, a custom position which can be called by a content plugin, or no position at all if you want to call the instance directly using a shortcode.

When do they display?

A module is assigned an access level, which the logged in user must satisfy for the module to execute at all. They can be assigned to show on every menu item, some menu items or none.

File Structure

A module requires 2 files only, but if you're writing the module for distribution you should create a helper and set a layout path to allow users to override your layout. If the module is not for distribution then the minimal structure is sufficient.

For a minimal module you need the manifest and an entry file. For a full MVC module you need 4 files eg.

  • mod_helloworld.php - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.
  • mod_helloworld.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.
  • helper.php - This file contains the helper class which is used to do the actual work in retrieving the information to be displayed in the module (usually from the database or some other source).
  • tmpl/default.php - This is the module template. This file will take the data collected by mod_helloworld.php and generate the HTML to be displayed on the page.

XML Manifest for a minimal module

Location: /modules/mod_example/mod_example.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8.0" client="site" method="upgrade">
    <name>Example Minimum</name>
    <author>Your Name</author>
    <version>1.0.0</version>
    <creationDate>2018-01-01</creationDate>
    <description>This message appears in the administration on installation.</description>
    <files>
        <filename module="mod_example">mod_example.php</filename>
    </files>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field name="something" type="text" label="Something" description="" filter="raw" />
            </fieldset>
        </fields>
    </config>
</extension>

PHP Code for a minimal module

Location: /modules/mod_example/mod_example.php

<?php
defined('_JEXEC') or die;

echo "here be some output, but.";

// the entry file has a param object available, here we retrieve the value entered into the module instance
$something = $params->get('something','default value if empty');

XML Manifest for an MVC module

Location: /modules/mod_helloworld/mod_helloworld.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8.0" client="site" method="upgrade">
    <name>Example Full</name>
    <author>Your Name</author>
    <version>1.0.0</version>
    <creationDate>2018-01-01</creationDate>
    <description>This message appears in the administration on installation.</description>
    <files>
        <filename>mod_helloworld.xml</filename>
        <filename module="mod_helloworld">mod_helloworld.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <filename>tmpl/default.php</filename>
        <filename>tmpl/index.html</filename>
    </files>
     <config>
    </config>
</extension>

Entry File for an MVC Module

Location: /modules/mod_helloworld/mod_helloworld.php

defined('_JEXEC') or die;
require_once dirname(__FILE__) . '/helper.php';

$hello = modHelloWorldHelper::getHello($params);
require JModuleHelper::getLayoutPath('mod_helloworld');

Helper file for an MVC Module

Location: /modules/mod_helloworld/helper.php

class ModHelloWorldHelper
{
    public static function getHello($params){
        return 'Hello, World!';
    }
}

Template file for an MVC Module

Location: /modules/mod_helloworld/tmpl/default.php

<?php 
defined('_JEXEC') or die;

echo $hello;

Using AJAX in a module with com_ajax

Official Documentation: https://docs.joomla.org/Using_Joomla_Ajax_Interface

Anatomy of an Ajax Request

Required

  • option=com_ajax

  • [module|plugin]=name

  • format=[json|debug|raw]

Optional

  • method=[custom fragment] defaults to get if omitted.

Overview

All requests begin with ?option=com_ajax, which calls this extension, and must indicate the type of extension to call, and the data format to be returned.

Additional variables and values used by your extension may also be included in the URL.

For example, a request to ?option=com_ajax&module=session would call mod_session with results returned in the default format. In contrast,?option=com_ajax&plugin=session&format=json would trigger the onAjaxSession plugin group with results returned in JSON.

Module Support

Summary

Module support is accomplished by calling a method in the module's helper.php file.

Details

Module requests must include the module variable in the URL, paired with the name of the module (i.e. module=session for mod_session).

This value is also used for:

The name of the directory to check for the helper file, e.g. /modules/mod_session/helper.php The class name to call, e.g. modSessionHelper Optionally, the method variable may be included to override the default method prefix of get.

NOTE: All methods must end in Ajax. For example: method=mySuperAwesomeMethodToTrigger will call mySuperAwesomeMethodToTriggerAjax The Ajax Session Module is an example module that demonstrates this functionality.

Further Reading

Creating a template override