7 tips to help you convert your Joomla 1.5 template to Joomla 1.6

This morning I read a great post from our friends over at JoomlaPraise, about some of the changes involved in converting a Joomla Template from Joomla 1.5 to 1.6. Now that beta 4 has been released, with beta 5 scheduled to be released on July 12, it’s definitely time for template developers to start the process of converting their existing Joomla templates over to 1.6.

Over the past couple of weeks, I’ve been working on a new free template (Witblits) and last week I decided to start porting it over to Joomla 1.6. Due to the lack of current documentation, there were quite a few things I had to just “figure out” by scouring through articles, comments, bug reports, discussion boards, etc. I managed to figure out most of the issues I encountered and reading Kyles post this morning inspired me to contribute some of my findings to help make the transition over to Joomla 1.6 easier. I’m not going to cover the more obvious points that are already highlighted in Kyles post, so these are just a few extra things which you may find useful.

Disclaimer: All the points mentioned in this post are based on my own (relatively limited) experience of converting a Joomla 1.5 template to Joomla 1.6. If anything is incorrect or can be improved upon, please let me know in the comments and I’ll update the post accordingly.

---

1.) Ensuring your template’s admin options and frontend are fully translatable

One thing I wanted to ensure with Witblits is that both the backend options and frontend were 100% translatable. It took a bit of head-scratching initially, as I was unable to find any clear documentation explaining the changes to how language files work in Joomla 1.6, but I managed to get there in the end :)

Firstly, let me quickly go over the process of how the language files work in Joomla. In your template, you include a “language” folder, which includes sub-folders of each the languages you are providing translations for. In this case I only have a folder for “en-GB”, as I’m initially only going to provide a British English translation (which can then be used as a base by others to create different translations). Inside this folder, you have your actual language ini file, which needs to be named using the following convention: [ln-LN].tpl_[template-name].ini The [ln-LN] prefix refers to the language code, the tpl_ indicates that it is a translation for a template and the rest is pretty self explanatory. In the case of Witblits, the file is called en-GB.tpl_witblits.ini. There is a new feature in Joomla 1.6 which allows you to include a further “system” language file, whicch is used to display the extensions name and description in the users own language (providing there is a translation file included for their language) after they install the extension. I came across a few posts which said this was not necessary for templates, but looking through the language files for the default templates, I see each of them have one of these files, so I decided to include one anyways. The naming convention for the new description translation file is: [ln-LN].tpl_[template-name].sys.ini The only difference between this and the previous file, is the addition of the .sys before the .ini file extension. So again, in the case of Witblits, the name is en-GB.tpl_witblits.sys.ini. The format of the system language file is the same as the default one, however it only includes the language strings for the templates name and description.

Note: If you look in any already installed templates, you will not see any of these language files. The reason for this is because they are moved to the /SITEROOT/languages/en-GB/ (in the case of the British Language) when you install the template.

Letting Joomla know that there is a translation available

In order for Joomla to know that there is a translation included, you need to add the following snippet to your templateDetails.xml:

<languages folder="language/en-GB/">
   <language tag="en-GB">en-GB.tpl_witblits.ini</language>
   <language tag="en-GB">en-GB.tpl_witblits.sys.ini</language>
</languages>

Notice how I’ve specified the folder path, specifying where the translation files are located in relation the templates root. Now that we’ve created the necessary language files and Joomla now knows there is a translation available, we need to add the following block to the top of the language file:

; $Id: en-GB.tpl_witblits.ini 10498 2008-07-04 00:05:36Z ian $
; Prothemer
; Copyright (C) 2010 Web Monkeys Design Studio. All rights reserved.
; License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
; Note : All ini files need to be saved as UTF-8

This includes the copyright and license information. The only thing to point out here, is the necessary use of semi colons for the file top info, instead of the pound (#) sign, which was previously the case for .ini files in Joomla 1.5. It took me quite a bit of digging to figure this one out and the translation won’t be picked up until they are changed.

Including a translation file for options in the template admin

One of my initial challenges with the translation, was how to provide one translation for the admin options and one for the templates frontend. In extensions, this is defined by wrapping the admin language file (named the same as the frontend version) in the <administration> xml tag. After trying a number of different variations and lots of Googling, I eventually discovered that this does not apply to templates. Both the backend and frontend language strings are combined in the templates main language file. For the backend translation, you need to create language strings which correlate with the ones you have in your language file. An example of this would be:

<field name="blockwraps" type="radio" default="0" label="TPL_WITBLITS_LABEL_BLOCK_WRAPS" description="TPL_WITBLITS_DESCRIPTION_BLOCK_WRAPS">
   <option value="0">TPL_WITBLITS_VALUE_NO</option>
   <option value="1">TPL_WITBLITS_VALUE_YES</option>
</field>

Notice how the label, description and radio options all have language strings. In the language file, the strings would then be something like this:

TPL_WITBLITS_LABEL_BLOCK_WRAPS="Enable block wraps"
TPL_WITBLITS_DESCRIPTION_BLOCK_WRAPS="Enabling this option, will add a wrapping div around each of the templates blocks. This provides you with an additional hook, with which you can utilize the full width of the browser window, while still keeping your content centered with a fixed with."
TPL_WITBLITS_VALUE_NO="No"
TPL_WITBLITS_VALUE_YES="Yes"

---

2.) Taking advantage of the new “Media” element

Elements in Joomla represent the xml types that you use to create your options. The default types include: text, textarea, radio, list, section, category, spacer, filelist, folderlist – to name but a few.

These elements are used extensively throughout Joomla and in Joomla 1.6, we have the new JForms api (which replaces the now discontinued JParameter). Based on the various posts and discussions I came across, it seems the new JForm API is way more powerful and flexible. I haven’t had a chance to test the other new elements we have available in Joomla 1.6, but one in particular that I came across, which is a really nice addition is the new “media” element. This adds a text field, with a “select” button on the right of the input. Clicking the button opens a lightbox, with the option to select an existing image in the images/stories (or any sub folder of the images/stories), or upload a new one. The only issue I could see with this was that the lightbox window is a bit too small and thus hides the “insert” button, located in the top right. This could cause some confusion for users who don’t realize the content area is bigger than the lightbox window. That said, it’s still a really nice touch and I’m sure loads of template dev’s will be taking advantage of this one. To use the media element, simply add the following code to your templateDetails.xml (in the same section as the other “fields”:

<field name="logo_image" type="media" default="" size="50" label="TPL_WITBLITS_LABEL_LOGO_IMAGE" directory="templates/witblits/images/logos" exclude="\.html" hide_default="yes" description="TPL_WITBLITS_DESCRIPTION_LOGO_IMAGE" />

Which will then output a field that looks like this: Clicking the “insert” button, open’s the lightbox panel, allowing the user to either select an existing image or upload a new one:

---

3.) How to create custom elements for your template options

This was another part that took a bit of figuring out, but thanks to some guidance from Stian, I was able to figure it out.

In the Joomla 1.5 version of Witblits, I’d added two custom elements, “loader” and “colorpicker”. The loader element is used to inject some custom css and javascript files into the head, allowing me to not only tweak the admin options styling, but also included the necessary css and javascript for the custom colorpicker.

Creating the loader element

I decided that it would be quicker to use the new text element as a base, rather than port my existing elements. So I copied the /SITEROOT/libraries/joomla/form/fields/text.php (in Joomla 1.5 these are located in /SITEROOT/libraries/joomla/html/parameter/element/text.php), over to my templates/witblits/admin/elements/ folder, then renamed two instances of the file to loader.php and colorpicker.php. I then opened the loader.php file in my editor and stripped out all the unnecessary code. You can take a look at the original and my changed version, which is included in the attachment at the bottom of this tutorial. To activate the loader element, I simply added the following xml to the top of the rest of my fields: <field type="loader" /> Looking at the source code of the template admin, I could see that the files were being included correctly: Then, with the admin specific css file being included, I was able to tweak the admin options accordion and options styling:

Creating the colorpicker element

Once I had the loader working, I then proceeded to create the colorpicker element. I followed the same steps as before, though this time instead of stripping out the text input field code, I simply copied and pasted the code I’d used in the 1.5 version, with all hooks that the colorpicker needed. Once the elements output was finished, I just needed to update the javascript, which is used to activate the various colorpicker instances, as the input field names have changed in Joomla 1.6. Apart from the button to activate the colorpicker, I also added a span, which I then positioned over the right side of the text input and used some javascript to dynamically get the value from the colorpicker, so that it would act as a live preview of the color they were selecting.

The colorpicker element file is included in the zip file at the bottom of this post, so if you want to view the specific code changes, simply download the attachment and dig through the various files used.

To activate the colorpicker options, I simply add the following to my templateDetails.xml fields:

<field name="color_background" type="colorpicker" default="#fff" id="picker_color_background" previewid="preview_color_background" size="50" label="TPL_WITBLITS_LABEL_BACKGROUND_COLOR" description="TPL_WITBLITS_DESCRIPTION_BACKGROUND_COLOR" />

If you take a look at the colorpicker.php (included in the zip), you will notice I’ve added two extra parameters for the colorpicker element – “id” and “previewid“. These were needed to ensure that each of the colorpicker items were unique and could be targeted directly. Here’s a preview of the new colorpicker in action:

Activating the new elements in the templateDetails.xml

One last thing to mention on the topic of custom elements, is that in order for your new elements to work, you need to include a reference in your templateDetails.xml, essentially letting Joomla know you have included them. Near the top of the file (i have mine set below the languages block), add the following snippet:

<fields addformpath="/templates/witblits/admin/elements">
   <field type="colorpicker" name="Color Picker Param" />
   <field type="loader" name="CSS and JS Loader Param" />
</fields>

The Joomla 1.5 version of this code would look something along the lines of:

<params addpath="/templates/witblits/admin/elements">
   <param type="colorpicker" name="Color Picker Param" />
   <param type="loader" name="CSS and JS Loader Param" />
</params>

Note: In the case of Witblits, I decided to keep all the admin specific files in a sub folder, to keep things nice and tidy, so the example above reflects the location of the elements. This would vary depending on where you decide to keep yours.

---

4.) Making it easy for your users to upgrade

This one’s been around since Joomla 1.5 (possibly even earlier), but its still really useful to know.

At the top your templateDetails.xml, where you have: <install version="1.6" type="template"> Append method=”upgrade” to your install tag, like this: <install version="1.6" type="template" method="upgrade"> This will then let your users install an updated version of the template, without the need to uninstall the previous version first. We’ve been doing this in Morph for a while and it really makes it easy for us to roll out hotfix updates, without disrupting the flow of traffic on a users site. Normally in order to upgrade your template, the user would need to set another template as the default before they would be able to uninstall, then reinstall. The upgrade method means this is not necessary.

---

5.) Shorthand versions of templates parameters

In Witblits, I’ve included a functions file, where I define all my parameters, functions and the other inner workings of the template. I guess “functions” isn’t the best choice of a name, as it serves a number of different purposes, but for now i’ll live with it until I think of something better suited.

For the parameters, because I reuse many of them throughout the template, I decided to create shortcut parameters for each, allowing me to reduce the code (and readability) of the parameters through out the index.php. Some examples of these are:

$grid_columns		= $this->params->get('grid_columns');
$sidebar_columns	= $this->params->get('sidebar_width_' . $grid_columns);
$content_columns	= $grid_columns - $sidebar_columns;
$logo_type		= $this->params->get('logo_type');
$logo_text		= $this->params->get('logo_text');
$tagline		= $this->params->get('tagline');
$logo_image		= $this->params->get('logo_image');

This means that, instead this: <?php if($this->params->get('block_wrap', 1)) : ?> I can use this shorter version: <?php if($block_wrap == 1) : ?> I guess it comes down to preference, but for me personally, I find it much easier to scan through the templates index logic with the shorter variables rather than the full version.

---

6.) Updated error codes in error.php

If your template uses a custom error.php (located in the root of your template), you’ll need to update the error codes for them to work in Joomla 1.6.

This is taken directly for the “Upgrading your Joomla 1.5 template to Joomla 1.6” tutorial on the Joomla Documentation site.

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

---

7.) Handling HTML Overrides in Joomla 1.6

I had done extensive html overrides in our Joomla template framework, Morph, and for the 1.5 version of Witblits these are still being used. This was necessary to ensure that the frontend code was clean and had the necessary hooks for styling.

In the 1.6 version however, Joomla’s frontend code is much cleaner and semantic. For this reason I decided to delete the existing html overrides and will create new overrides as they are needed.

---

Click here to download the example elements

---

That’s all for this round. If you have any other good tips for upgrading templates to Joomla 1.6 or just Joomla 1.6 templating tips in general, please share them in the comments below. :)

---

Related blog posts:

Tags: howto, joomla 1.6, templates, upgrading