templateDetails.xml Overview

Table of Contents

templateDetails.xml Overview

Essential Elements
The files element
positions element
languages element
media element

This reference guide provides an overview of the templateDetails.xml file.

The templateDetails.xml file provides information on the template’s options and properties. It is placed in the top-level directory of a template installation package.

Once a template is installed, the file is located at site_root/templates/yourtemplate/templateDetails.xml

Info:

Upgrade method
Template’s name, author information, and description
File structure of all template files
Module positions
Language files

The information is provided in xml element/attributes.

Essential Elements

The templateDetails.xml file need the following information, at minimum.templateDetails.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="template" client="site" method="upgrade">
	<name>templatename</name>
	<version>1.0</version>
	<creationDate>Whenever</creationDate>
	<author>Author Name</author>
	<authorEmail>[email protected]</authorEmail>
	<copyright>(C) Year Company</copyright>
	<description>TPL_YOURTEMPLATES_XML_DESCRIPTION</description>
	<inheritable>1</inheritable>
	<files>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<filename>error.php</filename>
		<folder>a folder tag for every folder in the package</folder>
	</files>
	<positions>
		<position>module-position1</position>
		<position>module-position2</position>
	</positions>
	<languages folder="language">
		<language tag="en-GB">en-GB/tpl_yourtemplate.ini</language>
		<language tag="en-GB">en-GB/tpl_yourtemplate.sys.ini</language>
	</languages>
</extension>Code language: HTML, XML (xml)

extension element

<extension type="template" client="site" method="upgrade">Code language: HTML, XML (xml)

The extension element informs Joomla what type of extension this is (a template). The client is “site” meaning it’s a frontend template. The method attribute set to upgrade means Joomla processes the package as an upgrade – it overwrites all existing template files when the package is installed.

All other elements are contained within the extension element.

name element

<name>templatename</name>Code language: HTML, XML (xml)

The name element contains information about the template’s name. It should be the short/alias name for your template, matching the name you use internally for the template’s folder name.

For example, if your template is named “My Template” and you placed it in site_root/templates/mytemplate, you would put the text “mytemplate” in this element.

version & creation date elements

<version>1.0</version>
<creationDate>Whenever</creationDate>Code language: HTML, XML (xml)

Simply the version and creation date of your template. Update using whatever numbering conventions you’d like when new versions are released.

author info elements

<author>Author Name</author>
<authorEmail>[email protected]</authorEmail>Code language: HTML, XML (xml)

The name of the template’s author, or company, and a contact email. Anyone who installs your template will be able to see the information provided here. Maybe don’t use your personal email.

copyright element

<copyright>(C) Year Company</copyright>Code language: HTML, XML (xml)

Template copyright information

description element

<description>TPL_YOURTEMPLATES_XML_DESCRIPTION</description>Code language: HTML, XML (xml)

A full description of your template, displayed in the template’s information and when the template is installed.

This is a language constant. So it will load the text from your template’s language .ini files.

It’s suggested that you use language files for information like this, that should be translatable. Additionally, you can add HTML to the text of the language file, if you want. You cannot add HTML directly to the xml file. So if you want to format your template’s description, the language ini file is the better option.

If you wanted to, you could just put a short plain text description in here, without using the language file. It will just display the text you enter.

<description>This is a really cool template I made!</description>Code language: HTML, XML (xml)

inheritable element

<inheritable>1</inheritable>Code language: HTML, XML (xml)

This element is optional, you may omit it if you do not want your template to be inheritable. If inheritable, it means your template will support child-templates. Users will be able to create child templates and modify them in the backend.

The files element

The files element contains the files that are in the template’s top level directory under site_root/templates/yourtemplate

You must define every file and folder you intend on placing in this directory using the folder and filename elements. If you omit any files, they will not be copied when the template package is installed. If you have a file listed here that’s NOT in the package, you will encounter an error when the template is installed.

Here’s a sample of what standard files/folders can be found in a template. Note that you can choose to store the css, images, and js files in the template directory itself or under a separate folder in Joomla’s media directory. In this example, these folders/files are in the template directory, not the Joomla media folder.

<files>
    <filename>index.php</filename>
    <filename>templateDetails.xml</filename>
    <filename>template_preview.png</filename>
    <filename>template_thumbnail.png</filename>
    <filename>error.php</filename>
    <folder>css</folder>
    <folder>html</folder>
    <folder>images</folder>
    <folder>js</folder>
</files>Code language: HTML, XML (xml)

positions element

<positions>
	<position>module-position1</position>
	<position>module-position2</position>
</positions>Code language: HTML, XML (xml)

This is where you define the template’s module positions. The correct naming is lower case with no spaces, or hyphens.

You may define whatever module positions you’d like. At minimum, I’d suggest the following positions to start: menu, search, content-top, content-bottom, sidebar, header, footer

languages element

<languages folder="language">
	<language tag="en-GB">en-GB/tpl_yourtemplate.ini</language>
	<language tag="en-GB">en-GB/tpl_yourtemplate.sys.ini</language>
</languages>Code language: HTML, XML (xml)

The languages element specifies where the language files go. The tag is the language tag. The folder attribute defines the source folder from the template package root.

The files specified here will be moved to the language folder under Joomla’s site root.

media element

<media destination="templates/site/mybasictemplate" folder="media">
	<folder>js</folder>
	<folder>css</folder>
	<folder>scss</folder>
	<folder>images</folder>
</media>Code language: HTML, XML (xml)

The media element is optional. If you’d like to keep your template’s media files (js, css, images, etc.) under Joomla’s media folder at site_root/media/templates/site/yourtemplate instead of site_root/templates/yourtemplate you can use this element.

The folders specified here will be copied to the template’s folder under the media directory. They must be placed under a folder in the template package root. In this example, it’s the media folder: folder="media">

If you choose to use this, you should omit the folders from the files element.