Creating Pure CSS Templates in Joomla!

This chapter is from the book 

Creating a Simple Template: CSSTemplateTutorialStep1

To understand the contents of a template, let's start by looking at a blank Joomla template.

Template File Components

This section reviews the manual process of setting up template files. Normally, you would install the template using the Joomla installer, which takes care of all these steps.

When constructing your own templates, you need to set up several files and folders in a coordinated manner. A template needs to contain various files and folders. These files must be placed in the /templates/ directory of a Joomla installation, each in a folder designated for that template. If you had two templates installed called Element and Voodoo, your directory would look something like this:

/templates/element
/templates/voodoo

Note that the directory name for a template must be the same as the name of the template—in this case, element and voodoo. These names are case-sensitive and shouldn't contain spaces.

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

/element/templateDetails.xml
/element/index.php

These filenames and locations must match exactly because this is how they are called by the Joomla core script. The first of these is the template XML file: templateDetails.xml.

This is an XML-format metadata file that tells Joomla what other files are needed when it loads a web page that uses this template. (Note the uppercase D.) 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 unpacking and installing a template when using the extension installer in the administrative backend.

The second key file is the primary template file that generates pages, index.php. This file is the most important in a Joomla template. 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 HTML/XHTML.

Almost all templates use additional files. It is conventional (although not required by the Joomla core) to name and locate them as shown here:

/element/template_thumbnail.png
/element/css/template.css
/element/images/logo.png

These are just examples. Table 9.1 lists the files commonly found in a template.

Table 9.1. Core Files Needed for a CSS-Based Template

/templatename/folder/filename	Description
/element/template_thumbnail.png	A web browser screenshot of the template (usually reduced to around 140 pixels wide by 90 pixels high). After the template has been installed, this functions as a preview image that is visible in the Joomla administration Template Manager and also the template selector module in the frontend (if used).
/element/css/template.css	The CSS of the template. The folder location is optional, but you have to specify where it is in the index.php file. You can call it what you like. Usually, the name shown is used, but you will see later that there are advantages to having other CSS files, too.
/element/images/logo.png	Any images that go with the template. Again for organization reasons, most designers put them in an images folder. Here we have an image file called logo.png as an example.

templateDetails.xml

The templateDetails.xml file acts as a manifest, or packing list, that includes a list of all the files or folders that are part of the template. It also includes information such as the author and copyright. Some of these details are shown in the administrative backend in the Template Manager. An example of an XML file is shown here:

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="template">
      <name>TemplateTutorial15</name>
      <creationDate>August 2007</creationDate>
      <author>Barrie North</author>
      <copyright>GPL</copyright>
      <authorEmail> compassdesigns@gmail.com </authorEmail>
      <authorUrl>www.compassdesigns.net</authorUrl>
      <version>1.0</version>
      <description>First example template for Chapter 9 of the Joomla Book</description>
      <files>
            <filename>index.php</filename>
            <filename>templateDetails.xml</filename>
            <filename>favicon.ico</filename>
            <folder>css/</folder>
            <folder>images/</folder>
            <folder>js/</folder>
      </files>
      <positions>
            <position>user1</position>
            <position>top</position>
            <position>left</position>
            <position>banner</position>
            <position>right</position>
            <position>footer</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>
            </param>
      </params>
</install>

Let's look at what some of these lines mean:

• <install version="1.5" type="template">—The contents of the XML document are instructions for the backend installer. The option type="template" tells the installer that you are installing a template and that it is for Joomla 1.5.
• <name>TemplateTutorial15</name>—This line 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, such as spaces. If you're installing manually, you need to create a directory whose name is identical to the template name.
• <creationDate>August 2007</creationDate>—This is the date the template was created. It is a free-form field and can be anything such as May 2005, 08-June-1978, 01/01/2004, and so on.
• <author>Barrie North</author>—This is the name of the author of this template—most likely your name.
• <copyright>GPL</copyright>—Any copyright information goes in this element.
• <authorEmail>compassdesigns@gmail.com</authorEmail>—This is the email address at which the author of this template can be reached.
• <authorUrl>www.compassdesigns.net</authorUrl>—This is the URL of the author's website.
• <version>1.0</version>—This is the version of the template.

• <files></files>—This is a list of various files used in the template. The files used in the template are laid out with <filename> and <folder> tags, like this:

  <files>
       <filename>index.php</filename>
       <filename>templateDetails.xml</filename>
       <filename>favicon.ico</filename>
   <folder>css/</folder>
   <folder>images/</folder>
   <folder>js/</folder>
  </files>

  The "files" sections contain all generic files, such as 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> tags. You can also include whole folders, such as an image folder, by using the <folder> tag.

• <positions></positions>—This shows the module positions available in the template. It is the list of page locations, such as top, left, and right, defined in the template in which modules can be set to appear, using the Position drop-down of the Module Manager. The position names in this list must precisely match the PHP code that generates content for each listed position inside index.php.
• <params></params>—This section describes the parameters that can be set in the backend and passed as global variables to allow advanced template functions, such as changing the color scheme of the template.

index.php

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

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

<?php
// no direct access
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">

The first PHP statement simply makes sure the file is not accessed directly for security.

A web page DOCTYPE is one of the fundamental components of how a web page is shown by a browser—how various HTML tags are handled and, more importantly, how the browser interprets CSS. The following observation from alistapart.com should give you further understanding:

• [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.

You can use several DOCTYPEs. Basically, the DOCTYPE tells the browser what version of HTML was used to design the page, whether it has some legacy code or also contains XML, and therefore how to interpret the page. Here the words strict and transitional start getting floated around (float:left and float:right usually) to indicate whether legacy code was included. Essentially, ever since the web started, different browsers have had different levels of support for various HTML tags and versions of CSS. For example, Internet Explorer won't understand the min-width command to set a minimum page width. To duplicate an effect so that it displays the same in all browsers, you sometimes have to use browser-specific "hacks" in the CSS that make up for shortcomings in each browser's adherence to the published standards.

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 from the standards (for example, continued use of discontinued tags).

To complicate things, there is something called "quirks" mode. If the DOCTYPE is wrong, outdated, or not there, the browser goes into quirks mode. This is an attempt to be backward compatible, so Internet Explorer 6, for example, will render the page as if it were Internet Explorer 4.

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

• They use the DOCTYPE declaration straight from the WC3 web page, and the link ends up as DTD/xhtml1-strict.dtd, which is a relative link on the WC3 server. You need the full path, as shown earlier.
• Microsoft set up Internet Explorer 6 so you could have valid pages but be in quirks mode. This happens when you have an xml declaration put before instead of after the DOCTYPE.

Next is an XML statement (after the DOCTYPE):

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this-> language; ?>" lang="<?php echo $this->language; ?>" >

The information I just gave you about Internet Explorer 6 quirks mode is important. In this chapter, you're designing only for Internet Explorer 6 and later, and you need to make sure that it's running in standards mode to minimize the hacks you have to do later on.

Let's look at the structure of the index.php file header; you want it to be as minimal as possible but still have enough for a production site. The header information you will use is as follows:

<?php
// no direct access
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; ?>" >

<head>

<jdoc:include type="head" />

<link rel="stylesheet" href="templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="templates/system/css/general.css" type="text/css" />
<link rel="stylesheet" href="templates/<?php echo $this->template ?> /css/template.css" type="text/css" />

</head>

What does all that this?

We have already discussed the implications of the DOCTYPE statement in the index.php file. The <?php echo $this->language; ?> code pulls the language from the site's language setting in Global Configuration.

The next line is for including more header information:

<jdoc:include type="head" />

This code snippet inserts in the generated page all of the header information that is set in the Global Configuration. In a default installation, it includes the tags shown here:

  <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <meta name="robots" content="index, follow" />
  <meta name="keywords" content="joomla, Joomla" />
  <meta name="title" content="Home Page" />
  <meta name="author" content="Administrator" />
  <meta name="description" content="Joomla! - the dynamic portal engine and content management system" />
  <meta name="generator" content="Joomla! 1.5 - Open Source Content Management" />
  <title>Home Page</title>
  <link href="/templates/yourtemplate/favicon.ico" rel="shortcut icon"
type="image/x-icon" />


  <script type="text/javascript" src="https://localhost//yoursite/media/system/js/mootools.js"></script>
  <script type="text/javascript" src="https://localhost//yoursite/media/system/js/caption.js"></script>

Much of this header information is created on-the-fly, specific to the page (article) that someone is viewing. It includes a number of metatags, the favicon, any RSS-feed URLs, and some standard JavaScript files.

The last lines in the header provide links to CSS files for Joomla-generated pages in general and also in this template:

<link rel="stylesheet" href="templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="templates/system/css/general.css" type="text/css" />
<link rel="stylesheet" href="templates/<?php echo $this->template ?>/css/template.css" type="text/css" />

The first two files, system.css and general.css, contain some generic Joomla styles. The last one is all the CSS for the template, here called template.css. The PHP code <?php echo $this->template ?> returns the name of the current template. Writing it in this way rather than writing the actual path makes the code more generic. When you create a new template, you can just copy this line (along with the whole header code) and not worry about editing anything.

The template CSS can include any number of files, such as conditional ones for different browsers and for different media, such as print. Adding the following code detects and adds an additional CSS file that targets the quirks of Internet Explorer 6:

<!--[if lte IE 6]>
<link href="templates/<?php echo $this->template ?>/css/ieonly.css" rel="stylesheet" type="text/css" />
<![endif]-->

The next example is part of a technique for using a template parameter. In this case, a color scheme selected as a parameter in the Template Manager is loading a CSS file that has the same name as the selected color:

<link rel="stylesheet" href="templates/<?php echo $this->template ?>/css/<?php echo $this->params->get('colorVariation'); ?>.css" type="text/css" />

It might generate this:

<link rel="stylesheet" href="templates/voodoo/css/blue.css" type="text/css" />

The Joomla! Page Body

Now that the <head> part of the page is set up, we can move on to the <body> tag. Creating your first template will be easy! Ready?

To create the template, all you need to do is use Joomla statements that insert the contents of the mainbody, plus any modules you want:

<body>
<?php echo $mainframe->getCfg('sitename');?><br />
<jdoc:include type="modules" name="top" />
<jdoc:include type="modules" name="left" />
<jdoc:include type="modules" name="breadcrumbs" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="right" />
<jdoc:include type="modules" name="footer" />
</body>

The template contains the following, in reasonably logical viewer order:

• The name of the site
• The top modules
• The left modules
• A breadcrumb bar
• The main content
• The right modules
• The footer modules

At this point (if you preview it), the site does not look very awe inspiring (see Figure 9.3).

You want to come as close to semantic markup as possible. From a web point of view, this means a page can be read by anyone—a browser, a spider, or a screen reader. Semantic layout is the cornerstone of accessibility.

Notice that you use the first of a number of commands specific to Joomla to create this output:

<?php echo $mainframe->getCfg('sitename');?><br />
<jdoc:include type="modules" name="top" />
<jdoc:include type="modules" name="left" />
<jdoc:include type="modules" name="breadcrumbs" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="right" />
<jdoc:include type="modules" name="footer" />

The PHP echo statement simply outputs a string from the configuration.php file. Here, you use the site name; you could as easily use the following:

The name of this site is <?php echo $mainframe->getCfg('sitename');?><br />
The administrator email is <?php echo $mainframe->getCfg('mailfrom');?><br />
This template is in the <?php echo $this->template?> directory<br />
The URL is <?php echo JURI::base();?>

The jdoc statement inserts various types of XHTML output, from either modules or components.

This line inserts the output from a component. What component it is will be determined by the linked menu item:

<jdoc:include type="component" />

This line inserts the output for a module location:

<jdoc:include type="modules" name="right" />

This line generates content for all modules that have their position set to right. The content generated for those modules is placed in the page in the order set in the Order column of the Module Manager. This is the full syntax:

<jdoc:include type="modules" name="location" style="option" />

We'll look at the various options for styles in the section "Modules in Templates," later in this chapter.