Modules, like components, are set up in a particular directory structure.

/modules
  /mod_latest_news
	/tmpl
	  default.php   (the layout)
	helper.php   (a helper file containing data logic)
	mod_latest_news.php   (the main module file)
	mod_latest_news.xml   (the installation XML file)

Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:

/templates
  /beez
	/html
	  /mod_latest_news   (this directory matches the module directory name)
		default.php   (this file matches the layout file name)

The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.

Copying or Creating Layout Files

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/modules/mod_latest_news/tmpl/default.php

to this location, creating the approriate directories in the event they don’t already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.

Module Chrome

Joomla! 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

  • 0 (the default) displayed modules in a vertical table
  • 1 displayed them in a horizontal table
  • -1 displayed the raw module output
  • -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
  • -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

  1. Nobody could remember which number was which, and
  2. You couldn’t expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:

<jdoc:include type="modules" name="left" style="xhtml" />

The built-in styles that are now available are:

  • table (was 0 and is the default)
  • horz (was 1)
  • none (was -1)
  • xhtml (was -2)
  • rounded (was -3)
  • outline (new – used to preview module positions – see screenshot above)

In the source code, these styles are referred to as “chrome”. The default chrome is in the system template of the default Joomla! install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it. Your will lose your changes when you upgrade your Joomla! installation.

To create your own chrome, or module styles, create or edit modules.php under the templates /html/ directory. (This is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template provides some extra chrome as an example. (It provides an example style called “slider”). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

Creating your own chrome is easy. Let’s look at example that displays the module in a Definition List (a set of DL’s, DT’s and DD’s).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):

/*
 * Module chrome that wraps the module in a definition list
 */
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
   <dlkw2"><?php echo $params->get('moduleclass_sfx'); ?>">
      <?php if ($module->showtitle != 0) : ?>
         <dt>
            <?php echo $module->title; ?>
                </dt>
            <?php endif; ?>
                <dd>
            <?php echo $module->content; ?>
                </dd>
            </dl>
        <?php
}

We will be calling the style “dlist”, so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

  • showtitle tells you whether to show the title of the module of not
  • title is the title of the module
  • content is the output of the module (from its layout)

This is a very simple case and you can, of course, design more complex styles, possibly using custom atrributes in the XML tag.