Real Men write Joomla templates from scratch with nothing but vi and an obsidian arrowhead. But I bill by the hour, so my clients appreciate it when I modify existing ones to meet their needs.
The following assumes Joomla 1.6 through 2.5. Previous versions of Joomla differ in their handling of templates, but some of what follows is generally applicable. They might apply to more recent versions of Joomla, but as of this writing I haven’t had the opportunity to check.
Choose a template you wish to modify and insure its license allows derivative works. Unpack the template into a temporary working space. Inside the template’s directory, create the file CHANGELOG.txt and document there all the files you add or modify. This will help you later when you have to make changes and you don’t remember what you did.
Edit templateDetails.xml. You have to at least:
- Replace <name>original_name</name> with the template’s new name. It will appear in the Template Manager, so choose something human-friendly.
- Add <filename>CHANGELOG.txt</filename> to the <files> section.
- Replace <language tag=”en-GB”>en-GB/en-GB.tpl_original_name.ini</language> with the new name. Do the same on the next line, en-GB.tpl_original_name.sys.ini.
While I’m there I also change <creationDate>, <author>, <authorEmail>, <authorUrl>, and <copyright>.
In index.php, component.php, and error.php, and change the paths to reflect the template’s new name. Search the rest of the template for other files that might reference the old path.
In the directory language/en-GB, change the names of the files en-GB.tpl_original_name.ini and en-GB.tpl_original_name.sys.ini to reflect the template’s new name.
Now compress your modified template using zip and install it on your local instance of Joomla. The template is by no means ready; we install it now so we can see what we’re doing as we continue to work on it. We’ll make a final zip package when we’re through. In the meantime you can now delete the original unzipped files in the temporary working space.
Depending upon your system’s permissions, you may have to change ownership of the installed template’s files to edit them. For example, on my development box I have to (as root) chown -R user:apache /var/www/html/joomla1.6/templates/template-name/, replacing user with my username.
I use Bluefish as a simple IDE for this kind of work, so I create a project in Bluefish and add to it the installed versions of the files we’ve created or modified. Any other text file I modify also gets added.
Check your work in your local instance of Joomla. Correct any errors and make other changes as desired. Common changes include:
- Replace the favicon.
- In the directory language/en-GB/, edit the files en-GB.tpl_new_name.ini and en-GB.tpl_new_name.sys.ini. In both, find the placeholder XML_DESCRIPTION. Replace it’s value, which is the original template’s description, with your own.
- Add translations to the language/ directory, using the en-GB/ subdirectory as a model.
- Create an offline page to be shown to site visitors when the site is offline. Copy the file templates/system/offline.php to templates/TEMPLATE_NAME/offline.php and modify as desired. Common changes are to replace the default image and to remove the login form. (TODO: This works for Joomla 1.5, but does it still apply to 1.6 and later?)
Comment and document the changes you make.
Once tested, take a screenshot of your new template. Save it as a thumbnail PNG, 640 x 380 pixels, and save it as template_preview.png, overwriting the original. Then save it at 200 x 120, overwriting template_thumbnail.png.
Review file permissions to insure that nothing has been inadvertently changed. As with the rest of Joomla, files should be 644 and directories should be 755.
When all is well, compress your completed template to create the final installer. Valid compression types are tar.gz and zip. Install it on the remote server (Extensions – Extension Manager – Install). Test to insure all is well.
TIPS AND TRICKS
A useful reference is Customizing the JA Purity template. Although written for Joomla’s 1.5’s default template, much of its information is applicable to template customization generally and for more recent versions of Joomla.
Templates are written in XHTML, not HTML. If (like me) you are accustomed to writing HTML, then validation is even more important that usual.
When modifying or creating new PNG images, save them as indexed rather than RGB when practical, which usually decreases the file size considerably. If you use The Gimp, this is done in Image – Mode – Indexed.
You can view the module positions of your active template by appending &tp=1 to the end of any URL. As a security feature, Joomla ships with this feature disabled; enable it at Extensions – Template Manager – Options – Templates. Disable it when no longer needed.
Templates for Joomla 1.5 (not earlier, not later) require a params.ini file, but many 1.5 templates lack it or give it incorrect permissions. To keep the Joomla backend happy, create an empty file with that name if needed and insure that its permissions are 644, just like any other file in Joomla.
Changing the Joomla Offline page
Features introduced in Joomla 1.5 templates
Joomla 1.5 template tutorial
Joomla! 1.6 Default Templates
The tutorial how to design templates for Joomla 1.6 is oriented towards writing a template from scratch, but also provides useful background information for template modifiers, too