Joomla Templates 111 - Module Chrome

April 09, 2009

Reading time ~2 minutes

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.

In Joomla version 1.5, the numbers are still recognised, but more commonly the style is represented as a word. The syntax for displaying a module position was also 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 by adding tp=1 to the URL)

In the source code, these styles are actually referred to as chrome. As covered in a previous section, the default chrome can actually be found in the system template provided in the default Joomla install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your Joomla installation.

To create your own chrome, or module styles, all you need to do is 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 actually does provide some extra chrome as an example (it provides and new example style called slider). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

Creating your own chrome is really easy. Let’s look at ficticious 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 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.

Advanced Test Driven Development for Node - Part 1

Part 1 of my attempt to port Robert C. Martin's talk '8LU:Advanced Concepts in TDD' to Node. Continue reading

Semantic versioning for retail software

Published on December 11, 2014

Better Grunt files (for organised developers)

Published on December 02, 2014