Joomla! Documentation™

This Article Needs Your Help

The templateDetails.xml file is required for Joomla! templates. 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.

More information about Creating a Joomla! Template

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. This file is found in the template directory -> Protostar -> templateDetails.xml. The various sections of the file are explained below.

XML Format

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 with the closing tag </extension>.

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

Basic Details

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.

<extension version="3.1" type="template" client="site">
	<name>protostar</name>
	<version>1.0</version>
	<creationDate>4/30/2012</creationDate>
	<author>Kyle Ledbetter</author>
	<authorEmail>admin@joomla.org</authorEmail>
	<copyright>Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.</copyright>
	<description>TPL_PROTOSTAR_XML_DESCRIPTION</description>

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 the article.

Folder Structure

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.

	<files>
		<filename>component.php</filename>
		<filename>error.php</filename>
		<filename>favicon.ico</filename>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<filename>template_preview.png</filename>
		<filename>template_thumbnail.png</filename>
		<folder>css</folder>
		<folder>html</folder>
		<folder>images</folder>
		<folder>img</folder>
		<folder>js</folder>
		<folder>language</folder>
		<folder>less</folder>
	</files>

Module Positions

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

These are the module positions in the default Protostar template:

	<positions>
		<position>banner</position>
		<position>debug</position>
		<position>position-0</position>
		<position>position-1</position>
		<position>position-2</position>
		<position>position-3</position>
		<position>position-4</position>
		<position>position-5</position>
		<position>position-6</position>
		<position>position-7</position>
		<position>position-8</position>
		<position>position-9</position>
		<position>position-10</position>
		<position>position-11</position>
		<position>position-12</position>
		<position>position-13</position>
		<position>position-14</position>
		<position>footer</position>
	</positions>

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 other areas of Joomla! where module positions can be selected. The list 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, while this adds the position to the backend, additional development in other template files is required to render the position on the front end.

Languages

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 (system) extension is for text that will be viewed in the Administrator section.

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>
	</languages>

As mentioned earlier, language strings are used to allow a method for translating text. This method provides developers and users with a method to translate text used by templates and extensions into any language and make use of the extensive International language support that Joomla! offers. 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 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: Creating a Language Definition File

Loading extra language files

Parameters

A template may offer display options and other parameters that can be chosen by the Administrator in the Template Manager. For instance, the default Prototype 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 Prototype 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.

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

				<field name="templateBackgroundColor" class="" type="color" default="#F4F6F7"
					label="TPL_PROTOSTAR_BACKGROUND_COLOR_LABEL"
					description="TPL_PROTOSTAR_BACKGROUND_COLOR_DESC" />

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

				<field name="sitedescription"  type="text" default=""
					label="JGLOBAL_DESCRIPTION"
					description="JGLOBAL_SUBHEADING_DESC"
					filter="string" />

				<field name="googleFont"
					type="radio"
					class="btn-group btn-group-yesno"
					default="1"
					label="TPL_PROTOSTAR_FONT_LABEL"
					description="TPL_PROTOSTAR_FONT_DESC"
				>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>

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

				<field name="fluidContainer"
					type="radio"
					class="btn-group btn-group-yesno"
					default="0"
					label="TPL_PROTOSTAR_FLUID_LABEL"
					description="TPL_PROTOSTAR_FLUID_DESC"
				>
					<option value="1">TPL_PROTOSTAR_FLUID</option>
					<option value="0">TPL_PROTOSTAR_STATIC</option>
				</field>
			</fieldset>
		</fields>
	</config>

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. With this in mind, it is relatively simple to create as many additional tabs and parameters as you like and organize them as you choose.

For more information about working with Parameters, see:

Defining a parameter in templateDetails.xml

Retrieving parameter data in a template file