Joomla! Documentation - User contributions [en]

Amending the templateDetails.xml file

2009-11-05T20:00:25Z

Felham: The field is translated. Put the correct fields in the admin template language file.

To ensure that your template is fully internationalised you must make sure that certain XML elements are translated and that the language definition files are listed in the ''templateDetails.xml'' file.

==== Translating templateDetails.xml ====
A couple of the elements in the ''templateDetails.xml'' file are used in the Template Manager and are themselves translatable. These should always be translated.

{| class="wikitable"
| name
| Name of the template. For example, Beez

|-
| description
| Description of the template.

|}
These fields are also shown to the user during template installation.

==== Adding language definition files to templateDetails.xml ====
All language files must be declared in the ''templateDetails.xml'' file. This is done by adding two ''<nowiki><language></nowiki>'' elements for each language to be included with the template; one for the front-end strings; the other for the administrator back-end strings. For example, the two British English language files and the two German language files for the Beez template are declared as follows
<source lang="xml">
<?xml version=”1.0” encoding=”utf-8” ?>
<install version=”1.5” type=”template”>

.........

<languages>
<language tag=”en-GB”>en-GB.tpl_beez.ini</language>
<language tag=”de-DE”>de-DE.tpl_beez.ini</language>
</languages>

.........

<administration>
<languages folder=”admin”>
<language tag=”en-GB”>en-GB.tpl_beez.ini</language>
<language tag=”de-DE”>de-DE.tpl_beez.ini</language>
</languages>
</administration>

</install>
</source>

Note that in the administration ''<nowiki><languages></nowiki>'' tag the ''folder'' attribute is used. This is because the language files for the front-end and back-end have the same file names and so cannot exist in the same directory within the template package file. In this example, the administration language files have been placed in a sub-directory called ''admin'' to separate them from the front-end language files.
<noinclude>[[Category:Templates]][[Category:Languages]]</noinclude>

Packaging a extension

2009-05-04T11:32:43Z

Felham:

A directory with several loose files is not a convenient package for distribution. So the final step is to make a ''package''. This is a compressed archive containing the directory structure and all the files. The package can be in '''ZIP''' format (with a <tt>.zip</tt> extension), in '''TAR-gzip''' format (with a <tt>.tar.gz</tt> extension), or in '''TAR-bz2''' format (with a <tt>.tar.bz2</tt> extension).

If your template is in a directory <tt>mytemplate/</tt> then to make the package you can connect to that directory and use commands like:
* <tt>tar cvvzf ../mytemplate.tar.gz *</tt>
* <tt>zip -a -r ..\mytemplate.zip *.*</tt>

=== Note to Mac OS X users ===
Note to template developers using Mac OS X systems: the Finder's "compress" menu item produces a usable ZIP format package, but with one catch. It stores the files in [[AppleDouble]] format, adding extra files with names beginning with "<tt>._</tt>". Thus it adds a file named "<tt>._templateDetails.xml</tt>, which Joomla 1.5.x can sometimes misinterpret. The symptom is an error message, "XML Parsing Error at 1:1. Error 4: Empty document". The workaround is to compress from the command line, and set a shell environment variable "COPYFILE_DISABLE" to "true" before using "compress" or "tar". See the [[AppleDouble]] article for more information.

File structure for packaging

2009-05-04T11:32:23Z

Felham:

The most basic files, such as index.php, component.php, templateDetails.xml, template_thumbnail.png, favicon.ico, params.ini should be placed directly in your template folder. The most common is to place images, CSS files, JavaScript files etc in separate folders. Joomla override files must be placed in folders in the folder "html".

When making the template folder, your language files should be copied to your template folder. The ones for the front end site should be placed directly in the template folder. If you have language files for the back end, these should be placed in a folder, named for instance "admin". All the language files will be copied automatically to the right folders if stated correctly in the templateDetails.xml.

Creating a thumbnail preview image

2009-05-04T11:31:40Z

Felham:

A thumbnail preview image should be 206 pixels in width and 150 pixels high. Recommended file format is png.

You can take a screen shot of your site/template using the key "Prnt Scrn" on Windows or the corresponding on Mac/Linux. (There are also many programs specialized in screen shots that can be used.) After making the screen shot, paste or open the picture in an image editor such as PhotoShop or Gimp and resize and crop your image to 206x150 pixles.

Packaging a extension

2009-05-04T11:29:18Z

Felham: Added sub headline

{{inuse}}
A directory with several loose files is not a convenient package for distribution. So the final step is to make a ''package''. This is a compressed archive containing the directory structure and all the files. The package can be in '''ZIP''' format (with a <tt>.zip</tt> extension), in '''TAR-gzip''' format (with a <tt>.tar.gz</tt> extension), or in '''TAR-bz2''' format (with a <tt>.tar.bz2</tt> extension).

If your template is in a directory <tt>mytemplate/</tt> then to make the package you can connect to that directory and use commands like:
* <tt>tar cvvzf ../mytemplate.tar.gz *</tt>
* <tt>zip -a -r ..\mytemplate.zip *.*</tt>

=== Note to Mac OS X users ===
Note to template developers using Mac OS X systems: the Finder's "compress" menu item produces a usable ZIP format package, but with one catch. It stores the files in [[AppleDouble]] format, adding extra files with names beginning with "<tt>._</tt>". Thus it adds a file named "<tt>._templateDetails.xml</tt>, which Joomla 1.5.x can sometimes misinterpret. The symptom is an error message, "XML Parsing Error at 1:1. Error 4: Empty document". The workaround is to compress from the command line, and set a shell environment variable "COPYFILE_DISABLE" to "true" before using "compress" or "tar". See the [[AppleDouble]] article for more information.

Amending the templateDetails.xml file

2009-05-04T11:26:12Z

Felham: Sorry, misunderstood this before.

To ensure that your template is fully internationalised you must make sure that certain XML elements are translated and that the language definition files are listed in the ''templateDetails.xml'' file.

==== Translating templateDetails.xml ====
A couple of the elements in the ''templateDetails.xml'' file are used in the Template Manager and are themselves translatable. These should always be translated.

{| class="wikitable"
| name
| Name of the template. For example, Beez

|-
| description
| Description of the template.

|}
These fields are also shown to the user during template installation. <font color="red"><nowiki>[[[ Check: These did not get translated at one time. </nowiki>Has this been fixed? ]]]</font>

==== Adding language definition files to templateDetails.xml ====
All language files must be declared in the ''templateDetails.xml'' file. This is done by adding two ''<nowiki><language></nowiki>'' elements for each language to be included with the template; one for the front-end strings; the other for the administrator back-end strings. For example, the two British English language files and the two German language files for the Beez template are declared as follows
<source lang="xml">
<?xml version=”1.0” encoding=”utf-8” ?>
<install version=”1.5” type=”template”>

.........

<languages>
<language tag=”en-GB”>en-GB.tpl_beez.ini</language>
<language tag=”de-DE”>de-DE.tpl_beez.ini</language>
</languages>

.........

<administration>
<languages folder=”admin”>
<language tag=”en-GB”>en-GB.tpl_beez.ini</language>
<language tag=”de-DE”>de-DE.tpl_beez.ini</language>
</languages>
</administration>

</install>
</source>

Note that in the administration ''<nowiki><languages></nowiki>'' tag the ''folder'' attribute is used. This is because the language files for the front-end and back-end have the same file names and so cannot exist in the same directory within the template package file. In this example, the administration language files have been placed in a sub-directory called ''admin'' to separate them from the front-end language files.
<noinclude>[[Category:Templates]][[Category:Languages]]</noinclude>

File structure for packaging

2009-05-04T11:22:03Z

Felham:

{{inuse}}The most basic files, such as index.php, component.php, templateDetails.xml, template_thumbnail.png, favicon.ico, params.ini should be placed directly in your template folder. The most common is to place images, CSS files, JavaScript files etc in separate folders. Joomla override files must be placed in folders in the folder "html".

When making the template folder, your language files should be copied to your template folder. The ones for the front end site should be placed directly in the template folder. If you have language files for the back end, these should be placed in a folder, named for instance "admin". All the language files will be copied automatically to the right folders if stated correctly in the templateDetails.xml.

Talk:Distributing Joomla! templates

2009-05-04T11:09:30Z

Felham: New page: I don't quite understand what "How does template installation work?" has to do here, if this is for people who want to package their own template. Installation of templates are much more b...

I don't quite understand what "How does template installation work?" has to do here, if this is for people who want to package their own template. Installation of templates are much more basic, and covered elsewhere in the docs. --[[User:Felham|Felham]] 11:09, 4 May 2009 (UTC)

Distributing Joomla! templates

2009-05-04T11:08:09Z

Felham: Changed to How_to_install_templates which already exists

== How to choose a suitable license ==
{{:How to choose a suitable license|How to choose a suitable license}}

== How does template installation work? ==
{{:How_to_install_templates|How_to_install_templates}}

== File structure for packaging ==
{{:File structure for packaging|File structure for packaging}}

== Creating a thumbnail preview image ==
{{:Creating a thumbnail preview image|Creating a thumbnail preview image}}

== Packaging the template for installation ==
{{:Packaging the template|Packaging the template}}

<noinclude>[[Category:Templates]]</noinclude>
<noinclude>[[Category:Tutorials]]</noinclude>

J1.5:Installing a template

2009-05-04T11:07:38Z

Felham:

=== Install via Admin Panel (packed template file) ===

Log into the back-end of your site (''www.your-site.com''/administrator/)

Click on: Extensions -> Install/Uninstall

[[Image:Tpl_tut_install_template_1.png]]

You see the page "Extension Manager"

From here you can install your Templates, Plugins, Modules, Components and Languages. You have three options:
* Upload Package File - (select a package from your PC, upload and install it)
* Install from Directory - (enter the path where the package is located on your server)
* Install from URL - (enter the URL to the package)
Here, we choose the first method: Upload Package File

Select the package from your PC and click the button "Upload File & Install"

[[Image:Tpl_tut_install_template_2.png]]

If the package contains no errors you are done and get a success message like the one below.

[[Image:Tpl_tut_install_template_3.png]]

=== Install via FTP (unpacked template file) ===

Templates can also be installed via FTP without packaging them. Simply select the template folder on your PC and upload it to your server, using your favorite FTP software. Be sure you upload the template folder to the directory: /''path_to_joomla''/templates/ - where /''path_to_joomla''/ is the location of your Joomla! installation on the server. This method is mostly used when you have created a template yourself, and do not want to have to package it to install the template, or if you want to upload more than one template at once.

''Note: Do not try to use FTP to install Components, Modules and Plugins if you are a beginner/novice. These items need database entries which have to be inserted manually if you bypass the package installer.''

<noinclude>[[Category:Beginners]]</noinclude>
<noinclude>[[Category:Templates]]</noinclude>
<noinclude>[[Category:Topics]]</noinclude>

J1.5:Installing a template

2009-05-04T11:06:38Z

Felham: Double title removed, inserted headlines

== Install via Admin Panel (packed template file) ==

Log into the back-end of your site (''www.your-site.com''/administrator/)

Click on: Extensions -> Install/Uninstall

[[Image:Tpl_tut_install_template_1.png]]

You see the page "Extension Manager"

From here you can install your Templates, Plugins, Modules, Components and Languages. You have three options:
* Upload Package File - (select a package from your PC, upload and install it)
* Install from Directory - (enter the path where the package is located on your server)
* Install from URL - (enter the URL to the package)
Here, we choose the first method: Upload Package File

Select the package from your PC and click the button "Upload File & Install"

[[Image:Tpl_tut_install_template_2.png]]

If the package contains no errors you are done and get a success message like the one below.

[[Image:Tpl_tut_install_template_3.png]]

== Install via FTP (unpacked template file) ==

Templates can also be installed via FTP without packaging them. Simply select the template folder on your PC and upload it to your server, using your favorite FTP software. Be sure you upload the template folder to the directory: /''path_to_joomla''/templates/ - where /''path_to_joomla''/ is the location of your Joomla! installation on the server. This method is mostly used when you have created a template yourself, and do not want to have to package it to install the template, or if you want to upload more than one template at once.

''Note: Do not try to use FTP to install Components, Modules and Plugins if you are a beginner/novice. These items need database entries which have to be inserted manually if you bypass the package installer.''

<noinclude>[[Category:Beginners]]</noinclude>
<noinclude>[[Category:Templates]]</noinclude>
<noinclude>[[Category:Topics]]</noinclude>

Creating a thumbnail preview image

2009-05-04T10:21:30Z

Felham:

{{inuse}}A thumbnail preview image should be 206 pixels in width and 150 pixels high. Recommended file format is png.

You can take a screen shot of your site/template using the key "Prnt Scrn" on Windows or the corresponding on Mac/Linux. (There are also many programs specialized in screen shots that can be used.) After making the screen shot, paste or open the picture in an image editor such as PhotoShop or Gimp and resize and crop your image to 206x150 pixles.

Distributing Joomla! templates

2009-05-04T10:03:10Z

Felham: Added headlines

== How to choose a suitable license ==
{{:How to choose a suitable license|How to choose a suitable license}}

== How does template installation work? ==
{{:How does template installation work?|How does template installation work?}}

== File structure for packaging ==
{{:File structure for packaging|File structure for packaging}}

== Creating a thumbnail preview image ==
{{:Creating a thumbnail preview image|Creating a thumbnail preview image}}

== Packaging the template for installation ==
{{:Packaging the template|Packaging the template}}

<noinclude>[[Category:Templates]]</noinclude>
<noinclude>[[Category:Tutorials]]</noinclude>

Distributing Joomla! templates

2009-05-04T10:01:07Z

Felham:

{{:How to choose a suitable license|How to choose a suitable license}}

{{:How does template installation work?|How does template installation work?}}

{{:File structure for packaging|File structure for packaging}}

{{:Creating a thumbnail preview image|Creating a thumbnail preview image}}

== Packaging the template for installation ==
{{:Packaging the template|Packaging the template}}

<noinclude>[[Category:Templates]]</noinclude>
<noinclude>[[Category:Tutorials]]</noinclude>

Creating a basic Joomla! template

2009-05-04T10:00:13Z

Felham: Moved Packiging the template text to an own article (which were created but not used)

== Introduction ==

The purpose of this tutorial is to serve as an introduction to creating Joomla! templates. It will cover the essential files and code needed to create a basic template. The code is presented so it can be cut and pasted with very little modification needed.

== Setting up a directory structure ==
{{:Setting up a directory structure|Setting up a directory structure}}
{{:How to edit the files|How to edit the files}}
== Creating a basic templateDetails.xml file ==
{{:Creating a basic templateDetails.xml file}}

== Creating a basic index.php file ==
{{:Creating a basic index file}}
{{:Testing the template}}

== Packaging the template for installation ==
{{:Packaging_the_template}}

== Conclusion ==

You should now have created a template that works. It won't look like much yet. The best thing to do now is start experimenting with the layout.

<noinclude>
[[Category:Templates]]
[[Category:Tutorials]]
</noinclude>

Packaging a extension

2009-05-04T09:59:04Z

Felham: Moved text from Editing Tutorial:Creating a basic Joomla! template

{{inuse}}
A directory with several loose files is not a convenient package for distribution. So the final step is to make a ''package''. This is a compressed archive containing the directory structure and all the files. The package can be in '''ZIP''' format (with a <tt>.zip</tt> extension), in '''TAR-gzip''' format (with a <tt>.tar.gz</tt> extension), or in '''TAR-bz2''' format (with a <tt>.tar.bz2</tt> extension).

If your template is in a directory <tt>mytemplate/</tt> then to make the package you can connect to that directory and use commands like:
* <tt>tar cvvzf ../mytemplate.tar.gz *</tt>
* <tt>zip -a -r ..\mytemplate.zip *.*</tt>

Note to template developers using Mac OS X systems: the Finder's "compress" menu item produces a usable ZIP format package, but with one catch. It stores the files in [[AppleDouble]] format, adding extra files with names beginning with "<tt>._</tt>". Thus it adds a file named "<tt>._templateDetails.xml</tt>, which Joomla 1.5.x can sometimes misinterpret. The symptom is an error message, "XML Parsing Error at 1:1. Error 4: Empty document". The workaround is to compress from the command line, and set a shell environment variable "COPYFILE_DISABLE" to "true" before using "compress" or "tar". See the [[AppleDouble]] article for more information.

Setting up a directory structure

2009-05-04T09:54:53Z

Felham:

To make the most basic template, '''create a new folder''' in the ''"templates"'' folder. Name this folder after your template i.e. "mynewtemplate".

Using a text editor (or dedicated editor such as [[Adobe Dreamweaver]]) '''create the files "index.php" and "templateDetails.xml"'''

To keep things organized, make '''2 new folders called "images" and "css"'''. Inside the "css" folder create a file called "style.css".

Although it is fine to place all your CSS code directly in your "index.php" file to start, many web developers prefer to place their CSS code in a separate file that can be linked from multiple pages using the "link" tag.

This is the most basic practical setup.

Outline of folder and file structure:
* '''mynewtemplate/'''
** <u>css/</u>
*** ''style.css''
** <u>images/</u>
** ''index.php''
** ''component.php''
** ''templateDetails.xml''

What is the purpose of the templateDetails.xml file?

2009-05-04T09:38:56Z

Felham: /* File Structure */

{{RightTOC}}
The templateDetails.xml file holds a variety of meta-data used by the [[Screen.templates.15|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.

[[Image:template_details_basic.png]]

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

===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.

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

Optional and highly recommended file structure --

<pre>
<files>
<filename>index.php</filename>
<filename>component.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
<filename>params.ini</filename>
<folder>images/</folder>
<folder>css/</folder>
</files>
</pre>

===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.

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

===Module Positions===
The available [[module_positions|Module Positions]] that can be used in the template are defined.

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

===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.

[[Image:template_details_params.png]]

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

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

For more information about working with Parameters, see:

: [[Defining a parameter in templateDetails.xml]]
: [[Retrieving parameter data in a template file]]

<noinclude>[[Category:Templates]][[Category:Topics]][[Category:Beginners]]
[[Category:Parameters]]
[[Category:Template FAQ]]
</noinclude>

What is the purpose of the templateDetails.xml file?

2009-05-04T09:36:22Z

Felham: /* File Structure */

{{RightTOC}}
The templateDetails.xml file holds a variety of meta-data used by the [[Screen.templates.15|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.

[[Image:template_details_basic.png]]

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

===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.

<pre>
<files>
<filename>index.php</filename>
<filename>component.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>
</pre>

Optional and highly recommended file structure --

<pre>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
<filename>params.ini</filename>
<folder>images/</folder>
<folder>css/</folder>
</files>
</pre>

===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.

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

===Module Positions===
The available [[module_positions|Module Positions]] that can be used in the template are defined.

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

===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.

[[Image:template_details_params.png]]

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

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

For more information about working with Parameters, see:

: [[Defining a parameter in templateDetails.xml]]
: [[Retrieving parameter data in a template file]]

<noinclude>[[Category:Templates]][[Category:Topics]][[Category:Beginners]]
[[Category:Parameters]]
[[Category:Template FAQ]]
</noinclude>

Creating a basic templateDetails.xml file

2009-05-04T09:34:24Z

Felham: Added the file component.php

The <tt>templateDetails.xml</tt> file is essential. Without it, your template won't be seen by Joomla!. The file holds key "metadata" about the template.

Lets look at an example:
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN"
"http://dev.joomla.org/xml/1.5/template-install.dtd">
<install version="1.5" type="template">
<name>mynewtemplate</name>
<creationDate>2008-05-01</creationDate>
<author>John Doe</author>
<authorEmail>john@example.com</authorEmail>
<authorUrl>http://www.example.com</authorUrl>
<copyright>John Doe 2008</copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>My New Template</description>
<files>
<filename>index.php</filename>
<filename>component.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
<filename>images/background.png</filename>
<filename>css/style.css</filename>
</files>
<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>
</positions>
</install>
</source>
So, as you can see, we have a set of information between markup tags ( the <thing> ). Your best approach is to cut and paste this into your "templateDetails.xml" file and change the relevant bits (such as <name> <author> ).

The <files> part should contain all the files that you use - you possibly don't know what they are called yet - don't worry update it later.

Leave the positions as they are - these are a common set so you will be able to switch easily from the standard templates.

Amending the templateDetails.xml file

2009-04-28T15:33:15Z

Felham: There is no folder called "admin", so deleted that section. Adding the folder="admin" is not necessary, since we use the administration tags before. See JA Purity for proof of this.

To ensure that your template is fully internationalised you must make sure that certain XML elements are translated and that the language definition files are listed in the ''templateDetails.xml'' file.

==== Translating templateDetails.xml ====
A couple of the elements in the ''templateDetails.xml'' file are used in the Template Manager and are themselves translatable. These should always be translated.

{| class="wikitable"
| name
| Name of the template. For example, Beez

|-
| description
| Description of the template.

|}
These fields are also shown to the user during template installation. <font color="red"><nowiki>[[[ Check: These did not get translated at one time. </nowiki>Has this been fixed? ]]]</font>

==== Adding language definition files to templateDetails.xml ====
All language files must be declared in the ''templateDetails.xml'' file. This is done by adding two ''<nowiki><language></nowiki>'' elements for each language to be included with the template; one for the front-end strings; the other for the administrator back-end strings. For example, the two British English language files and the two German language files for the Beez template are declared as follows
<source lang="xml">
<?xml version=”1.0” encoding=”utf-8” ?>
<install version=”1.5” type=”template”>

.........

<languages>
<language tag=”en-GB”>en-GB.tpl_beez.ini</language>
<language tag=”de-DE”>de-DE.tpl_beez.ini</language>
</languages>

.........

<administration>
<languages>
<language tag=”en-GB”>en-GB.tpl_beez.ini</language>
<language tag=”de-DE”>de-DE.tpl_beez.ini</language>
</languages>
</administration>

</install>
</source>

Note that the language files for the back-end are placed automatically in the folders ''en-GB'' and ''de-DE'' in ''administrator/language/'', if the tags and administration hierarchy as stated above is used.
<noinclude>[[Category:Templates]][[Category:Languages]]</noinclude>

Creating a basic index file

2009-04-28T14:41:41Z

Felham: System CSS files are not linked to automatically using the jdoc include head, so added info about that. Also added the echo this template code.

The index.php file becomes the core of every page that Joomla! delivers. Essentially, you make a page (like any html page) but place PHP code where the content of your site should go. Here is the bare-bones code ready for you to cut and paste.

Lets start at the top:

<pre>
<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
</pre>
The first line stops naughty people looking at your coding and getting up to bad things. The second tells the browser (and webbots) what sort of page it is. The third line says what language the site is in.

Now the header for real:

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

The first line gets Joomla to put the correct header information in. This includes the page title, meta information as well as system JavaScript.
The rest creates links to two system style sheets and to your own style sheet (if it's named style.css and is located in the css folder).

Now for the main body:
<pre>
<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>
</pre>

Amazingly, this will suffice! Yes, its a very basic layout, but it will do the job. Everything else will be done by Joomla!. Note: you will need to ensure your menu is set to go into the "top" [[Screen.modules.edit.15#Details|module position]].

Finish it off - one last bit:
<pre>
</html>
</pre>
<noinclude>View the [[Testing the template|full source code]] of this template.</noinclude>

User:Felham

2009-04-27T13:25:55Z

Felham: New page: I'm a Joomla user from Sweden. You can find me with the same nick name on Joomla's Forum.

I'm a Joomla user from Sweden. You can find me with the same nick name on Joomla's Forum.

Talk:Using Class Suffixes

2009-04-27T13:23:34Z

Felham:

Great tutorial, but there is nothing about Menu Class Suffixes in the text, it only says in the headlines etc. that Menu Class Suffixes is going to be written about, but there is nothing - only Module Class Suffix again.

I added info about the menu class suffix function. Better to come with solutions than just complain... ;)

Using Class Suffixes

2009-04-27T13:22:44Z

Felham: Added about Menu Class Suffixes and moved the part about Module Class Suffixes that were under Menu Class Suffixes to where it belongs (under Module Class Suffixes), and also added new sub headlines.

{{review}}
This tutorial will show you how to use Page, Module, and Menu Class Suffixes in Joomla! 1.5 to fine-tune the appearance of your site. For the tutorial, we will assume you have the Joomla! 1.5.9 Sample site available.

==Background==
Joomla! creates HTML pages that use [[Glossary#Cascading_Style_Sheet_.28CSS.29|Cascading Style Sheets]] to control the appearance of the page. This includes things like fonts, colors, margins, and background. The CSS files are part of your template.

When Joomla! creates a page, it creates different CSS classes that are then referenced in the CSS file to specify which style will apply to which parts of the HTML page. These class names are pre-programmed into Joomla!. But Joomla! allows you to modify or add CSS classes by way of the Class Suffix parameters. This lets you fine-tune the appearance of specific pages with no programming and very little work. The best way to understand this is to see specific examples.

==When Would You Use a Class Suffix?==
Say, for example, that your website contains a number of Section Blog layouts, each for a different Section. If you are happy to have all of these pages styled the same way, then you wouldn't need to use a Page Class Suffix. However, say you want each of these sections styled differently than the others. For example, maybe you want a different background color or image for each different section.

Or say that you want the heading on your front page to look different than the heading on other pages.

In both of these cases, if you modify the styling in your "template.css" file for the standard CSS classes, it will affect all Menu Items that use these CSS classes. For example, if you change the style for the CSS class "componentheading", it will affect all of the Menu Items that use this class.

However, if you add a unique Page Class Suffix to a Menu Item, then Joomla! will create new CSS classes for each individual Menu Item so you can style each one differently.

==Page Class Suffix==
Before you start, make sure you have the Joomla! sample website available. Also, make sure the default template is set to "rhuk_milkyway" (in the Extensions → Template Manager).

===How It Works Without a Page Class Suffix===
Before we add a Page Class Suffix, let's see how this pages works without one. In the front end, navigate to Example Pages → Section Blog. In your browser, select the option to view the page source code. For example, in Firefox, press Ctrl+U. In Internet Explorer, select View → Source. In Safari, select View → View Source.

Using the "Find" command, find the first occurrence of the word "componentheading". It should look like the following: <pre><div class="componentheading"></pre>

Browse down the file and find the following tags:
:<pre><table class="blog" cellpadding="0" cellspacing="0"> </pre>

:<pre><table class="contentpaneopen"></pre>

:<pre><td class="contentheading" width="100%"></pre>

:<pre><table class="contentpaneopen"></pre>

<blockquote>''Note: The following screenshots were made using the free Firefox add-in called "Firebug". Firebug allows you to quickly see the relationship between the HTML elements in your source and the text and graphics shown on the page. It is a very handy tool, and you can get it [https://addons.mozilla.org/en-US/firefox/addon/1843 here]. There is also a free video tutorial about using Firebug with Joomla! available [[Tutorial:Using_Firebug_With_Your_Joomla_Website|here]].''</blockquote>

The screenshot below shows you the "componentheading" class. It is the page title area above the blog article.

[[Image:Componentheading_class_firebug.png]]

This screenshot shows you the entire "blog" class. This is the outer table into which all of the articles will fit.

[[Image:Blog_class_firebug.png]]

The next screenshot shows you the "contentpaneopen" class for an article heading. This includes the article title and the PDF, Print, and Email icons to the right.

[[Image:Contentpaneopen_class_title_firebug.png]]

This screenshot shows you the "contentpaneopen" class for the body of the article. This includes the author and date information as well as the actual article text.

[[Image:Contentpaneopen_class_article_firebug.png]]

So this gives us a good understanding of how Joomla! allows us to style the elements on a Section Blog layout. Joomla! writes out these classes as part of the HTML. And the template contains CSS that provides the styling information for these various elements and classes.

===Page Class Suffix (No Space)===
Now that we see how this works without a Page Class Suffix, let's try it with one. In the back end, navigate to Menus → Example Pages and click on "Section Blog". This should display the "Menu Item: [Edit]" screen for the Section Blog Layout. Click Parameters (System) to show the System Parameters. In the "Page Class Suffix" field enter the value "_myBlogSuffix" and click the Save button.

Now, go back to the front end and again navigate to Example Pages → Section Blog. Notice right away that we lost the styling for the page and article titles. Let's look closer to see why.

Using the browser "Find" command, find the first occurrence of "_myBlogSuffix". It is in a "div" tag and looks like this: <pre><div class="componentheading_myBlogSuffix"></pre> If you look through the source, you should also see the following classes: <code>blog_myBlogSuffix</code>, <code>contentpaneopen_myBlogSuffix</code>, and <code>contentheading_myBlogSuffix</code>.

By adding the Page Class Suffix, we ''changed'' all of these class names. That means that special styling in the CSS file that refers to the "base" class names (like componentheading, blog, and so on) will not be applied, since those classes no longer exist on the page.

Now, you can fix this problem by editing your templates CSS file to add the same styling for the new classes (for example, "componentheading_myBlogSuffix"). But there is a much easier way to do this -- simply by adding a leading space to the parameter.

===Page Class Suffix (With a Leading Space)===
Again in the back end, go back to Menus → Example Pages → Section Blog. We're going to change the value of the Page Class Suffix. This time we're going to enter in a leading space and call it <space> + "myBlogClass", as shown below.

[[Image:Page_class_suffix_space.png]]

Now, go back to the front end and re-display the Example Pages → Section Blog. Notice that our styling is back! Let's look at the HTML source to see what is going on. Open the source and find the first occurrence of "myBlogClass". It should like this: <pre><div class="componentheading myBlogClass">
</pre> Because we put a leading space in the Page Class Suffix, we created a second class instead of changing the name of the first class (which is allowed and supported by all modern browsers). So we didn't break any of the existing CSS styling for this page. (One warning: we need to make sure the new class name is different than any of the other class names used on the page. Otherwise, we might get styling we don't want.)

===Add CSS Styling to New Class===

At this point, we've created a new CSS class in the HTML to allow for some new styling. Now we need to use this new class to actually change the look of our page. The first thing we need to do is find the applicable CSS file. In this case, it is <code><joomla_root>/templates/rhuk_milkyway/css/template.css</code>.

Let's say we want to add a background color, but only to this specific Section Blog. (Remember, if we wanted to just change all of the Section Blog pages in our site, we could just change the CSS styling for the base classes, such as "componentheading" or "blog".) We need to do is figure out which area ("componentheading", "blog", or "contentpaneopen") we want to style. Say we just wanted to style the "componentheading" area.

First, let's use the CSS selector "div.myBlogClass" and add the following code to the end of our CSS file:<source lang="css">
/* Custom Styling */
div.myBlogClass {
background-color: #FFE4E1; /* mistyrose */
}
</source>

The result is that the page heading now has the background color, as shown below.

[[Image:Div_styling_example.png|center|frame]]

Now this works fine in our example, because the other classes are defined for "table" tags and not "div" tags. But it is normally better to be more specific in our style selector by styling only those elements that have both the desired base class and the new class. For example, let's replace the code above with the following code:
<source lang="css">/* Custom Styling */
.blog.myBlogClass {
background-color: #FAFAD2; /* lightgoldenrod */
}
</source>

This specifies that the new style will only be applied to elements that have both the "blog" and the "myBlogClass" styles. This gives us the background color over the entire "blog" area, as shown below.

[[Image:Blog_styling_example.png]]

The great thing about creating a ''new'' class (with the leading space trick) is that we don't need to copy all of the existing styling for the base classes. We can just focus on the new styling that we want.

Now in this example, we focused on the Section Blog layout. The class names for different components might be different, but the process will be the same. The table below shows some common Joomla! layouts and a list of class names that can have Page Class Suffixes added.

{| class="wikitable"
|-
! Layout
! CSS Class Names Used
|-
| Article Layout
| componentheading, contentpaneopen, contentheading, contentpagetitle
|-
| Category Blog, Frontpage Blog, Section Blog
| componentheading, contentpagetitle, blog, contentpaneopen, contentheading, readon, blog_more
|-
| Category List, Section List
| componentheading, contentpane, contentdescription
|-
| Contact Category
| componentheading, contentpane, contentdescription, sectiontablefooter, sectiontableheader, category
|-
| Contact Layout
| componentheading, contentpaneopen, contentheading
|}

So, to sum up what we have learned about using the Page Class Suffix parameter:
# Use a leading space to create a new CSS class. This way you don't have to worry about re-doing or breaking existing CSS styles.
# Look in the HTML source code to find the locations of the base and new classes.
# If desired, use Firebug to see which HTML elements correspond to which areas on the page.
# Add custom styling to the end of the "template.css" file, specifying both the name of the desired base class and the custom class in the form <code>.baseclass.customclass</code> as in the example above.

==Module Class Suffix==
The Module Class Suffix parameter works in the same way as the Page Class Suffix. Let's go through an example using the Latest News module.

In the administrative back end, navigate to Extensions → Module Manager and find the "Latest News" module. Click on it to open it for editing, and enter <space> + "customLatestClass" in the Module Class Suffix parameter field, as shown below:

[[Image:Module_class_suffix_space.png]]

Now, navigate to the home page in the front end and view the page source code. The screenshot below was made using the Firebug add-in tool. It shows the home page and the HTML and styling for the customised Latest News module.

[[Image:Latest_news_custom_class.png]]

In the upper part of the screen, outlined in light blue, is the "div" element for the module. Below, in the HTML window, we see the HTML as follows: <pre><div class="moduletable customLatestClass"></pre> and then <pre><ul class="latestnews customLatestClass"></pre>

The "moduletable" and "latestnews" classes are created automatically. The new class, "customLatestNews" was created because we started the Module Class Suffix parameter with a leading space.

Now, let's use our new class to add some custom styling. Again, go to the end of the templates/rhuk_milkyway/css/template.css file and add the following code:
<source lang="css">
div.customLatestClass {
background-color: #FFFFD2;
}

div.customLatestClass h3, ul.customLatestClass, ul.customLatestClass a {
color: #8B4513;
}
</source>

Save the file and re-display the home page. It should look like the screenshot below:

[[Image:Latest_news_styled.png]]

The CSS selector <code>div.customLatestClass</code> sets the background color for the entire area. The three selectors <code>div.customLatestClass h3, ul.customLatestClass, ul.customLatestClass a</code> select the font color for the "h3" heading, the bullets ("ul" tag), and the "a" tag, respectively. Note that, if we only wanted to style the "ul" element, we wouldn't need a Module Class Suffix unless we had more than one "Latest News" module. Instead, we could just have defined the CSS using the standard "latestnews" class.

===Be careful not to break existing CSS styling===

In menus, we need to be careful not to break existing CSS styling.

Let's look at how this works. In the administrative back end, navigate to Extensions → Module Manager and open the Main Menu for editing. Click on the Advanced Parameters. Notice that the Module Class Suffix is set to "_menu", without a leading space.

Now, go to the Home page in the front end and view the source code (or use Firebug). The screenshot below shows the HTML for the Main Menu.

[[Image:Main_menu_div.png]]

Notice that the class is called "module_menu" because of the Module Class Suffix. Also, notice that there is special styling in the "template.css" and "blue.css" files for the "module_menu" class. For example, there is a background image that provides part of the blue border around the menu.

We can confirm this by returning to the back end and changing the Module Class Suffix to blank. Return to the Home page and refresh. Now the Main Menu will show without the special "module_menu" styling, as shown below:

[[Image:Main_menu_no_suffix.png]]

This shows an important point. Existing modules, especially menus, may already have CSS styling that depends on Module Class Suffixes. So we need to be careful when making changes.

What if we still wanted to add some special styling just to the Main Menu? One way is to get tricky and add a second CSS class to the existing suffix. To see this, return to the Module Manager in the back end and open the Main Menu for editing. This time, in the Module Class suffix, enter <code>_menu</code>, a space, and then <code>myMenuClass</code>, as shown below:

[[Image:Module_class_suffix_tricky.png]]

Now, add the following code to the end of the templates/rhuk_milkyway/css/template.css file:
<source lang="css">
div.myNewClass {
font-size: 1.2em;
}
</source>

Go back to the Home page and notice that now the font in the Main Menu is larger, as shown below.

[[Image:Main_menu_custom_style.png]]

If we open Firebug, we can see what the HTML and CSS looks like, as shown below:

[[Image:Firebug_custom_menu_class.png]]

By putting a space between the "_menu" and "myNewClass", we added the new class into the HTML. Then, by selecting the new class in the CSS file, we changed the font size.

==Menu Class Suffix and Menu Tag ID==
All core modules allow you to enter a Module Class Suffix, as discussed above. Menu modules have two additional parameters: Menu Class Suffix and Menu Tag ID. Let's look at what these parameters do.

===Menu Class Suffix===

The Menu Class Suffix inserts an extra suffix in the class for the unordered list that builds up the menu. If unedited, the class is "menu". If adding "_myMenuClass" under Advanced Parameters → Menu Class Suffix, the new tag will be "menu_myMenuClass".

(This behaviour is only for the Menu Style "List". If chossing "Legacy - Vertical" or "Legacy - Horizontal", the class suffix will be added to the links in the table; this suffix will then be "mainlevel_myMenuClass". When choosing the Legacy Flat List, the suffix will be added the links (as on the two other Legacy lists), but it will also be added to the ul tag, but as an id rather than a class; the id will be "mainlevel_myMenuClass".)

===Menu Tag ID parameter===

Now, lets look at the Menu Tag ID parameter. Navigate to the back end, open the Main Menu module for editing, and enter "myTagID" in the Menu Tag ID parameter.

Add the following code to the end of the templates/rhuk_milkyway/css/template.css file:
<source lang="css">
#myTagID {
list-style-type: square;
}
</source>

Now, re-display the Home page to see the change. The bullets for the Main Menu should now appear as squares, as shown below:

[[Image:Main_menu_square_bullets.png]]

Finally, we can look at the HTML and CSS in Firebug, as shown below.

[[Image:Menu_tag_id_code.png]]

Joomla! has added the attribute <code>id="myTagID"</code> to the "ul" tag for the Main Menu. This allowed us to change the style for this ID. Note that, since this is an "id" attribute, we use the CSS selector <code>#myTagID</code> (with a "#" instead of a ".").

==Conclusion==
The Class Suffix and Menu Tag ID parameters allow you to fine-tune the CSS styling of your web site. By using a leading space in the suffix name, we can create a new class. This is normally the preferred method, since, as long as the new class name does not conflict with an existing class, no existing styling will be broken.

[[Category:Tutorials]]

Talk:Using Class Suffixes

2009-04-27T12:39:22Z

Felham: New page: Great tutorial, but there is nothing about Menu Class Suffixes in the text, it only says in the headlines etc. that Menu Class Suffixes is going to be written about, but there is nothing -...

Where to find design tools

2009-03-25T15:33:57Z

Felham: Updated link.

[http://www.alvit.de/handbook/ Web Developer's Handbook], a massive directory of design resources for web developers.<br />
[http://colorschemedesigner.com/ Colour scheme generator]
<noinclude>[[Category:Itemised lists]][[Category:Templates]]
[[Category:Template FAQ]]</noinclude>

What is the typical template directory structure?

2009-03-25T15:29:08Z

Felham: Added info about the file component.php

===Typical Template Directory Structure===
It is most common for a template to have at 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.
* 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.

{{:Typical template directory structure}}

<noinclude>[[Category:Templates]][[Category:Definition lists]][[Category:Beginners]]
[[Category:Template FAQ]]
</noinclude>