The Joomla! Community Portal ™

Joomla 1.6 beta versions are out!

I, along with the rest of the Joomla! developer community, have been downloading and installing the new release and playing around with all the goodies.

The community is gearing up and squashing all those little annoying bugs and working on the help screens (Note: Documentation is extremely important! I was on the doc team for the 1.5 release and it's very rewarding - Get involved!).

Now that Joomla 1.6 Beta has arrived, it's time to take a look under the hood of the new Template Manager and examine the new features it has to offer.

I figured the best way to look at the differences between Joomla 1.6 Beta and Joomla 1.5 would be to compare those differences for you. So, let's get started!

[Template Manager] Joomla 1.5 vs Joomla 1.6 Beta

Joomla 1.5 Template Admin

Joomla 1.6 Beta Template Admin

So the biggest differences you'll see here is that Joomla 1.5 gives you two sub options: Site Templates and Admin Templates. Joomla 1.6 Beta is drastically different. Instead of site templates an admin templates, instead you'll find Styles, and Templates. This highlights a huge functional change in the way templates will operate in Joomla 1.6 in terms of customization. Joomla 1.6 handles front end vs backend handling by adding a location parameter.

Back In Joomla 1.5, professional template providers would provide some advanced parameter sets within the Template's configuration screen to handle some basic customization needs. Several template providers also began construction on the concept of Template Frameworks to perform some advanced customization for templates.

Now introduce Joomla 1.6's template handling features: Templates, and styles.

Joomla 1.6 Beta Template Manager - Styles & Templates

Joomla 1.6 Beta Template Styles Edit Screen

So what are styles and templates in Joomla 1.6 Beta? I asked myself this question when I first loaded the Joomla 1.6 Beta and took a peak through the administration panel. The conclusion I came to was that Joomla 1.6 is still strongly template based, but an added level of control has been added by allowing for "subset" templates: Styles.

Joomla Styles - what does it mean? A Joomla style is a set of parameters for a Joomla template. These styles can be duplicated, independent, and assigned to templates. The bottom line here is that a template style is the Joomla template's parameters with the ability to have different values of those parameters as needed.

What you need to know: Joomla 1.6 will allow designers to create a single template with multiple styles that provide for different sets of parameters that can be directed at users based on the current menu selection, or the user's user access rights.

Joomla 1.6 Template File System Structure:

Joomla templates have always had a particular structure and required files. Joomla 1.5's structure is identical to Joomla 1.6's, let's take a look at what files you'll have to have and what's in them:

Template Path:

<!--
**** <joomlaroot>/templates/<templatename>/
-->

<!-- All Files are in the Template Folder -->

index.php
index.html
templateDetails.xml
template_thumbnail.png
css/template.css
images/
html/ <!-- optional! -->

Joomla 1.5 vs Joomla 1.6 Beta [templateDetails.xml]

So one thing that has changed with each release of Joomla is the XML file. The XML file is the glue that holds all installable packages for Joomla! extensions together. When it comes to Joomla templates, that file must be named templateDetails.xml. XML is a wonderful language, and the reason is because XML is a language "generator". Meaning, each element in the XML is able to be created and used for a specific application. What this means in the grand scheme of website development is XML files are incredibly diverse and useful. The Joomla project utilizes this feature of XML in all of it's extension install packages.

Let's examine the differences in a Joomla 1.5 templateDetails.xml file and a Joomla 1.6 Beta templateDetails.xml file:

templateDetails.xml:

In Joomla 1.5 there are about 5 basic XML elements that were used:

Joomla 1.5 Template XML Introduction:

<?xml version="1.0" encoding="iso-8859-1"?>
<install version="1.5" type="template">
 <nameJoomla 1.5 Template XML Example</name>
 <version>1.0</version>
 <creationDate>05/29/10</creationDate>
 <author>Chad Windnagle</author>
 <copyright>s-go Consulting LLC</copyright>
 <authorEmail>author@email.com</authorEmail>
 <authorUrl>http://www.s-go.net</authorUrl>
 <license>GNU GPL</license>
 <description>This is an XML example from s-go.net</description>

The above is an example of the elements found in the first part of a Joomla 1.5 template XML. It contains detailed information about the template. Which version of Joomla it's for, who the author is, how to contact that author, and the license information. Let's look at the first elements you'll find in a Joomla 1.6 Template's XML file.

<?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">
<install version="1.6" type="template">
 <name>Joomla 1.6 Template Name</name>
 <creationDate>05/29/10</creationDate>
 <author>Chad Windnagle</author>
 <authorEmail>author@email.com</authorEmail>
 <authorUrl>http://www.s-go.net</authorUrl>
 <copyright>s-go Consulting LLC</copyright>
 <license>GNU General GPL</license>
 <version>1.0</version>
 <description>My Joomla 1.6 Beta template xml description</description>

So the only real difference in this file is the use of a DTD. DTD stands for DocTypeDefinition and it's basically a way to check the XML file's content to make sure that it matches the structure needed to be used by the application. Joomla has not used DTD's prior to Joomla 1.6 Beta. Another minor diffenence you'll note is the version parameter in the install element has the value of 1.6 instead of 1.5. This clearly denotes that it is a 1.6 template, instead of a 1.5 or 1.0 template.

The next section of the XML file is the area that defines what files and folders come with a template. This is unchanged in from Joomla 1.5 to Joomla 1.6 Beta:

<files>
<filename>index.php</filename>
<filename>index.html</filename>
<filename>favicon.ico</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
<folder>css</folder>
<folder>images</folder>
</files>

This details all of the files I listed above as being necessary for a working Joomla! template install. There was a time when the XML file required you to list not only every folder but also every file in each folder. In a Joomla! 1.5.X release a new feature was added to the template installer that allowed you to just list the files in the root directory, and then use the <folder> element to create and find all the files in the sub directories. This will save every template designer in the world tons and tons of time compiling complex XML files.

The next part of this XML is module position definitions:

<positions>
<position>positionName</position>
</positions>

Here is the area you want to define all your module positions for your template. Add as many as you need, the position names can't have spaces, but they can be anything you want.

There ae some advanced things in the XML file that I won't cover, but the XML will be useful when you get into trying to build out parameters for your template's back end screens as well.

Let's look at the rest of the template's files. We already know what the templateDetails.xml file is - let's take a look at the rest of these files and find out what they do!

Index.php

The template index.php file is like a compiler file for your entire site. This file is much like a file you would find on a traditional HTML site - it has everything. It calls stylesheets, creates div positions, loads javascript, has if statements etc... This is the meat of your template.

Starting off in the index.php file for Joomla 1.6 Beta you should find this line straight away:

<?php defined( '_JEXEC' ) or die( 'Restricted access' ); ?>

This is something that you should find in every PHP file in your Joomla! site. This is a PHP statement that causes the file to not load if the server tries to send the file to the browser. This is highly important because it is a large security risk to not have this line as anyone can see the underlying code. All PHP files should start out with this line.

The next section of the file that you are going to need is the head information.

<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="/templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="/templates/system/css/general.css" type="text/css" />
<link rel="stylesheet" href="/templates/*yourTemplateName*/css/template.css"
    type="text/css" />
</head>

So opening is the head tag, rather common in all template files. Next we have a jdoc:include - this is a Joomla! framework call. This will load in Joomla! related header information. This should be included in all Joomla! templates you build,

Next are two CSS files from the System directory - these are stylesheets that style things like error pages, messages etc...Most template designers call these files because you never know what kind of error your site users might run into - Joomla! developers have covered you design-wise with these stylesheets so your error messages will at least look pretty.

The last stylesheet is the one you want to worry about - this is the call to your template's stylesheet. You can of course put as many stylesheets in here as you need. This will contain all the class and ID definitions for your template - as well as any additional styling you for your site. Again, you can put as my stylesheets in your head area as you need too to get your design looking as spiffy as possible.

After this the template is going to start taking some form - starting off with a body tag, you'll begin to be able to place in divs to control your site's layout. That's rather common so I'm not going to cover it. But what i will cover is the next line of PHP you'll want to finish building your template:

<jdoc:include type="modules" name="positionName" />

This line calls in a module position. The name value is the one you want to worry about - this is what you will put as the position in the module manager in when editing module's in the Joomla 1.6 Beta back end. This name also will connect with the module positions you listed in your XML file (see how it all comes together?).  But you've seen that fancy thing where module positions and colums will load and be called at different times. How is that done? A few more lines of PHP will take care of that for you.

<?php if ($this->countModules('positionName')) ?>
<jdoc:include type="modules" name="positionName" />
<?php endif; ?>

So now you can start getting really fancy. You can put div classes and IDs inside of these if statements. Those will only load when the module is loading as well. So that's the secret of how those template builders get those elegant columns come and go as they please.

The next two Joomla! framework calls you will find quite necessary:

<jdoc:include type="message" />
<jdoc:include type="component" />

The message type will load any Joomla error messages into your site. Thtis would be like failed logins, new registration notices, etc... Finally, no template is complete without the actual content! The component type loads all site content, as well as all other installed components.

And that brings us to the end of the index.php file.

Index.html

The index html file is literally a dummy file. it contains next to nothing. The only purpose of this file is to prevent hackers from accessing the virtual directory of your template directory which poses a security risk. So just include a blank index.html file in every single directory to be safe!

Favicon.ico

This is an ico file which is - you guessed it, your site's favicon. That's that little 16x16 image that loads in your browser's address bar and on your bookmarks. Create a custom one to really personalize your site.

Template_thumbnail.png

That little image you get when you mouse over template's in the Joomla 1.6 template manager - this is it. It has to be named template_thumbnail.png and in the root directory of your template folder.

Out of the root

Alright so we made it out of the root of a Joomla! 1.6 template package. There are two other directories that must be included in a Joomla! 1.6 template install package.

css/template.css

Joomla has extensive CSS styling - all things such as category titles to article titles to readmore links etc..are defined here in this file. I haven't found a great resource that documents all of the Joomla 1.6 beta css classes and IDs yet, so for now you might want to check out Firebug to learn what they in the Joomla 1.6 html output.

Along with Joomla! element styling, the template css file is also the file you will define all the divs you wrote into your index.php file.

Now - you do not have to store all of this CSS in this one file. In fact it's kind of nice to separate things out. But for the sake of simplicity I've described it as all being in one file.

images

The final directory you must have with a Joomla! 1.6 Template package for the installer to run correctly is the images directory. This images directory might not even be used, but chances are if you have any images in your CSS file they'll be in here.

Optional Template Parameters

There are a few other things you can do with your templating to make it more advanced. While I won't cover these optional things totally in this blog post, I will mention them so interested persons can investigate more thoroughly.

XML Elements - Parameters

If you've seen in the professional templates settings that you can change such as font sizers, template widths, colors, etc...This is all done with a new element in your XML file and a file called params.ini. you will create a params.ini file with your default values. Those values will corrospond to elements in your XML that are named like this:

<config>
<fields name="params">
<fieldset name="basic">
<field name="fieldName" type="list" default="defaultValue" label="Your Label"
    description="Your Description">
<option value="aValue">Value Name</option>
<option value="anotherValue">Another Value Name</option>
</field>
</config>

Template Overrides

No blog about Joomla! templates would be complete unless Template Overrides was mentioned and explained.

Template Overrides is a feature that was added in Joomla 1.5 that allowed you to override the HTML output of a component or module as long as it correctly followed the MVC templating structure. This was done by creating a directory in your template's root called HTML you could then copy the component or module's directory into the HTML directory. Modify the files to fulfill your needs and that HTML would be used in place of the components installed HTML.

What does this do? This feature gives template desginers complete control over the HTML output of the code from Joomla! This allows you to take some of the components in Joomla 1.5 that stil use table based outputs and make them entirely div placed. You can "hack" core component / module code without causing security risks when updates come along. You can apply changes as needed to allow you to fully manipulate the code without the fear of losing your changes when an update for Joomla! or whatever extension you've overrode in this method being lost.

In short, template overrides are extremely powerful and one of my favorite Joomla 1.5 features.

Read more about template overrides here.