Archived:Upgrading a Joomla 1.5 template to Joomla 2.5

This page has been archived. This page contains information for an unsupported Joomla! version or is no longer relevant. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

This page provides feedback on the process of upgrading or converting a Joomla 1.5 template for use with Joomla 1.6 and later versions from those who have already attempted it. This is intended to be a living document that can be added to as more experience is gained and is likely to be reorganised periodically. If you have encountered a problem when upgrading a template, or if you have any information that you think will help smooth the way for others who will follow then please add your comments initially on the Talk page. We will then collate the information and incorporate it into this page.

Chris Davenport prepared slides for a presentation at the JoomlaDay UK 2010 event which explain the changes in templates for Joomla! 1.6.

Template Manifest File

There are important changes to the templateDetails.xml file:

1. Edit the DOCTYPE.
2. Change the <install> tag to <extension> as shown below.

<?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">

Notice the additional new client attribute which is set to site for a front-facing template and administrator for an back-end template.

Be sure to change the closing tag from </install> to </extension>.

Template Parameters

In Joomla! the template parameters are defined in templateDetails.xml. Whereas in 1.5 parameters are defined as part of the <params> section, and each parameter is defined as a <param>, in 1.6 and later, template parameters are contained in the <config> section and treated as a <field> nested within the <fieldset> and <fields> tags, as illustrated below.

<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>

<fieldset name="basic"> wraps the parameters in a 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. It 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 params in your layout overrides for other components, and modules.

Objects and Methods

Sitename

• <?php echo $mainframe->getCfg('sitename');?> is now $app->getCfg('sitename'); Where $app = JFactory::getApplication();

Error Codes

• $this->error->code is replaced by $this->error->getCode();
• $this->error->message is replaced by $this->error->getMessage();

Discovery

In some cases your converted template may not be shown in the Template Manager even though all coding appears to be correct. Verify that your template files are installed in the /templates directory. Then run the Discover process as follows.

1. Go to Administrator > Extensions > Extension Manager > Discover
2. Click the Discover icon.
3. If your template appears on the list, select it and then click the Install icon.

Layout Overrides

com_content

If you have used the Beez overrides, or code derived from the Beez overrides, in your 1.5 template, you may encounter a JHtml::icon not supported. File not found. error when migrating the template to Joomla 1.6 and later. To fix this, simply add the following statement near the top of the template html/com_content/article/default.php file:

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

Alternate Method Using a Version 2.5 Template

Start with a basic template that works with a current version of Joomla. For this example, use the Atomic template that is supplied with Joomla 2.5.

1. Copy the entire /templates/atomic folder to a new folder in the /templates directory.
2. Rename this new folder. For instance, you might call it mysitename-atomic to designate it as the custom template for this site and adding the reminder that it was derived from the atomic template.
3. In the new template's index.php file, delete everything between the <body> </body> tags.
4. Copy and paste everything within the <body> </body> tags from your version 1.5 template to the body of the new template's index.php file.
5. Delete or rename the template.css file copied from the Atomic template.
6. Copy the template.css file from the old version 1.5 template.
7. Update the templateDetails.xml file in the revised template.
   1. Change the <name> entry to match the name of the template folder. It is case-sensitive. If the folder is /templates/mysitename-atomic, the entry in the templateDetails.xml file will be <name>mysitename-atomic</name>.
   2. Replace the <positions> section of the file so that they match the positions used in the index.php file.
   3. Change the other elements as necessary. For instance, you might want to modify the creation date and version number.
8. Delete images in the /template/image file and add your images.
9. Delete the lines in the <head> section of the index.php file that load CSS and Javascript files that are not needed.

Template Root Directory Considerations

Compare the files in the root directory of the new template to old template's root directory files. It may be necessary to copy a few of the old files to the new template.

For example, copy the old favicon.ico file to the new template's root directory.

Remove the /html directory that was in the donor template. Copy the /html directory from your old template's files.