[Developer]

Tutorial:Understanding Joomla! templates


All site templates (templates that change what your website looks like) can be found in the templates directory. For example, if your template is called "mytemplate", then it would be placed in the folder "[path-to-Joomla!]/templates/mytemplate".
All administrator templates (templates that change what the administrator section of the site looks like) can be found in the administrator/templates directory. For example, if your administrator template is called "myadmintemplate", then it would be placed in the folder "[path-to-Joomla!]/administrator/templates/myadmintemplate".




Typical Template Directory Structure

It is most common for a template to have at least four files:

• index.php

Provides the logic for the display and positioning of modules and components.

• template.css

Handles the presentational aspects of the template including specifications for margins, fonts, headings, image borders, list formatting, etc.

• templateDetails.xml

Holds meta-information related to the template and used by the Installer and the Template Manager.

• template_thumbnail.ext - replace .ext with the extension format of the image (.jpg, .png, .gif)

Generally a 200x150 pixel image that is shown when the cursor is held over the template name in the Template Manager. This gives the Administrator a snapshot view of the template before applying it to the Site.
A typical template for Joomla! 1.5 will include the following directories:

• css - contains all the .css files
• html - contains template override files for core output and module chrome
• images - contains all images used by the template

Contents

[hide]

• 1 Typical Template Directory Structure
• 2 Basic Details
• 3 File Structure
• 4 Languages
• 5 Module Positions
• 6 Parameters

The templateDetails.xml file holds a variety of meta-data used by the Template Manager in installation and maintenance. It is helpful to recognize the different sections of the file. Typically, each section of data is indented to make the file more readable, but this indentation is not necessary.
Basic Details

The initial display of the Template Manager shows a list of available templates and basic details relating to the template. Each of these bits of information is gathered from the templateDetails.xml file.

<install version="1.5" type="template">
<name>rhuk_milkyway</name>
<creationDate>11/20/06</creationDate>
<author>Andy Miller</author>
<authorEmail>rhuk@rockettheme.com.com</authorEmail>
<authorUrl>http://www.rockettheme.com</authorUrl>
<copyright></copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>TPL_RHUK_MILKYWAY</description>
File Structure

All files related to the template are listed. Each filename contains full path information starting at the template root. The Administrator's Installer uses this information when storing the files during installation.
A small portion of the files listed in the rhuk_milkyway template is given below.
<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>
Languages

Some templates may include language files to allow translation of static text in the template. Notice that two language files are shown below. The first holds the language file for text that will be viewed by the User. The second, placed within <administration> tags, is for text that will be viewed by the Administrator.
<languages>
<language tag="en-GB">en-GB.tpl_beez.ini</language>
</languages>
<administration>
<languages folder="admin">
<language tag="en-GB">en-GB.tpl_beez.ini</language>
</languages>
</administration>
Module Positions

The available Module Positions that can be used in the template are defined.
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>footer</position>
<position>debug</position>
<position>syndicate</position>
</positions>
Parameters

A template may offer display options that can be chosen by the Administrator in the Template Manager. For instance, the rhuk_milkyway template allows the Administrator to change the border colors, change the background color, and define the display width.

An example of adding a parameter and its values is shown below.

   <params>
	<param name="colorVariation" type="list" default="white" label="Color Variation" description="Color variation to use">
	    <option value="blue">Blue</option>
	    <option value="red">Red</option>
	    <option value="green">Green</option>
	    <option value="orange">Orange</option>
	    <option value="black">Black</option>
	    <option value="white">White</option>
	</param>
    </params>

For more information about working with Parameters, see:
Defining a parameter in templateDetails.xml Retrieving parameter data in a template file

The index.php file is the skeleton of the website. Every page that Joomla! delivers is "index.php" fleshed out with a selection of content inserted from the database.
The index.php file for a template contains a mixture of code that will be delivered as it is, and php code, which will be modified before it is delivered. The code will be familiar to anyone who has designed a simple html webpage: there are 2 main sections - the <head> and <body>. Where index.php differs is the use of php code to insert information selected from a database.
Here is an example:
A tradition HTML head section:

<head>
<title>My Example Webpage</title>
<meta name="title" content="example" />
<link rel="stylesheet" href="www.example.com/css/css.css" type="text/css" />
</head>

And the same thing done the Joomla! way:

<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>templates/mytemplate/css/css.css" type="text/css" />
</head>

[ht
So, instead of these header parts being defined on the index.php file, the header parts are looked up from the database by bits of php code. The clever part is that both these scripts will deliver the same code to a user. If you look at the code of a joomla website, all the <?php blah /> will have been replaced by regular html code.
Good template design
Index.php should be as bare-boned as you can make it because it will be re-sent every time a new page is loaded. Elements such as styling should be delivered in css files that are saved in the users cache. The tutorials here will go through the technical aspects of creating your index.php.
Why index.php?
Index.htm has historically been the name given to the home page of a website. Thus when a user navigates to Example Web Page, the webserver delivers www.example.org/index.htm. Because Joomla! is written in PHP, index.php is the automatically served file. To futher complicate things, when a user navigates to the joomla website, the index.php of the root directory redirects to the index.php of the current default template.