Using multiple templates’ overrides in Joomla 1.5 modules

Homepage > Diary > Coding > Using multiple templates’ overrides in Joomla 1.5 modules

Sun 09/20/2009

One of most usefull feature in Joomla 1.5 is the ability to quickly customize the HTML output of a module by using template overrides (see here for details).

The only problem is that, once you have coded an override for a module, it’ll be used for all module’s instances within the CMS. The issue here is that you might want to output one module in a column as just a simple list of links AND in the main body as a content-rich table.

This problem can be addressed with a module hack and the addition of a new backend parameter type (for 1.5 native modules only), both in a system wide or module specific way . Here is a step by step tutorial:

Adding a new parameter to the module

Joomla 1.5 features a native way to add backend parameter types beside the native ones. In our case i’ve realized a new element (parameter) file which will look if a template override folder exists for the spefic module and, if found, will list all PHP files whose name is prefixed with “custom_” . You can download the file here.

Now you’ll need to place this file inside a folder called element, then open the .xml configuration file of the module and search for the <params> opening tag. Replace it with the following code (YOURMODULENAME is the module name):

<params addpath="/modules/mod_YOURMODULENAME/element">

Now place the new parameter as the last child of the <params> tag:

<param name="template" type="customtemplates" modulename="mod_YOURMODULENAME" default="default" label="Custom template" description="Use this custom template file" />

Hacking the main PHP module file

To make the module fully aware of the new template you choose, you need to pass the customtemplates paramenter to the static method which retrieves the template. For instance let’s say your mod_mymodule.php file has a line like this:

require( JModuleHelper::getLayoutPath( 'mod_mymodule') );

Now provide the customtemplates parameter by changing the line to:

require( JModuleHelper::getLayoutPath( 'mod_mymodule',$params->get('template','default') ) );

Done!

Untill no custom template’s overrides are found, the default template (default for the module or the default override if present) will be used. Once you’ll create a custom_whatever.php template file it’ll show up in the select list.

Adding the new parameter system-wide

By adding the parameter as a native-like parameter, you’ll be able to use it on all module without calling it in the <params> tag.

To add the paramenter system-wide you just have to place the customtemplates.php element in the /libraries/joomla/html/parameter/element folder. Since this is a custom element you shouldn’t have any problem on CMS upgrades.

The drawback

There’s a major drawback for this solution: since you are going to modify some module’s file you’ll need to keep a copy of them to prevent future upgrades from removing your changes (and breaking your template).

Dwight Jack Workroom