Migrating a Template from Joomla 1.5 to 3.x
From Joomla! Documentation
When considering an update to your 1.5 template there are a few considerations.
First, what skills do you need? To make template changes, minimally you need to be familiar with the basics of PHP, HTML, XML, CSS and possibly some JavaScript. If you don’t have a basic grasp of these skills a lot of what you’ll be looking at will look foreign so either brush up on those skills or hire a professional.
Second, the extent that your template needs to change must be measured in terms of the new enhancements or design changes that have developed in planning your migration. Is the change going to take advantage of new Bootstrap framework styling that is available in Joomla 3? Or is it a strict move that mirrors the current site. While some of the changes that are new to Joomla 3 are mandatory (meaning your template will not load), others are enhancements and your template will load but might not look the way you want.
For purposes of this document we will be assuming the simplest example and suggest a mirror image of the current 1.5 template. For more complex templates or for major enhancements you may need to do some research or hire someone who has more experience with templates.
Review the Basics of Templates[edit]
Some things haven't changed. You still need to be familiar with the basics of a JoomlaTemplate: The folder directory structure is one of those things. Minimally at the root level you need 2 files: index.php and templateDetails.xml (notice the case!). Most templates include at least two folders: an images folder to hold all the graphics that your template uses and a folder for your CSS styling. More advanced templates might contain folders with names like these for example: html for component and module customization, a “language” folder for custom language overrides, javascript to hold custom JavaScript routines.
Just be sure if the folder is listed in the XML file it exists in the template you upload to Joomla. If you declare a file in the xml then it must exist or your template will not load.
One example of an improvement in versions greater than 1.5, is the dropping of the requirement that all the subfolder filenames be listed. For templates in Joomla 3, you simply list the folder name.
For more information on the basics of a template see this link: Creating a basic Joomla! template
XML File Changes[edit]
What needs to change in the templateDetails.xml file ( Template Manifest File )
The template manifest file provides the information Joomla needs to install your template. The XML manifest file has been almost completely modified since 1.5 so make sure you study up and are familiar with the basics and the modifications. Your template will not load if this file is not exactly right.
Document Reference Type Tag and the Install/Extension Tag[edit]
The XML Install tag is now an “extension” tag. Additionally, any reference in the DOCTYPE Tag or version numbers now needs to refer to 3.0.
The old lines are something like this:
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://dev.joomla.org/xml/1.5/template-install.dtd">
<install version="1.5" type="template">This now needs to look like this:
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">
<extension version="3.1" type="template" client="site">Folder and File Tags[edit]
This rule has always been true and still is: If you list the Filename or Folder in the XML it must exist in the uploaded template. This has not changed in Joomla 3. What did change is the 1.5 requirement that all the filenames in a folder be listed. Now you can refer to just the folder name. For example, previously in 1.5 your xml filenames were listed individually as follows:
<images>
<filename>images/arrow.png</filename>
<filename>images/arrow2.png</filename>
<filename>images/arrow3.png</filename>
<filename>images/author.gif</filename>
</images>For a Joomla 3 template this statement suffices:
<folder>images</folder>Module Tags[edit]
For 1.5, module positions were defined in the template. This has not changed. They still need to be listed.
Parameters[edit]
Parameters are an optional feature of templates that allow the template author to offer options for styling of the template in the Joomla Administrator. In Joomla 1.5 templates the parameters were listed in a "parameters.ini" file at the root level. This file has been eliminated and the parameters are now tags in the XML file.
Here is an example of the contents of a parameters.ini file:
colorVariation=blue
backgroundVariation=blueTo define the parameters in Joomla 3 you must add these lines to the XML file:
<config>
<fields name="params">
<fieldset name="advanced">
<field name="colorVariation" class="" type="color" default="#08C"
label="TPL PROTOSTAR COLOR LABEL"
description="TPL PROTOSTAR COLOR DESC" />
<field name="backgroundVariation" class="" type="color" default="#F4F6F7"
label="TPL PROTOSTAR BACKGROUND COLOR LABEL"
description="TPL PROTOSTAR BACKGROUND COLOR DESC" />
</fieldset>
</fields>
</config>For more complex parameter XML tags you may have to refer to more complex documentation. Also note that the index.php that reference the parameter variables will also need to be changed.
See these links for more information about:
The index.php File[edit]
What needs to change in the index.php file?
The index.php files are as widely varied as there are designers and programmers that write them. The index.php in a template for Joomla 3 is the compilation of the many versions that came before including 1.5, 1.6, 1.7, 2.5, etc. This template file is the "bloodstream" providing life to your skin, and it has access to every piece of Joomla's framework available and can use these pieces to manipulate what your site is going to look like to your users. This has always been true and still is. Template designers and programmers have taken advantage of this fact in previous versions and will continue to, so this file needs the most careful research and planning.
Changes that were made to the framework for Joomla 3 may cause problems to some older templates and when rendered could produce errors. Other templates may not have referenced the same piece of framework at all and work fine with almost no changes. For example, a 1.5 template that accesses the variable value frontpage to determine if they are on the home page or not. This doesn't work in Joomla 3. (See table below for code ) If a template referenced a changed piece or not will be the determining factor of how many issues you will have when trying to implement your updated template.
Be prepared to make some changes based on “best practices”. Although your index.php may function, it needs to be secure and execute efficiently. Consider that every page served to your audience uses the index.php file so make sure you are familiar with the recommended methods for the Joomla framework and building blocks for a template. A thorough study of the index.php file in both the Protostar Template and the Beez Template that is included with the Joomla 3 installation package can provide examples and best practices for more complex templates.
Guidelines[edit]
Here are some guidelines for your Joomla 3 template index.php file:
1. Again, some things haven't changed: all index.php templates need to start with this statement:
<?php defined( '_JEXEC' ) or die;?>True for Joomla 1.5 and still true for Joomla 3.
2. For Joomla 3 the recommended DOCTYPE ( Document Type Declaration ) should be HTML5 as this is used throughout Joomla 3. Here is an example:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">3. To make use of Joomla 3's application framework:
In 1.5 access to the framework was done through the $mainframe variable. You might see something like this:
<?php require_once ('includes/../framework.php');
$mainframe =& JFactory::getApplication('site'); ?>- replace it with this:
<?php $app = Jfactory::getApplication();?>4. To retrieve the Heading code use this statement directly beneath your heading tag and follow it with your stylesheets. This has not changed with the Joomla 3 but always bears repeating:
<jdoc:include type="head" />5. To retrieve the sitename in 1.5 you might see this:
<?php echo $mainframe->getCfg('sitename');?>For Joomla 3 use this code:
<?php $app->getCfg('sitename');?>6. Error Codes and Messages:
A better methodology for retrieving error codes is in place for Joomla 3. You might see this in your 1.5 template:
<?php $this->error->code; ?>- replace it with this Joomla 3 convention:
<?php $this->error->getCode(); ?>For error messages, this is a typical 1.5 statement:
<?php $this->error->message; ?>- Replace it with this statement for Joomla 3
<?php $this->error->getMessage(); ?>7. To access the template parameters in replace code that looks like this:
<?php $color = $this->params->get('colorVariation'); ?>- with this recommended methodology:
<?php $app = Jfactory::getApplication();
$template = $app->getTemplate(true);
$params = $template->params;
$color = $params->get('colorVariation'); ?>This will work equally well as an example:
<?php $app = Jfactory::getApplication();
$params = $app->getParams();
$color = $params->get('colorVariation'); ?>8. Access to the Global Document Object classes in the index.php template file is typically coded this way:
<?php $doc = Jfactory::getDocument(); ?>This statement is the same in Joomla 3. However, it is valid to note that this statement is not necessary to access the page classes so it might be there or it might not depending on the original programmer. For example: given the code:
<?php $doc =& JFactory::getDocument();
echo 'Current title is: ' . $doc->getTitle(); ?>is equivalent to this code:
<?php echo 'Current title is: ' . $this->getTitle(); ?>In Summary[edit]
The table below is a quick reference of code differences between a Joomla 1.5 and Joomla 3.x template's index.php file.
| Description | In a 1.5 Template (index.php) you might see | Recommended J3.x Template (index.php) code |
|---|---|---|
| First Line | <?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
|
No change |
| DOCTYPE | <?php echo '<?xml version="1.0" encoding="utf-8"?'.'>'; ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>" > |
<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>"> |
| Access to Joomla Framework | $app = JFactory::getApplication(); OR
require_once (‘includes/../framework.php' );
$mainframe =& JFactory::getApplication('site');
|
No change but needs to look like this:
$app = JFactory::getApplication(); |
| Retrieve HTML headers from Joomla | <jdoc:include type="head" /> |
No change |
| Retrieve the Sitename | $mainframe->getCfg('sitename');
|
$app->get('sitename');
|
| Retrieve Error Codes | $this->error->code |
$this->error->getCode(); |
| Retrieve Error Messages | $this->error->message |
$this->error->getMessage(); |
| Retrieve System Messages | $this->getBuffer('message')
|
<jdoc:include type="message" /> |
| Active Language | $this->language; |
$doc->language; |
| View | JRequest::getVar( 'view' ) |
$app->input->getCmd('view');
|
| Task | JRequest::getVar( 'task' ) |
$app->input->getCmd('task');
|
| Layout | JRequest::getVar( 'layout' ) |
$app->input->getString('layout', 'default');
|
| ID | JRequest::getVar( 'id' ) |
With alias:$app->input->getString('id');
Only ID:$app->input->getInt('id');
|
| Homepage detection | <?php if(JRequest::getVar( 'view' ) == 'frontpage') ?> |
<?php $menu = $app->getMenu(); if($menu->getActive() == $menu->getDefault()) ?> |
| Main Content | <jdoc:include type="component" /> |
No change |
| Modules & Positions | <jdoc:include type="modules" name="right" style="xhtml" /> |
No change |
| Retrieve Base URL | $url = clone(JURI::getInstance()); echo $this->baseurl; JURI::root()*; |
JURI::base(); $this->baseurl; |
| Access to Document Page Classes | $doc = JFactory::getDocument(); |
No change
However, use of "$this->" is equivalent. |
| Access to Template Parameters | echo $this->params->get('colorVariation');
|
No change |
Bootstrap Styling and Joomla 3[edit]
To incorporate the new Bootstrap Styling ( 2.3.2 ) into your updated template, use these three lines at the very top of your index.php, replacing the one line php block.
<?php defined( '_JEXEC' ) or die;
JHtml::_('bootstrap.framework');
JHtml::_('bootstrap.loadCss', true, $this->direction); ?>After these statements, you can add Bootstrap (2.3.2 ) classes wherever you need to and take advantage of the Bootstrap Framework offered in Joomla 3.
This Bears Repeating...[edit]
There are many variations of coding practices and your success with translating a 1.5 template into a template fit for Joomla 3 depends on the complexity of the old and new design, and the original coding. Your template might have been previously converted from Joomla 1.0! Your best strategy is to research the documentation available and become familiar with the Protostar and Beez templates in Joomla 3. Techniques for coding and structuring in these 2 templates have undergone the scrutiny of the Joomla community and volunteer developers – the true experts on how to best make your template secure and function reliably.