Chapter 20: Customizing Joomla! Templates 509 Knowing the Parts of a Template As noted earlier, a template is actually a collection of files that work together. In this section, I out- line the basic files that are needed and their roles in the system. Note that some templates are more complex than others and may include a large number of additional files. The discussion of the default templates in the next section demonstrates the variance that can occur with various approaches to template design. Directory structure All front-end templates are kept inside the directory /templates, located at the root of the Joomla! installation. All back-end templates are kept in /administrator/templates. Inside the appropriate directory, each template will have its own directory names for the template. By way of example, the default RHUK_Milkyway template’s files are found at /templates/rhuk_ milkyway . Inside the individual template’s directory you typically find: l A /css directory containing the CSS files needed by the template l An /html directory containing overrides, if any l An /images directory containing any images specifically needed by the template The template may also have other directories, as defined by the template developer. The key files At a minimum, a Joomla! 1.5.x template includes the following files: l component.php l index.php l template.css l templateDetails.xml l template_thumbnail.png Each of these key files is discussed in detail in the following sections. component.php The component.php file has a very narrow and specific purpose; it provides the display of printer-friendly pages. Part IV: Customizing and Extending the System 510 Here are the contents of this file, taken from the default RHUK_Milkyway template: <head> <jdoc:include type=”head” /> <link rel=”stylesheet” href=”<?php echo $this->baseurl ?>/templates/ rhuk_milkyway/css/template.css” type=”text/css” /> <?php if($this->direction == ‘rtl’) : ?> <link rel=”stylesheet” href=”<?php echo $this->baseurl ?>/templates/ rhuk_milkyway/css/template_rtl.css” type=”text/css” /> <?php endif; ?> </head> <body class=”contentpane”> <jdoc:include type=”message” /> <jdoc:include type=”component” /> </body> </html> This file is standardized from template to template. The only lines that change from template to template relate to the path of the CSS files. Note The preceding code example omits the preliminary tag, comments, access control, and doctype declaration. Please see the file included in the distribution to view the file in its entirety. index.php The index.php is the key file in the template. This file contains the HTML formatting for the page layout and the statements that include the component and module output. The file provides a standard document head and then outlines the page’s div structure and places all the element posi- tion holders on the page. Elements are positioned on the page through the use of jdoc:include statements. Here is a snippet from the default RHUK_Milkway template’s index.php, showing the placement of two module position holders: <div id=”search”> <jdoc:include type=”modules” name=”user4” /> </div> <div id=”pathway”> <jdoc:include type=”modules” name=”breadcrumb” /> </div> The preceding code places on the page the user4 and breadcrumb module position holders. To enable easy styling of the elements inside those module positions, the user4 module position holder is wrapped in a div with the id search, and the user4 module position holder is wrapped in a div with the id pathway. Chapter 20: Customizing Joomla! Templates 511 The include statements use the syntax jdoc:include type=”nameoftype” The available jdoc include types are: l component <jdoc:include type=”component” /> This is used only once in the template to set the placement of the main content area for the page. l head <jdoc:include type=”head” /> This is used only once in the template to set the style, script, and meta elements inside the template’s <head> area. l installation <jdoc:include type=”installation” /> This is only used in the Joomla! installer template and should not appear in your site or admin template’s index. php file. l message <jdoc:include type=”message” /> This is used only once in the template. It is placed inside the <body> area where you want system messages to appear on the page. l module <jdoc:include type=”module” name=”modulename” /> This is used to place a single module on the page. Additional attributes to control the layout and appear- ance may be available. l modules <jdoc:include type=”modules” name=”modulepositionname” /> This is used to place the module position holders in the template. Additional attributes to control the layout and appearance may be available. Note Module position holders must not only be placed into the index.php file but must also be declared in the templateDetails.xml file. An index.php file may or may not make use of all the available types; however, it will certainly use at least the head, component, message, and modules types, as these are the minimum needed to construct a usable template. Tip The code for the index.php file is too long for convenient inclusion in the text. Nonetheless, I strongly rec- ommend reviewing the index.php files included in the default Joomla! distribution to familiarize yourself with what happens in this key template file. template.css The styling of templates is handled by cascading style sheets. Although a template is very likely to have multiple CSS files, the key file is the template.css, which is located inside the template’s /css directory. This file determines the page width and margins, the placement of the elements on the page, and the look of the fonts, backgrounds, borders, and so on. Part IV: Customizing and Extending the System 512 Note If you are looking for a listing of the various Joomla! core CSS styles, there are two lists that are maintained and updated: http://forum.joomla.org/viewtopic.php?t=125508 and http://docs.joomla.org/Template_refer- ence_material. templateDetails.xml This file contains information that is needed by the Joomla! installer and the Template Manager. It also includes the definition of the template parameters for the Template Manager and the declara- tion of the module position holders for use by the Module Manager. The contents of templateDetails.xml file from the default RHUK_Milkyway template are typical: <?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>rhuk_milkyway</name> <creationDate>11/20/06</creationDate> <author>Andy Miller</author> <authorEmail>rhuk@rockettheme.com</authorEmail> <authorUrl>http://www.rockettheme.com</authorUrl> <copyright></copyright> <license>GNU/GPL</license> <version>1.0.2</version> <description>TPL_RHUK_MILKYWAY</description> <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> <filename>images/indent2.png</filename> <filename>images/indent3.png</filename> <filename>images/indent4.png</filename> <filename>images/index.html</filename> <filename>images/mw_box_blue_bl.png</filename> <filename>images/mw_box_blue_br.png</filename> <filename>images/mw_box_blue_tl.png</filename> <filename>images/mw_box_blue_tr.png</filename> <filename>images/mw_content_b_l.png</filename> <filename>images/mw_content_b_r.png</filename> <filename>images/mw_content_b.png</filename> <filename>images/mw_content_t_l.png</filename> <filename>images/mw_content_t_r.png</filename> Chapter 20: Customizing Joomla! Templates 513 <filename>images/mw_content_t.png</filename> <filename>images/mw_footer_blue_b_l.png</filename> <filename>images/mw_footer_blue_b_r.png</filename> <filename>images/mw_footer_blue_b.png</filename> <filename>images/mw_footer_separator.png</filename> <filename>images/mw_header_b.png</filename> <filename>images/mw_header_blue_t_l.png</filename> <filename>images/mw_header_blue_t_r.png</filename> <filename>images/mw_header_blue_t.png</filename> <filename>images/mw_header_l_b.png</filename> <filename>images/mw_header_r_b.png</filename> <filename>images/mw_header.jpg</filename> <filename>images/mw_joomla_logo.png</filename> <filename>images/mw_line_grey.png</filename> <filename>images/mw_menu_active_bg.png</filename> <filename>images/mw_menu_cap_l.png</filename> <filename>images/mw_menu_cap_r.png</filename> <filename>images/mw_menu_normal_bg.png</filename> <filename>images/mw_menu_separator.png</filename> <filename>images/mw_readon.png</filename> <filename>images/mw_shadow_blue_l.png</filename> <filename>images/mw_shadow_blue_r.png</filename> <filename>images/spacer.png</filename> <filename>css/index.html</filename> <filename>css/template.css</filename> <filename>css/template_rtl.css</filename> <filename>css/editor.css</filename> <filename>css/ieonly.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> <position>debug</position> <position>syndicate</position> </positions> <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> Part IV: Customizing and Extending the System 514 <option value=”green”>Green</option> <option value=”orange”>Orange</option> <option value=”black”>Black</option> <option value=”white”>White</option> </param> <param name=”backgroundVariation” type=”list” default=”blue” label=”Background Variation” description=”Background 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> <param name=”widthStyle” type=”list” default=”fax” label=”Template Width” description=”Width style of the template”> <option value=”fax”>Fluid with maximum</option> <option value=”medium”>Medium</option> <option value=”small”>Small</option> <option value=”fluid”>Fluid</option> </param> </params> </install> The preceding code provides the following key information: l The initial descriptive information for the Installer and the Template Manager l The declaration inside the <files> tags of all the files in the package for the installer l The declaration inside the <positions> tags of all the module position holders for the Module Manager. l The declaration inside the <param> tags of the template parameters that are available in the Template Manager. Note The preceding code example is shown in its entirety. template_thumbnail.png This file is the thumbnail image of the template that is shown inside the Template Manager. It is generally 206 x150 pixels in size. Although the system supports .jpg, .gif. and .png, the preferred format is .png. Chapter 20: Customizing Joomla! Templates 515 Introducing the Template Manager All of the system’s templates, both front-end and back-end, are managed from within Joomla’s Template Manager. To access the Template Manager, click on the option Template Manager under the Extensions menu. Clicking on the Template Manager option displays the output shown in Figure 20.5. The toolbar at the top of the Template Manager provides quick access to the following functions: l Default: Select a template then click this icon to set the template as the default for your site. l Edit: Select a template from the list then click this icon to edit the template’s details. l Help: Click to access the online Help files related to the active screen. FIGURE 20.5 The Template Manager interface. . templateDetails.xml file from the default RHUK_Milkyway template are typical: <?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. http://forum .joomla. org/viewtopic.php?t =12 5508 and http://docs .joomla. org/Template_refer- ence_material. templateDetails.xml This file contains information that is needed by the Joomla! installer. developer. The key files At a minimum, a Joomla! 1. 5 .x template includes the following files: l component.php l index.php l template.css l templateDetails.xml l template_thumbnail.png Each of