Joomla! Documentation™

Adding a module template

In most cases, we want our module to have the ability to display output using a template. We could theoretically code all of this directly into the module php file but using a separate file increases flexibility and gives us the option to override the module output in a template.

So in order to create a module template we need to do two things

1. Create the template
2. Tell the module to load the template and display it

With your favorite editor, create the following file

tmpl/default.php

<?php

/**
 * @package     Joomla.Tutorials
 * @subpackage  Module
 * @copyright   Copyright (C) 2005 - 2010 Open Source Matters, Inc. All rights reserved.
 * @license     License GNU General Public License version 2 or later; see LICENSE.txt
 */

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

?>

<p>Hello World! I am a module</p>

This is pretty straight forward, all we are really doing is creating a php file that outputs a paragraph. Next thing on our list is to modify the module php file to load this awesome template.

With your favorite editor, edit the following file

mod_helloworld.php

<?php

/**
 * @package     Joomla.Tutorials
 * @subpackage  Module
 * @copyright   Copyright (C) 2005 - 2010 Open Source Matters, Inc. All rights reserved.
 * @license     License GNU General Public License version 2 or later; see LICENSE.txt
 */

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

require JModuleHelper::getLayoutPath('mod_helloworld', $params->get('layout', 'default'));

As you can see, the only thing that is required for this module to use our template is a call to JModuleHelper::getLayoutPath(). The first argument is the name of the module to find the template for (this is naturally our very own mod_helloworld module). The second argument is a bit harder to grasp, but it gives the module manager the option to assign an alternative layout to the module. The layout parameter is a parameter which is available to all module in the module manager.

Lastly we need to modify the XML manifest so our new folder is copied into Joomla! when the module is installed.

mod_helloworld.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="2.5.0" method="upgrade">

        <name>Hello World!</name>
        <!-- The following elements are optional and free of formatting constraints -->
        <creationDate>Once upon a time</creationDate>
        <author>John Doe</author>
        <authorEmail>john.doe@example.org</authorEmail>
        <authorUrl>http://www.example.org</authorUrl>
        <copyright>Copyright Info</copyright>
        <license>License Info</license>
        <!--  The version string is stored in the extension table -->
        <version>0.0.2</version>
        <!-- The description is optional and defaults to the name -->
        <description>Description of the Hello World module ...</description>

        <!-- Note the folder attribute: This attribute describes what to copy
                into the module folder -->
        <files>
                <filename module="mod_helloworld">mod_helloworld.php</filename>
                <filename>mod_helloworld.xml</filename>
                <folder>tmpl</folder>
        </files>

</extension>