Understanding the templateDetails.xml file_Joomla! 1.5 Templates Cookbook-QQ阅读男生玄幻网

上QQ阅读APP看书，第一时间看更新

Understanding the templateDetails.xml file

The templateDetails.xml is vital for your Joomla! template to function correctly. It defines the metadata of your template. There are three fundamental things that this file tells Joomla!:

Information about the author of the template (that's you!)
The files that are used within the template
The positions that Joomla! uses to position content within the template

The templateDetails.xml file can also provide information about a theme's color variations and other parameters.

Getting ready

If your template does not already have one, create a templateDetails.xml file in your template's directory. For example, if your template was called ch2-test, this would be in the templates\ch2-test directory.

How to do it...

Before we begin, we need to define a few things in our file:

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

The first and second lines define the version of the XML that we're using for the file, and the character encoding the file needs (stuff that needn't concern us!). The third line tells Joomla! which version of it our template is compatible with (1.5 in this instance), and what it is (a template).

Author information

The first thing that is defined within the templateDetails.xml file is information about the author of the template:

<name>ch2-test</name>
<creationDate>January 2010</creationDate>
<author>Richard Carter</author>
<authorEmail>richard@peacockcarter.co.uk</authorEmail>
<authorUrl>http://www.earlgreyandbattenburg.co.uk</authorUrl>
<version>1.0.2</version>
<description>A test of the templateDetails.xml file for Chapter 2 of Joomla! 1.5 Templates Design Cookbook</description>

It allows you to define the name of the template (ch2-test), its creation date (January 2010) and the name of the author(s) of the template (Richard Carter), as well as their e-mail address, and website. After that, it defines the version of the template (1.0.2), and gives a brief description of the template, which appears when you view details of the template in the Joomla! administration panel, under Extensions | Template Manager:

Positions

Positions within Joomla! templates let you customize where you can place content in your template. These are defined within the template's templateDetails.xml file, within the positions element:

<positions>
positions element<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>
</positions>

As you can see, this template defines a number of positions for content to be placed within the template. You can see where these blocks appear in your Joomla! template by adding ?tp=1 to the end of your Joomla!-powered page's URL (see Understanding Joomla! template positions ):

From the previous screenshot, you can see, among others, the breadcrumb block towards the top-left of the screen.

Parameters

The next thing that templateDetails.xml defines is a template's parameters. As we've seen, a Joomla! template can use parameters to allow variations of its color scheme, width, and other attributes.

<params>
<param name="colorVariation" type="list" default="white" label="Color Variation" description="Color variation to use">
<option value="blue">Blue</option>
<option value="pink">Pink</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>
<param name="anotherOption" type="list" default="option1" label="Another Option" description="Another parameter option for your template">
<option value="option1">Option 1</option>
<option value="option2">Option 2</option>
</param>
</params>

Each<param> element that is defined needs to have name, type, and label attributes defined.

The name attribute uniquely identifies the parameter within the template. You should not have more than one parameter in a template with the same name.

The type attribute tells Joomla! what type of option to create. In most cases, in Joomla! template design, you will want this value to be list, although there are over 20 options available for this value. Other parameter types can be found in Joomla!'s documentation at

The label attribute is the descriptive text that appears next to the option in your Joomla! admin panel, in this case, Color Variation and Another Option:

The description attribute is not mandatory, so you can leave this field out if you want to. Though to help anyone using your template, it's recommended that you provide a brief overview of what the parameter does here. Similarly, the default value is recommended, but not required.

Parameters are optional in your template, so you don't need to have any parameters defined within your template's templateDetails.xml file.

Closing the XML file

Finally, we need to close the XML file:

</install>

That's it; our template's templateDetails.xml file is complete for now. In all, it should look similar to the following:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
<install version="1.5" type="template">
<name>ch2-test</name>
<creationDate>10/12/09</creationDate>
<author>Richard Carter</author>
<authorEmail>richard@peacockcarter.co.uk</authorEmail>
<authorUrl>http://www.earlgreyandbattenburg.co.uk</authorUrl>
<version>1.0.2</version>
<description>A test of the templateDetails.xml file for Chapter 2 of Joomla! 1.5 Templates Design Cookbook
</description>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
</files>
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
</positions>
</install>

How it works...

Joomla! relies on the templateDetails.xml file to provide it with information about the template.

There's more...

You can include a thumbnail preview of your template by adding an image called template_thumbnail.png into your template's directory. Make sure you add a reference to it in your templateDetails.xml file within the<files> element so that Joomla! knows it's there when the template is being installed!

<files>
<!-- other files defined -->
<filename>template_thumbnail.png</filename> 
</files>

When you now go into your Joomla! website's admin panel, you'll see this screenshot if you hover over the name of your template in Extensions | Template Manager: