Migrate a Joomla 1.5 Template to 2.5

Joomla 2.5.3 ReleasedJoomla 1.5 has been a great platform but its time is coming towards an end. Security updates for Joomla 1.5 are likely to end in September 2012.

We have already given you detailed instructions on moving the main part of your site from Joomla 1.5 to 2.5 using jUpgrade and SPUpgrade. In this tutorial we're going to show you how to update a Joomla 1.5 template to work with Joomla 2.5.

For simple templates, there aren't a lot of steps needed to migrate 1.5 template for 2.5. However upgrading a sophisticated template will be trickier.

We're going to show you the easiest possible way to update. We're going to rely on cutting-and-pasting code so you can do this without having to learn any PHP or programming.

The template we'll be using: Versatility 4


The template I'm going to demonstrate is Versatility4 which you can get from http://rockettheme.com. RocketTheme does have an updated version of this, but it's a good example of a fairly complex template for this tutorial. Still, it's worth checking to see whether your template provider has a Joomla 2.5 version already created for you. It will save you from going through this complete tutorial

The process of moving your template involves several parts:

  1. Move your main site to Joomla 2.5.
  2. Create a new template folder for your new Joomla 2.5 template.
  3. Move over the files and folders from your Joomla 1.5 template to your 2.5 template. Except for index.php and templateDetails.xml.
  4. Migrate the code in the templateDetails.xml file.
  5. Migrate the code in the index.php file.
  6. Discover and publish your template in the Joomla 2.5 administrator area.

That's the general process that we're going to use. Here are the specific steps you'll follow:

Step 1: Move your main site to Joomla 2.5

Before you start, use jUpgrade or SPUpgrade to create a new version of your site in Joomla 2.5. You can do this using our 1.5 to 2.5 update tutorials for jUpgrade and SPUpgrade. Neither of those will modify or upgrde the templates from 1.5 to 2.5, although the directory may (or may not) be copied to the upgrade destination. We're going to assume it wasn't copied.

Step 2. Copy the Atomic template

  • Access your Joomla site files and go to the /templates/ directory.
  • Copy the entire /atomic/ directory and give this new directory the name /atomicVersatility/. The Atomic template is extremely basic, and was really intended for purposes like this. You can use this process with other base templates as well, but this one is free and already installed.

Step 3. Delete the template.css file from the Atomic template

  • Go inside the /templates/atomicVersatility/ folder.
  • Delete or rename the template.css file. We want to replace this and don't want to use any of the Atomic CSS. You probably won't need to change the template_ie.css and template_rtl.css files. 

Step 4. Copy directories and files from your 1.5 template to the new template with two exceptions.

  • Go inside the old Joomla 1.5 /templates/yourtemplatename/ folder and copy all of the files and folders, except for index.php and templateDetails.xml, into the /templates/atomicVersatility/ folder.
  • Make sure that all of your Joomla 1.5 CSS files are now copied to /atomicVersatility/css/.
  • You do not need to copy the templateDetails.xml file or index.php because We're going to be modifying the one in the destination directory for this tutorial. This will make copy and paste as simple as possible with an abolute minimum of code writing.

Step 5. Change the entry in templateDetails.xml to match the name of the new template folder

  • Open /templates/atomicVesatility/templateDetails.xml, and change the entry to match the name of the template folder. It is case-sensitive so make sure you type accurately.
  • Change the other elements as necessary. For instance, you might want to modify the creation date and version number and the description.

Step 6. Move the positions section in templateDetails.xml

  • Go inside the old Joomla 1.5 /templates/yourtemplatename/ folder and open the original templateDetails.xml file.
  • Find the positions section and copy it to your clipboard.
  • Go inside the /templates/atomicVersatility/ folder and open the new templateDetails.xml file.
  • Paste the 1.5 positions section over the top of the old positions section. You can completely eliminate the old postions.

Step 7. Move the parameters section in templateDetails.xml

We are now going to repeat that task with another section of the templateDetails.xml file. In a complicated template there will be a section of the templateDetails.xml file called params that contains numerous settings for the template. In a simple template there will be very few or even none.

In Joomla 1.5 templates, the code for this section was written like this:


Now the code is a bit different, so you can't just copy this section and put it in the new xml file. The format for this section is now substantially different:


Everything that was once a "param" is now a field inside a fieldset. The parameters for simple templates are quick to move from 1.5 to 2.5, but modifying complicated templates can be very time consumiing if you have to type everything.

Be sure to type in the opening tags correctly as in the image below:


And be sure to end with these closing tags.


If you're unfamiliar with these parameter tags, take your time and refer back often a working templateDetails.xml file from a Joomla 2.5 template. Be sure to change all the tags in the entire list of parameters that need changing.

Step 8. Remove the the body section in atomicVersatility/index.php

  • Go inside the /templates/atomicVersatility/ folder and open your new index.php file.
  • Delete everything between and including the opening and closing body tags.
  • Go inside the old Joomla 1.5 /templates/yourtemplatename/ folder and open the index.php file.
  • Copy everything between and including the opening and closing body tags onto your clipboard.
  • Go inside the /templates/atomicVersatility/ folder and open your new index.php file.
  • Paste everything on your clipboard between the opening and closing body tags in atomicVersatility/index.php.

Step 9. Move the basepath info in index.php

  • Go inside the old Joomla 1.5 /templates/yourtemplatename/ folder and open the index.php file.
  • Look for these basepath lines or anything similar. Copy them to your clipboard.

define( 'YOURBASEPATH', dirname(__FILE__) ); require( YOURBASEPATH.DS."rt_styleswitcher.php");

  • Go inside the /templates/atomicVersatility/ folder and open your new index.php file.
  • Paste in the new basepath lines directly beneath the line "defined ("_JEXEC") or die". It should look like the following image:

Step 10. Move the Mootools behavior in index.php

The next thing is to get the Mootools behavior.

  • Go inside the /templates/atomicVersatility/ folder and open your new index.php file.
  • Search for anything relating to Mootools or anything that might be written under Jhtml::_('behavior.mootools");
  • Go inside the old Joomla 1.5 /templates/yourtemplatename/ folder and open the index.php file.
  • Look for JHtml::_('behavior.framework', true): paste your code there.


  • Between line 15 and 16 paste all of the lines of code from the Joomla 1.5 version that appear after $app = JFactory::get Application(); and come before the document type declaration. Your line numbers may be different than mine. I am using the numbers in the picture strictly as a reference.
  • There may be quite a few lines of code and sections divided by comments. Makes sure the last thing at end is the ?> which is the php closing tag.
  • Below is a view of the code in the new index file showing that the application object section is blank. On this illustration, you'll be pasting the entries from the old file between lines 15 and 16.

Step 11. Modify the $live_site line in index.php

  • Under $app =Jfactory::getapplication(); there will be line for $live_site. Change $mainframe to $app. For example, find the following line:

$live_site = $mainframe->getCfg('live_site');

  • Change those lines so that it now reads like this:

$live_site = $app->getCfg('live_site');

  • The entire section should end with the closing ?> tag , and come before the DOCTYPE.

Step 12. Check the head section of the original index.php

  • Go inside the old Joomla 1.5 /templates/yourtemplatename/ folder and open the index.php file.
  • Check the head section and look for additional lines of code. Copy them to your clipboard.
  • Go inside the /templates/atomicVersatility/ folder and open your new index.php file.
  • Paste the code into your new index.php between the head tags. Be sure to include the opening and closing PHP tags.

Step 13: Discover the new template and set it as the default

  • 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.
  • Go to Administrator > Extensions > Extension Manager > Discover.
  • Click the Discover icon.
  • If your template appears on the list, select it and then click the Install icon.
  • Return to the Template Manager and set it as the default by clicking the star. That will complete the process of moving your template from Joomla 1.5 to 2.5.

Other Resources