Understanding Joomla! templates

From Joomla! Documentation

Revision as of 08:56, 19 March 2015 by Tom Hutchison (talk | contribs) (linebreak)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Other languages:
Deutsch • ‎English • ‎Nederlands • ‎eesti • ‎español • ‎français • ‎português do Brasil • ‎български • ‎فارسی • ‎中文(台灣)‎

Typical Template Directory Structure[edit]

Joomla! CMS templates use a structure of directories and files but they can vary from template to template

  • 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:
  • 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:

Template directories[edit]

A typical template for Joomla! 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
  • language - contains additional language files used by the template

Depending on the complexity and design of the template it may also contain:

  • javascript - contains supporting JavaScript used by the template for added functionality

Example structure with files[edit]

Typical path of a template is <root>/public_html/domain-name/template/<name of your template> which will contain the following directories and files based on your template.


Template files[edit]

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

  • index.php
Provides the logic for the display and positioning of modules and components.
  • component.php
Provides the logic for the display of the printer friendly page, "E-mail this link to a friend." etc.
  • error.php
Provides a method to handle errors such as 404, page not found error.
  • favicon.ico
favicon icon file
  • template.css
Handles the presentational aspects of the template including specifications for margins, fonts, headings, image borders, list formatting, etc. The .css files may also be located in the /css directory.
  • templateDetails.xml
Holds meta-information related to the template and is used by the Installer and the Template Manager.
  • template_preview.ext - replace .ext with the extension format of the image (.jpg, .png, .gif)
Generally a 600x400 pixel image that is shown when the cursor is clicked on the thumbnail image in Template Manager:Templates, not Template Manager:Styles. This gives the Administrator a pop up modal window of the template before applying it to the Site.
  • template_thumbnail.ext - replace .ext with the extension format of the image (.jpg, .png, .gif)
Generally a 200x150 pixel thumbnail image that is shown when viewing the Template list in Template Manager:Templates, not Template Manager:Styles. This gives the Administrator a thumbnail view of the template before applying it to the Site.

The templateDetails.xml file is required for Joomla! templates and it can be found in the root template directory of any template inside the Joomla! templates directory. This XML file holds the basic meta-data that Joomla! needs in order to display and provide it as template option in the backend. It also contains a variety of other meta-data that is used to provide information about the template and the template authors and define files and folders that are used by the template. It also defines template language files, as well as parameters and settings the template will offer in the backend.

The templateDetails.xml file uses a fairly basic XML format and structure. The XML data in this file is separated into sections and specifically formatted in to render the various pieces and parameters. The XML data is read and parsed by powerful tools in the Joomla! core, then rendered to register the template and create the display seen in the Template Manager. This provides template developers a relatively simple method for creating assignments, settings and parameters for use in the template.

The implementation of templateDetails.xml will vary from template to template, it can be simple or complex depending on what features the template offers. The default Joomla! 3 Protostar template serves as an excellent example to demonstrate how this file is used. The various sections of this file are explained below.

XML Format[edit]

The top two lines of every templateDetails.xml file need to start with defining the XML format and doctype.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">

The next line is also required as it tells Joomla! that the data in this file is to be used for an extension, in this case a template. All template data is contained within this <extension> tag, and the file concludes by closing this tag </extension>.

<extension version="3.1" type="template" client="site">

Basic Details[edit]

The first section is generally where template developers include information about the template. Information such as names, dates, contact information, copyrights, version number and a basic description are common. This data is used in the Template Manager and is shown in the list of available templates and can be displayed in the template editing screens as well.

Template Basic Details as seen in Template Manager > Templates

Template Details example

Protostar XML code for basic details:

<extension version="3.1" type="template" client="site">
	<author>Kyle Ledbetter</author>
	<copyright>Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.</copyright>

You may notice that the final line of this code, the description, contains a language string and not the actual description. This string references a language file in the template where the actual description is defined and written. This is a preferred method in Joomla! for extensions that are distributed for public use to accommodate international language support, however one could simply type the description if translation is not a concern. The language files are also defined in the templateDetails.xml file, in the language section, which is covered in more detail later in this article.

Template Description seen in Protostar Editor

Template Details example

Folder Structure[edit]

All Folders related to the template installation are listed here. All files and folders located in the root of the template directory during installation need to be listed here. Any files contained inside a folder that is listed are automatically included. Each folder contains full path information starting at the template root. The Administrator's Installer uses this information when storing the files during installation.

Below is the file and folder structure from the default Protostar template. This is a fairly standard file structure for a basic Joomla! template.


File directory view of J3 Protostar

J3 protostar file structure en.jpg

Module Positions[edit]

The available Module Positions that can be used in the template are defined in this area.

These are the module positions defined in the default Protostar template:


The list of positions are contained within the <positions> tag. Each <position> tag creates a module position that is available from the position list in the module manager and in other areas of Joomla! where module positions can be selected.

The simple format of the position list means it can be easily customized. For example, to add a new module position to the list, simply add a new <position> tag inside the <positions> tag with a unique name using all lowercase letters with no spaces. Keep in mind, this only adds the position to the backend and additional development in other template files is required to render the new position on the front end.


Some templates may include language files to allow translation of static text in the template. Notice that the language folder is defined and the two language files inside are also included. Even though the language folder was defined earlier, these files need their own definitions. This method tells Joomla! where the language files that contain strings used by the template reside.

The first file holds the language file for text that will be viewed by the User. The second file, with the .sys, or system, extension is for text that will be viewed in the Administrator area.

This is the language folder and file structure from the default Protostar template:

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

Language strings are used in templates and throughout Joomla! for the purpose of utilizing the extensive international language support features in Joomla!. This method provides developers and users with a relatively simple method to translate any text that is used in templates and extension screens. Joomla! will check the language files for any language strings that are used and load the corresponding text in the language chosen by the user in place of the string. In this instance, there are only files for English (en-GB), any text translations in other languages must be provided by Users or Developers before they can be used by Joomla!.

More information about Language Files:


Protostar Advanced Parameters Screen

A template may offer display options and other parameters that can be chosen by the Administrator in the Template Manager. For instance, the default Protostar template allows the Administrator to change various colors, fonts and add a logo, these parameters are found under the Advanced tab, which is also defined and created by the XML parameters.

Template parameters are contained inside a <config> tag, which contains a <fields> tag with a name attribute of "params". Inside the <fields> tag is where the parameter groups and individual parameters are defined. The <fieldset> tag is used to create groups of parameters. Individual parameters are defined with the <field> tag.

Each <fieldset>, and each <field> parameter within a <fieldset>, require a unique name defined by the name attribute. This name defines the parameter itself and is used to pass settings to the front end files. Each parameter should also contain a label attribute and description attribute. The label text appears with the parameter in the settings screen to identify what the setting is used for and more detailed information can be included in the description.

A parameter field can be virtually any type of form input with corresponding options, this is selected by the type attribute. Any necessary options, such as radio button or select choices, are defined in <option> tags. CSS class names can be defined with the class attribute and a default parameter setting can be defined using the default attribute.

Below are the parameter definitions in the default Protostar Template. In this example, all Labels, Descriptions and Options are using language string definitions from the Language files defined in the previous section, as well as some from the Joomla! core, so they can be translated into different languages as necessary.

		<fields name="params">
			<fieldset name="advanced">
				<field name="templateColor" class="" type="color" default="#08C"
					description="TPL_PROTOSTAR_COLOR_DESC" />

				<field name="templateBackgroundColor" class="" type="color" default="#F4F6F7"

				<field name="logoFile" class="" type="media" default=""
					description="TPL_PROTOSTAR_LOGO_DESC" />
				<field name="sitetitle"  type="text" default=""
					filter="string" />

				<field name="sitedescription"  type="text" default=""
					filter="string" />

				<field name="googleFont"
					class="btn-group btn-group-yesno"
					<option value="1">JYES</option>
					<option value="0">JNO</option>

				<field name="googleFontName" class="" type="text" default="Open+Sans"
					description="TPL_PROTOSTAR_FONT_NAME_DESC" />

				<field name="fluidContainer"
					class="btn-group btn-group-yesno"
					<option value="1">TPL_PROTOSTAR_FLUID</option>
					<option value="0">TPL_PROTOSTAR_STATIC</option>

The Protostar template illustrates a few different ways that XML can be used in a template interface, but there are many more possibilities. In this example, the <fieldset name="advanced"> tag encloses all of the parameters and it uses the name attribute to create the "Advanced" tab in the interface. All that is necessary to create another tab in the interface is another <fieldset> tag with a different name attribute. With this in mind, it is relatively simple to create as many additional tabs and parameters as necessary in a template.

Additional Resources[edit]

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:

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

And the same thing done the Joomla! way:

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

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 www.example.org, the webserver delivers www.example.org/index.htm. Because Joomla! is written in PHP, index.php is the automatically served file. To further 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.