Joomla Template Tutorial - The Template Components

Article Index

The Template Components

In order to understand the contents of a template, we will start by looking at a blank joomla template. You can download such a blank template for the [JOOMLA FORGE]. In this file are the various files and folders that make up a Joomla template. These files must be placed in the /templates directory of a Joomla installation. So, if we had two templates installed, our directory would look something like:

/templates
/JS_Smoothportal
/JS_Synergy

Note that the directory names for the templates must be the same as the name of the template, in this case JS_Smoothportal and JS_Synergy. Obviously they are case sensitive and shouldn't contain spaces. Traditionally the designers initials or name is used as a prefix.

Within the directory of a template, there are a number of key files:

/JS_Smoothportal
templateDetails.xml
index.php

These two filenames and location must be matched exactly as this is how they are called by the Joomla core script.

  • templateDetails.xml
    (note the uppercase "D") An XML format metadata file that tells Joomla! what other files are needed when loading a web page that uses this template. It also details the author, copyright and what files make up the template (including any images used). The last use of this file is for installing a template when using the admin backend.
  • index.php
    This file is the most important. It lays out the site and tells the joomla CMS where to put the different components and modules. It is a combination of PHP and (X)HTML.

In almost all templates, additional files are used. It is conventional (although not required by the core) to name and locate them as shown below:

/JS_Smoothportal
template_thumbnail.png
/css
template_css.css
/images
logo.png
  • template_thumbnail.png
    A web Browser screenshot of the template (usually reduced to around 140 pixels wide and 90 pixels high). After the template has been installed, this functions as a "Preview image" visible in the Joomla! administration Template Manager.
  • css/template_css.css
    The CSS of the template. The folder location is optional, but you have to specify where it is. Note that the file name is only important in that its referenced in index.php. You could call it what you like. Usually the name shown is used, but we will see later that there are advantages in having other css files too.
  • images/logo.png
    Any images that go with the template. Again for organization reasons, most designers put this in an images folder. Here we have a image file called logo.png as an example.

To add the template (again, copious tutorials exist) you go to the admin portion of your site and install the template by uploading the zip file. Note you can actually add the files individually (not in a zip) too. You have to put them in yoursite.com/templates.

templateDetails.xml

The templateDetails.xml must include all the files that are part of the template. It also includes information such as the author and copyright. Some of these are shown in the admin backend in the Template Manager

An example xml file is shown below:

<mosinstall type="template" version="1.0.x">
<name>YourTemplate</name>
<creationDate>March 06</creationDate>
<author>Barrie North</author>
<copyright>GNU/GPL</copyright>
<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail> <authorUrl>www.compassdesigns.net</authorUrl>
<version>1.0</version>
<description> An example template that shows a basic xml details file </description>
<files>
<filename>index.php</filename>
<filename>js/ie.js</filename>
<filename>template_thumbnail.png</filename>
</files>
<images>
<filename>images/header.png</filename>
<filename>images/background.png</filename>
<filename>template_thumbnail.png</filename>
</images>
<css> <filename>css/base.css</filename>
<filename>css/norightcol.css</filename>
<filename>css/template_css.css</filename>
</css>
</mosinstall>

Lets explain what some of these lines mean:

  • mosinstall
    The contents of the XML document are instructions for the installer. the option type="template" tells the installer that we are installing a template
  • name:
    Defines the name of your template. The name you enter here will also be used to create the directory within the templates directory. Therefore it should not contain any characters that the file system cannot handle, for example spaces. If installing manually, you need to create a directory that is identical to the template name.
  • creationDate:
    The date the template was created. It is a free form field and can be anything like May 2005, 08-June-1978, 01/01/2004 etc.
  • author:
    The name of the author of this template - most likely your name
  • copyright:
    Any copyright information goes into this element. A Licensing Primer for Developers & Designers can be found on the Joomla forums.
  • authorEmail:
    Email address where the author of this template can be reached.
  • authorURL:
    The URL of the author's web site
  • version:
    The version of this template
  • files:
    The "files" sections contains all generic files like the PHP source for the template or the thumbnail image for the template preview. Each file listed in this section is enclosed by <filename> </filename>. Also included would be any additional files, here we use the example of a JavaScript file that is required by the template.
  • images:
    All image files that the template uses are listed in the images section. Again each file listed is enclosed by <filename> </filename>. Path information for the files is relative to the root of your template, e.g. if your template is in the directory called 'YourTemplate' and all images are in a directory 'images' that is inside 'YourTemplate', the correct path is:
    <filename>images/my_image.jpg</filename>
  • css:
    The stylesheet is listed in the css section. Again the filename is enclosed by <filename> </filename> and it's path is relative to the template root. Its often useful to have a number of stylesheets used all imported by the main template_css.css. We will discuss that more later in the tutorial.

The index.php

What actually is in an index.php file? It is a combination of (X)HTML and PHP that determines everything about the layout and presentation of the pages.

First we will look at a critical part of achieving valid templates, the DOCTYPE at the top of the index.php file. This bit of code that code goes at the very top of any web page. At the top of our page we have this in our template:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml"
lang="" xml:lang="">

A web page DOCTYPE is part of the fundamental components of who a web page is shown by a browser, specifically, how that browser interprets CSS. To give you a sense, an observation from alistapart.com says:

[information on W3C's site about doctypes is] "written by geeks for geeks. And when I say geeks, I don�t mean ordinary web professionals like you and me. I mean geeks who make the rest of us look like Grandma on the first day She�s Got Mail.�"

Anyway, there are several doctypes you can use. Basically, the doctype tells the browser how to interpret the page. Here the words "strict" and "transitional" start getting floated around (float:left and float:right usually). Essentially, ever since the WWW started, different browsers have had different levels of support for CSS. This means for example, that Internet Explorer won't understand the "min-width" command to set a minimum page width. To duplicate the effect you have to use "hacks" in the CSS.

Strict means the html (or xhtml) will be interpreted exactly as dictated by standards. A transitional doctype means that the page will be allowed a few agreed upon differences to the standards.

To complicate things, there is something called "quirks" mode. If the doctype is wrong, outdated, or not there, then the browser goes into quirks mode. This is an attempt to be backwards compatible, so Internet Explorer for example, will render the page pretending as if it was IE4.

Unfortunately, people sometimes end up in quirks mode accidentally. It usually happens two ways:

  • They use the doctype declaration straight from the WC3 web page, the link ends up as:
    DTD/xhtml1-strict.dtd
    Except this is a relative link on the WC3 server. You need the full path as shown above.
  • Microsoft set up IE6 so you could have valid pages, but be in quirks mode. This happens by having an "xml prolog" put before the doctype.
    <?xml version="1.0" encoding="iso-8859-1"?>

The part about IE6 quirks mode is important. In this tutorial we will only be designing for IE6+, so we will make sure that its running in standards mode. This will minimize the hacks we have to do later on. The xml prolog isn't essential anyway, we'll be taking note of future releases of Joomla and be leaving it off.

Making a page standards compliant, where you see "valid xhtml" at the bottom of the page does not mean really difficult coding, or hard to understand tags. It merely means that the code you use matches the doctype you said it would. That's it! Nothing else. Designing your site to standards can on one level be reduced to saying what you do, and then doing what you say.

Some useful links:

What else is in index.php?

Let's look at the structure of the header first, we want to be as minimal as possible, but still have enough for a production site. The header information we will use is:

<?php defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' ); ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" lang="" xml:lang=""
<head>
<meta http-equiv="Content-Type" content="text/html; " />
<?php
if ($my->id) { initEditor(); } ?>
<?php mosShowHead(); ?>
<script type="text/javascript"> </script>
<!--https://www.bluerobot.com/web/css/fouc.asp-->
<link href="/templates//css/template_css.css" rel="stylesheet" type="text/css" media="screen" />
</head>

What does all that mean?

<?php defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' ); ?>

Makes sure that the file isn't being accessed directly.

<?php defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' ); ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" lang="" xml:lang=""
<head>

We talked about this above. The "" is pulling the language from the site global configuration.

<meta http-equiv="Content-Type" content="text/html; " />

What character set we are using, _ISO is a special constant defining the character set encoding to use.

<?php if ($my->id) { initEditor(); } ?>

This is a script variable that is non-zero if a user is logged in to your site. If a user is logged in then the nominated WYSIWYG Editor is pre-loaded. You may, if you wish, always pre-load the Editor, but generally an anonymous visitor will not have the need to add content. This saves a little script overhead for normal browsing of your site.

<?php mosShowHead(); ?>

Header stuff that is set in the global configuration again. It includes the following tags (in a default installation):

  • <title>A Complete Guide to Creating a Joomla Template </title>
  • <meta name="description" content="Installing Joomla, doctype and the blank joomla template" />
  • <meta name="keywords" content="installing joomla, joomla doctype, blank joomla tempate" />
  • <meta name="Generator" content="Joomla! - Copyright (C) 2005 Open Source Matters. All rights reserved." />
  • <meta name="robots" content="index, follow" />
  • <link rel="shortcut icon" href="/images/favicon.ico" />

<script type="text/javascript"> </script>

To stop a bug, that being a flash of un-styled content. Details courtesy of Blue Robot. Note this can be any script file, so if we add one, we can remove this line.

<link href="/templates//css/template_css.css" rel="stylesheet" type="text/css" media="screen" />

This line links to the CSS file for the template. The PHP code <?php echo $cur_template; ?> will return the name of the current template. This makes this line "portable". When you create a new template you can jsut copy it (along with the whole head code) and not worry about editing anything.

As you will see later, in the temmplate_css.css file, we will use @import as a way to stop the site breaking with Netscape 4. Users of very old browsers won't be able to get the CSS sheet so will see our neat un styled content. If you wanted to cater to these older browsers, we would have too many CSS hacks, so we do this.

A blank joomla template body

This will be very very easy! Ready?

<body>
<!-- 1 --><?php echo $mosConfig_sitename;?>
<!-- 2 --><?php mospathway()?>
<!-- 3 --><?php mosLoadModules('top');?>
<!-- 4 --><?php mosLoadModules('left');?>
<!-- 5 --><?php mosMainBody();?>
<!-- 6 --><?php mosLoadModules('right');?>
<!-- 7 --><?php include_once( $mosConfig_absolute_path .'/includes/footer.php' );?>
</body>
</html>

We have in a reasonably logical order:

  1. name of the site
  2. the pathway
  3. top module
  4. left modules
  5. main content
  6. right modules
  7. the default footer module

The goal is to try and come as close to semantic markup as possible. From a web point of view, it means a page can be read by anyone, a browser, a spider or a screen reader. Semantic layout is the cornerstone of accessibility.

Now its worth noting that what we have here really is only the potential for semantic layout. If one were to go ahead and put random modules in random locations, then you would have a mess. An important consideration for CMS sites, a template is only as good as the population of the content. It is this that often trips designers up when trying to validate their site.