HTML

module

PHP

template

Styling the output of the Joomla was - and is - one of greatest challenges. One of tools making this easier for template developers is the "module chrome" concept/toolset introduced with Joomla 1.0 and constantly evolving ever since.

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:

• Nobody could remember which number was which, and
• 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)

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 Joomla project team, 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)
{ ?>
   <dl class="">
      <?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 attributes in the XML tag.