How to reuse Joomla 1.5 Templates?

This seems to be an ever returning question in Joomla world, you might already read the first part of the sequel: How to reuse Joomla 1.0 templates?. So, let's go one step further, and let's see how we can easily reuse those nice Joomla 1.5 templates in the post-Joomla 1.7 world (more specifically under Joomla 2.5). Don't expect a fully covering guide on how to convert Joomla 1.5 template to Joomla 2.5 template, but instead a detailed description on what I usually do - less theory, more practical knowledge.

As you might expect, the transition from Joomla 1.5 to Joomla 2.5 is easier in most cases, as the previous transition from Joomla 1.0 to Joomla 1.5 was. In most cases - I said ;) - because the trickier, more elaborated commercial Joomla 1.5 templates can be a real challenge. But let's see, how we can do the transition in an average case!

Generally you need to change 3 major things: the template's XML file, the index.php file and do some changes in the folders structure.

Let's take a look to them, one-by-one!

The template's main XML file: the templateDetails.xml

The first and foremost changes are found in the very first lines of the file, generally you will need to change (or add, if wasn't there) the DOCTYPE declaration and change the <install> tag occurrences (the opening and closing tags) to the <extension> tag, from the old syntax:

<?xml version="1.0" encoding="utf-8"?>
<install type="template" version="1.5">

to the new one:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.6//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.6/template-install.dtd">
<extension version="2.5" type="template" client="site">

The last line can contain the optional method switch too, so may look like as:

<extension method="upgrade" type="template" version="2.5" client="site">

(Note that the order of parameters is not important). The next important change is in parameters section. In Joomla 1.5 parameters are defined as part of the <params> section, and each parameter is defined as a <param>, beginning with Joomla 1.6 template parameters are contained in the <config> section and treated as a <field> nested within the <fieldset> and <fields> tags.

So the old syntax looked like:

<params>
     <param name="" type="" default="" label="" description="">
                <option value="1">On</option>
                <option value="0">Off</option>
     </param>
      <param name="" type="" default="" label="e" description="" />
</params>

The same parameters with the new syntax will look like:

<config>
    <fields name="params">
        <fieldset name="basic">
            <field name="" type="" default="" label="" description="">
                <option value="1">On</option>
                <option value="0">Off</option>
            </field>
            <field name="" type="" default="" label="e" description="" />
        </fieldset>
    </fields>
</config>

Note, than on the old syntagx the parameters - if where grouped, in more, than just basic group, where added by using a new pairs of <params> tags, like

<params group="advanced">
              ...
</params>

Now grouping of the parameters is mandatory, and for this purpose tis used the <fieldset> tag.  So, even if we have only one parameters group, we must have <fieldset name="basic"> tag, which wraps the parameters in the default grouping element. Using name="basic" labels that element as "Basic Options" and name="advanced" labels it as "Advanced Options". The name, type, default, label and description attributes still apply.

Outside of the main template files, you can access these parameters using the JApplication class. Previously, the values of the template parameters were stored in a plain text .ini file. In order to access those values outside of the template you needed to read the ini file and load the data into a JRegistry or JParameters object. Now, the values are stored in the database with other template information. We can load the params by passing the true variable to the getTemplate method of the JApplication object. We will show later, in the next section how this can be performed.

The next major change is in method to include files in the template package. Using the the old syntax you should reference them one-by-one, like this:

<files>
    <filename>html/com_content/article/default.php</filename>
    <filename>html/com_content/article/form.php</filename>
    <filename>html/com_content/article/index.html</filename>
    ...
</files>

Now you can - in fact, you should - include them grouped, referenced by the directory which contains them. In the new version the above code will look like:

<files>
    <folder>html</folder>
    ...
</files>

Since the template parameters are now stored in the database, and not in a textfile, you should drop the params.ini file and the reference in the XML file to it.

Joomla 2.5 introduces new file "error.php" to contain layout of error pages. This file is simple and we can reuse the file from default theme "atomic"., so you need to copy over the file from there, and add a reference to it in the XML file like:

<filename>error.php</filename>

Joomla 2.5 introduces new file "template_preview.png" to present big preview image of the theme. So you need to create a 640x480 screen-shot of your theme and name it "template_preview.png", you need to add this to the template's root directory and add a reference in the XML file to this file too:

<filename>template_preview.png</filename>

In most cases these are the changes you need to do in the templateDetails.xml.

Changes in index.php file

We already mentioned, that the template parameters are now stored in the database. So, from now on, if you need to access them in your index.php file (or anywhere in your template, they can be accessed like this:

$app		=& JFactory::getApplication();
$template	= $app->getTemplate(true);
$params		= $template->params;
$variable	= $params->get('variable');

This will allow you to access the template parameters in your layout overrides for other components, and modules.

Also you need to add the code to load the MooTools library. For this add these lines somewhere at the very beginning of your template:

/* The following line loads the MooTools JavaScript Library */
JHtml::_('behavior.framework', true);

If you had the template name hard-coded in your index.php - for example in the includes of needed JavaScript or CSS resources, then you should eliminate these, using for example instead of

rhuk_milkyvay

the more elegant and foolproof

<?php echo $this->template; ?>

There are also some other code changes, we just enumerate a few of them:

a. Sitename

$mainframe->getCfg('sitename');

is now

$app->getCfg('sitename');

To access this variable - and many others - you need to call the getApplication() function first, like this:

$app = JFactory::getApplication();

b. Error Codes

$this->error->code

is replaced by

$this->error->getCode();

And similarly

$this->error->message

is replaced by

$this->error->getMessage();

Template overrides

There is not too much changed here, the structure remained similar, the eventual problems can rise because of the use of new Joomla API. For example, if your old template used the overrides inherited from the Beez template, then you can have the surprise to see this error:

JHtml::icon not supported. File not found. 

this can be fixed by adding a line in the html/com_content/article/default.php file (from wich override the error is originates:

JHtml::addIncludePath( JPATH_COMPONENT . '/helpers' );

The files/folder structure changes

As we mentioned, at least one file - the params.ini - is no more needed, and 2 files are introduced, the error.php and the template_preview.png. The rest of the usual structure is the same.

Once you are reached this point, you can pack and try to install your template - or simply upload it to your test server. There might happen, that even if the procedures above are succeeding and you don't see your new template in Template manager. There is a simple cure for that. Go back to the Extension Manager, click on Discover tab, then in the top right menu click on the Discover icon.

A list of items wich are found on server, but for one reason or another the install procedure ended prematurely or was not completely performed. If the template's main XML file is correct, you will see your newly upgraded template in the list. Click on it, and you will be able to use it!