Joomla! today

Build your professional website using Joomla! 1.5 – Part 2

(Creating your own custom Templates)

Scope:

This article is part 2 of the series of articles on Joomla!. In part 1, we learnt the basics of Joomla! and walked through the steps to create a professional website using Joomla! This article provides the overview of Joomla! template, its structure & styles and provides a step-by-step approach to creating your own custom template and publishing your website content using the new template.

Though, the article uses HTML, CSS and other W3C standards discussing their detail is out of this article scope.

Target audience:

A Joomla! enthusiast who learnt the basics from part 1 and wants to do more with Joomla!
People who know the basics of Joomla! and want to create their own Template

By-line:

Author is a freelance consultant and trainer with empower consultancy & services Pvt. Ltd. Support for Joomla! articles, including this one, can be found at http://joomlatoday.blogspot.com/. You can also send your queries directly to him at ajit.kumar@empowerconsultancy.in

What is a Joomla! template

Joomla! provides the strong support for templates which allows the site administrator to change the content presentation instantaneously by choosing a different template. Joomla! template is a collection of files which control the content presentation. It provides the foundation to view the content of the website.

Why custom template?

There are various reasons why one would like to develop a new custom template. Some of them are:

· Technical reasons such as – loading time, conformance to W3C standards, etc.
Corporate identity
People are creative and there is no end to it
Learning the HOW-TOs

A look at the default Joomla! template

All the Joomla! site templates reside in the templates folder under the Joomla! installed folder. Every template has a directory matching with the template name. E.g. in the default Joomla! installation you will see two folders beez and rhuk_milkyway. Default Joomla! installation uses rhuk_milkyway template.

Each of the template directories may have the following directories:

· css – Contains all the CSS files used by the template.

· html – Contains the template files which are used to override the core output of the Joomla! system. This is an advanced topic and is currently excluded from this article for simplicity sake

· images – contains all the image files (e.g. logo, border, button images, etc.) used by the template

· javascript – Contains all the JavaScript code used by the template.

Following are the some of the important files related to a template, which acts like a foundation for most of the templates, if not all:

templateDetails.xml – Contains the meta-data about the template. This file must exist for a template. The file is used by the Joomla! Administrator interface for installation and maintenance of the template. The file contains the detail about the files which constitute the template, the author information, and the parameters which can be passed to the template through the Joomla! Administrator interface. This file is usually stored in the template root folder, which will be <xampp installed folder>/htdocs/<your site folder>/templates/<template name>.
index.php – This file contains the main logic of the template, including displaying components, modules, and articles. It also contains the client-side code, including CSS and JavaScripts. This file must exist for a template and is usually stored in the template root folder.
template_thumbnail.png – This is the small screen-shot of the template. Usually, it is of size 200 X 150 pixels. As shown in Figure 1, this is used by the Joomla! Administrator Template Manager interface to display the thumbnail when you place the mouse pointer on the template name. This is an optional file. After you have tested your template you can take a screenshot of it and create this file using your favourite image processing tools, like, GIMP. If created, this file is usually stored in the template root folder.

Figure 1: Template thumbnail

params.ini – This file contains the list of parameters the template supports. Each line contains a parameter name-value pair. This is an optional file. If created, this file is usually stored in the template root folder.

templateDetails.xml and the index.php files are the two important files which is created for every Joomla! template. It is worth going into the detail of these two files as we will also have to write them for our new template. We will break the complete file into related code chunks and see what it does.

templateDetails.xml

As discussed earlier, this file contains the meta-data about a template. It is used by the Joomla! Administrator interface. So, let us take a look at this file’s content and see what it does and understand what our template’s templateDetails.xml file should have.

---------------------------- CODE ------------------------------------

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://dev.joomla.org/xml/1.5/template-install.dtd">

---------------------------- CODE ------------------------------------

As templateDetails.xml is an XML file, like any other XML file, it must contain the header information with the DOCTYPE information. It also contains the DTD (Document Type Definition) URL based on which this XML file is written.

---------------------------- CODE ------------------------------------

---------------------------- CODE ------------------------------------

Joomla! Administrator interface allows the installation of components, modules, plug-ins, and templates using the same interface. Hence, it would require a way to differentiate between them. This entry tells the installer that it is a template and it is for 1.5 version of Joomla!.

---------------------------- CODE ------------------------------------

<name>rhuk_milkyway</name>

<author>Andy Miller</author>

<authorEmail>rhuk@rockettheme.com.com</authorEmail>

<authorUrl>http://www.rockettheme.com</authorUrl>

<description>TPL_RHUK_MILKYWAY</description>

---------------------------- CODE ------------------------------------

This contains the information about the template, like, author information, licence, template name and description, etc. Once the template is installed successfully through Joomla! Administrator interface, some of this information appears on the Administrator interface.

---------------------------- CODE ------------------------------------

<files>

<filename>index.php</filename>

<filename>templateDetails.xml</filename>

<filename>template_thumbnail.png</filename>

<filename>params.ini</filename>

<filename>images/arrow.png</filename>

<filename>images/indent1.png</filename>

........

</files>

---------------------------- CODE ------------------------------------

Every template is a group of files, like, image files, CSS, JavaScripts, etc. All these files are listed within the <files> tag. This gives template developer the flexibility to store the template files in any folder structure and use any file name.

---------------------------- CODE ------------------------------------

<position>breadcrumb</position>

<position>right</position>

<position>footer</position>

<position>debug</position>

<position>syndicate</position>

</positions>

---------------------------- CODE ------------------------------------

A template divides a page into smaller areas and each of them is allocated a position on the page. All the positions supported by a template are listed under <positions> tag. A new template may choose to support all the positions or a subset of them.

---------------------------- CODE ------------------------------------

<option value="green">Green</option>

<option value="orange">Orange</option>

<option value="black">Black</option>

<option value="white">White</option>

</param>

<param ......

...........

</param>

</params>

---------------------------- CODE ------------------------------------

A template’s functionality can be driven by the configuration of its parameter values. A template, which supports parameters, will list out all the parameters and its possible values under the <param> tag. Once specified, these parameters will appear on the Joomla! Administrator interface when you edit template information as shown in Figure 2. The Administrator can change the behaviour of the template by changing the parameter values.

Figure 2: Template Parameters

You must be thinking is the list of tags mentioned above is complete! Where can I find the complete list of tags and their attributes, which can be specified during the creation of my custom template? The answer lies in the second line in templateDetails.xml file. This line contains the URL of the DTD file (http://dev.joomla.org/xml/1.5/template-install.dtd), which contains the complete detail.

index.php

Anyone who develops a new template will have to write this file. So, the obvious question is - Why? Answer is, so that you know what shall be the structure of this file, what is it expected to do, and how does it ties the knot between the presentation and the content in the database.

Let us take a look at the code.

---------------------------- CODE ------------------------------------

defined( '_JEXEC' ) or die( 'Restricted access' );

---------------------------- CODE ------------------------------------

This line of code ensures that this script is not being accessed directly. This is required for security purpose.

---------------------------- CODE ------------------------------------

<!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; ?>" >

---------------------------- CODE ------------------------------------

This DOCTYPE tells the browser how to interpret the page. And, the xml:lang is set after reading the language setting from Joomla! site global settings.

---------------------------- CODE ------------------------------------

---------------------------- CODE ------------------------------------

Includes all the required CSS files. $this->params->get('colorVariation') reads the value set for ‘colorVariation’ template parameter.

---------------------------- CODE ------------------------------------

<!--[if lte IE 6]>

<![endif]-->

---------------------------- CODE ------------------------------------

Includes the CSS to work around with bugs or deviations from W3C standard in IE 6.0 or older

---------------------------- CODE ------------------------------------

<?php if($this->direction == 'rtl') : ?>

<?php endif; ?>

---------------------------- CODE ------------------------------------

Includes the appropriate template if the direction is set to right-to-left

---------------------------- CODE ------------------------------------

<body id="page_bg" class="color_<?php echo $this->params->get('colorVariation'); ?> bg_<?php echo $this->params->get('backgroundVariation'); ?> width_<?php echo $this->params->get('widthStyle'); ?>">

......

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

......

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

......

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

......

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

......

<jdoc:include type="modules" name="left" style="rounded" />

......

<jdoc:include type="modules" name="user1" style="xhtml" />

......

<jdoc:include type="modules" name="user2" style="xhtml" />

......

<jdoc:include type="component" />

......

<jdoc:include type="modules" name="footer" style="xhtml"/>

......

<jdoc:include type="modules" name="right" style="xhtml"/>

......

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

......

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

---------------------------- CODE ------------------------------------

This is the code which gets the content from the various modules and component and displays it on the page.

Keeping the usability, accessibility, and search engine optimisation in mind, a template loads the content in a logic order. Following is the order in which the various articles, components, and modules are loaded by the default Joomla! template:

logo
top modules - newsflash
user3 module – top menu
user4 module – search
pathway - breadcrumb module
left column - left modules – main menu, resources, key concepts, login form, etc.
main column

user1 module – Latest News
user2 module - Popular
footer modules – banner, copyright message
right modules – polls, advertisement, who’s online, etc.

footer

syndicate module
text – “Powered by Joomla!. valid XHTML and CSS.”

To know what modules are associated with what position, go to the Module Manager page of Joomla! Administrator interface of your web site.

Figure 3: Modules and positions

Figure 4 shows where the different modules are positioned on the Joomla! default web page.

Figure 4: Default template modules and positions

Default Joomla! template styles

The template styles are driven, mostly, by CSS. A Joomla! template can have one or more CSS files defined. It is possible to define a CSS for the site layout, a CSS for menus, a CSS for positions and so on.

Following are some of the important CSS files you may come across when you browse through the 3^rd party templates:

template.css – main template CSS file

template_rtl.css – main template CSS when the presentation direction is right-to-left
ieonly.css – styles defined to work around with Internet Explorer 6 and prior CSS bugs or deviations from standard
ie7only.css - styles defined to work around with Internet Explorer 7 CSS bugs or deviations from standard

All the Joomla! Administration pages use the CSS styles defined in the files under templates/system/css folder.

Figure 5 shows the default Joomla! page and some of the styles being used.

An easy way to figure out the style used on a page for an element can be found by installing the Web Developer add-on to the FireFox browser and enable the CSS style for the page for which you want to see the CSS styles.

Figure 5: Default template styles

Planning your custom template

Before we get into developing the new template, let us spend some time to plan out our template requirements. What exactly we want our template to present the website content? Let us say, following are my first cut of requirements:

3-column page layout
New template must display the same content as the default Joomla! template

Well, so, what action do these requirements correspond to? As, in any Joomla! template, content comes from the Joomla! database, no change in required from the content access point of view. However, to support requirement (b), the template must support the placeholders for dynamic content (modules, components) and static content (articles). Also, the new template must support the positions like top, left, right, user1, user2, user3, etc. As listed in the templateDetail.xml file of the default Joomla! template. So, to summarise, we will have to design a layout for the new template to support the above mentioned requirements.

Following is the step-by-step approach to create a new Joomla! template to address the above mentioned requirements:

Step 1: Preparing the infrastructure

Decide upon a name for your new template. E.g. I name my template bool (Born Out Of Laziness).

Create a folder by name bool under templates folder

Create following folders under bool :

You can create images folder if you plan to have your own images. I have not shown it here for simplicity sake.

Step 2: 3-column layout

When it comes to 3-column layout, we have two choices:

HTML table (<table>, <tr>, <td>)
HTML div with CSS

The selection of the approach is completely at your discretion. Both the approaches exist for various practical and technical reasons. However, the selection must be made based on the problem context. In this article I will use CSS as it allows me to separate the layout from presentation, it is faster to load in the browser, and provides better usability, accessibility, and SEO (Search Engine Optimisation). Refer to the Tableless layout HOWTO URL, mentioned in the Reference list for more detail. Discussion of HTML, CSS and other W3C standards is out of the scope of this article.

Following CSS code of our new template shows the styles for 3 columns and also for some of the component and module headings:

-------------------------------- CODE -------------------------

#left {

float:left;

width:15%;

border:1px gray;

padding: 5px;

}

#centre {

float:left;

width:60%;

border:1px gray;

padding: 5px;

}

#right {

float:left;

width:15%;

margin: 10px;

border:8px solid;

padding: 15px;

}

div.moduletable_menu h3 {

font-weight: bold;

color: #000;

background: #f23;

}

div.moduletable_text h3 {

font-weight: bold;

color: #000;

background: #f23;

}

div.moduletable h3 {

font-weight: bold;

color: #000;

background: #f23;

}

div.componentheading {

font-weight: bold;

color: #000;

background: #f99;

}

td.contentheading {

font-weight: bold;

color: #000;

background: #ff3;

}

-------------------------------- CODE -------------------------

Name this file template.css and save it under bool/css folder. It is optional to name the file template.css. You can specify any name of your choice.

Step 3: Having layout and placeholders for the dynamic and static contents

This previous step takes care of dividing the web page in 3 columns. However, we are still left out with the second requirement. To support it, we will have to write the index.php file.

Following PHP code of our new template shows the how the content is included in the template and how they are positioned:

-------------------------------- CODE -------------------------

<html>

<head>

<jdoc:include type="head" />

</head>

<body>

<ldoc:include type="message" />

<jdoc:include type="modules" name="left" style="xhtml" />

</div>

<jdoc:include type="component" />

</div>

<jdoc:include type="modules" name="right" style="xhtml" />

</div>

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

</body>

</html>

-------------------------------- CODE -------------------------

Save this index.php file under bool folder.

Step 4: Filling up the gaps

Now, that we have defined the template style sheet, it is time to put the basic building blocks to make it a Joomla! template, which can be installed through the Joomla! Administrator’s Template Manager interface. Following files needs to be created under bool folder:

templateDetails.xml
template_thumbnail.png

templateDetails.xml

Following is the code for our new template:

------------------------------- CODE --------------------------

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://dev.joomla.org/xml/1.5/template-install.dtd">

<creationDate>5 March 2008</creationDate>

<author>Ajit Kumar</author>

<authorEmail>ajit.kumar@empowerconsultancy.in</authorEmail>

<authorUrl>http://www.empowerconsultancy.in</authorUrl>

<description>This template is Born Out Of Laziness</description>

<files>

<filename>index.php</filename>

<filename>templateDetails.xml</filename>

<filename>template_thumbnail.png</filename>

<filename>css/template.css</filename>

</files>

<position>breadcrumb</position>

<position>right</position>

<position>footer</position>

<position>debug</position>

<position>syndicate</position>

</positions>

</install>

------------------------------- CODE --------------------------

Moving site content to your custom template

Now, that the template development is over, it is the time to see if it installs through the Joomla! Administrator and publish the web site content using it. Following is the step to accomplish this:

Step 1: Create a compressed zip file with all template files

Let us say our template folder looks like this:

templates/bool/templateDetails.xml

templates/bool/index.php

templates/bool/template_thumbnail.png

templates/bool/css/template.css

Go to the templates/bool directory and zip all the files and folders within it and name it, say, bool.zip

Step 2: Go to your site Joomla! Administrator interface

Step 3: Click on Extensions->Install/Uninstall

Step 4: Browse through the file system and select the bool.zip file and click on Upload File & Install button. This will install the template.

Figure 6: Template installed successfully

Step 5: Click on Templates tab to verify that a new entry has been created for our new template

Figure 7: Verify template installation

Click on Extensions->Template Manager

Figure 8: Verify template installation in Template Manager

Step 6: Click on Extensions->Template Manager. This will show our new template.

Step 7: Select the radio button next to bool template and click on Default toolbar icon on the top-right corner to make it the site default template.

Figure 9: New template marked as default

This completed the process of moving the web site to our new template.

It’s show time now. Let us see how the site looks like with our new template. Enter your website URL in the browser.

Figure 10: Site with new template

Looks okay! Now, it’s your turn to get creative with the styles. Grab a good book on CSS and transform this into a site which you have in your mind.

This brings us to the end of this article. We explored what it takes to develop a new Joomla! template and we got our hands dirty with developing a new Joomla! template. In the subsequent parts, we will discuss how to write your own Joomla! extensions, like, modules, components.

References

XAMPP Download - http://www.apachefriends.org/en/xampp.html

Joomla! 1.5 Download - http://www.joomla.org/

Web Developer - https://addons.mozilla.org/en-US/firefox/addon/60

Tableless layout HOWTO - http://www.w3.org/2002/03/csslayout-howto

W3Schools’ CSS tutorial - http://www.w3schools.com/css/

Joomla! today

Thursday, September 11, 2008

Creating Joomla! Module

Tuesday, March 18, 2008

Creating your own custom Joomla! Templates

Blog Archive

About Me