10. The index.php: The Heart of the Matter
Throughout the last few chapters I have repeatedly mentioned that the index.php file is the central control file of a Joomla! template. It takes on the task of setting patterns for the content created by the system and is the first template file used by the system.
The index.php file integrates the actual content, controls which modules are positioned where and when, combines the CSS files, and gives the template its unique look. It has the file extension .php, but it actually contains a mixture of HTML elements and PHP code. The HTML is responsible for the general page structure. The PHP integrates dynamic content.
Every Web designer who knows HTML will quickly be able to see the structure of a page by looking soley at the HTML code and ignoring the PHP code. But unfortunately, you cannot get by without PHP.
The code of the beez_20 template is quite complex, but I’m going to explain it to you from top to bottom. Please open the index.php file in the templates/beez_20 folder and have a look at it in an editor with syntax highlighting.
The Document Head
We start deconstructing the beez_20 template by looking at the document head in the index.php file, that part of the HTML that comes in the <head> section. Before we get to the actual <head> section, we have some Joomla! housekeeping to take care of as well as the task of defining the type of HTML we will use.
Safety First: Security
Even if you are Web designer who would rather work with HTML and CSS than PHP, believe me, a little bit of PHP can actually be fun. So let’s have a go at it.
In every Joomla! file with a name that ends with .php, you will see this at the beginning:
<?php
// no direct access
defined( '_JEXEC' ) or die;
This is a security feature internal to Joomla!. Specifically, it checks whether or not the constant JEXEC is set. As soon as someone surfs to a Joomla! site, this constant is set and checked repeatedly. This check prevents someone from outside gaining direct access to this file.
Which Document Type?
The Web speaks HTML. The first statement in each HTML document is the specification of the markup language used; its grammar is determined by the doctype declaration.
If you do not change the HTML output in the template (as described in Chapter 14, “Designing Default Output Individually”), but use the default output of Joomla!, you should choose XHTML Transitional:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
From version 1.6, you can also use Strict:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
beez5 even enables you to use HTML5 with the nice and simple declaration:
<!Doctype html>
As mentioned in Chapter 3, “CSS and HTML—Getting the Basic Structure into Shape,” it makes sense to use XHTML Transitional because of the editors packaged with Joomla!.
HTML Language Indicator
After the document specification, you will find further details on HTML itself:
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo
$this->language; ?>" lang="<?php echo $this->language; ?>"
dir="<?php echo $this->direction; ?>"
xmlns refers directly to the markup language used, and xml:lang specifies the language used in the document. dir, the abbreviation for direction, indicates the Western reading direction, from left to right: ltr (left to right).
Joomla! can also display Arabic or Hebraic sites, for example, which have content written from right to left. These would need the specification right to left: rtl.
The language used is determined in the Language Manager. Since Joomla! can manage multilingual content, the language itself is stored as a variable and can adapt dynamically to the language you enable.
jdoc: include type:head
jdoc is the abbreviation for Joomla! document and part of the Joomla! language range. If you want to know more, <jdoc:include type="head" /> integrates the functions of the file libraries/joomla/document/html/renderer/head.php.
The first line in every Joomla! template directly after the opened <head> area is this:
<head>
<jdoc:include type="head" />
With the statement <jdoc:include /> you can integrate not only the page head into the template but also the modules used and the actual content. The statements differ only by the specified type. I discuss them in more detail later.
What does <jdoc:include type="head" /> actually do? It automatically integrates a large part of the document head, so that you barely need to do anything to the design at this point. These are the statements that are added by the jdoc statement.
base
<base href="http://localhost/joomlabuch_installation/index.php" />
This information in the href attribute helps Joomla! generate search engine–friendly URLs. The base element is almost as old as HTML itself. It generally refers directly to the root directory. In Joomla! it is not used completely cleanly, for technical reasons, because it is part of the Joomla! routing. If you are in a category view for example, the base does not always refer to the root directory but to the category that the system is currently in.
The base element appears in the document head only if the search engine–friendly URLs are enabled in the Joomla! configuration.
The Character Set: UTF-8
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
This statement indicates the character set used in the document. Joomla! uses UTF-8. The browser needs to know which character set it should use to correctly display the characters.
For a long time, character sets could contain only a maximum of 256 characters. There are so many different character sets because the different languages of the world use different characters. Just think of umlauts in German or accents in French: characters that do not appear in many other languages. Depending on the language used, you need to specify a different character set in the head of the HTML file.
Because this is complicated and laborious, UTF-8 was developed. UTF-8 is a universal character set that can process up to 1,114,112 characters.
Some Web servers still have problems with displaying UTF-8, but it is the character set of the future. Joomla! uses UTF-8, and so it is well prepared for this future.
Metadata for Google and Company
As you probably know, you can include global details regarding the metadata in the Joomla! configuration; they are then added, automatically, in the document head. Individual articles can also contain these details.
<meta name="robots" content="index, follow" />
This data refers to the behavior of the search engine robots that frequently scan your pages for relevant information. The keyword index gets the robots to index a page. follow permits them to follow all links on the page. But if these statements were not present in the document head, the robots would still behave in the same way, so using these statements makes sense only if you want to stop the robots from indexing the page. You stop them with the keywords noindex and nofollow.
<meta name="description" content="Joomla! - the dynamic portal engine
and content management system" />
Describing the content of your site can pose a challenge even for a professional copywriter. It should be as precise and descriptive as possible, should not contain more than two or three sentences, should contain relevant keywords, and should attract future visitors with its wording. Some search engines display up to 250 characters, and others cut off the text after just 80 characters.
<meta name="keywords" content="joomla, Joomla" />
The relevance of the meta keywords has rapidly decreased in recent years. Opinions among search engine experts on the significance of the keywords currently vary greatly. While some believe the keywords should be the same on every page, others think that Google judges this negatively.
The experts agree that keyword spamming (using a great number of keywords) has a negative effect. You will not go wrong if you pick keywords carefully and make sure they are relevant to the contents of your page.
Generator
<meta name="generator" content="Joomla! 2.5 - Open Source Content
Management" />
The information generated by this statement is of little or no interest to the person looking at the Web site. Its purpose is to help people search the Web more easily and to find out how many pages were created with Joomla! and where they can be found.
Document title
<title>Joomla!</title>
The document title (title) is one of the most important pieces of information in the document head. The browser displays it at the very top of the browser bar and tells the user where he or she currently is. It should be descriptive and clearly worded because, for example, this document title is the first thing a blind person will hear when surfing with the appropriate software.
For Google it also has special significance. If someone searches for a specific term, Google first looks for Web sites that have this term in the URL. Then the search engine uses the contents of the document title and later the actual content of the site.
Joomla! generates the document titles dynamically. Depending on whether you have enabled or disabled search engine–friendly URLs, the document titles are composed of the page title, and the category and/or the heading of the article. In version 1.6 you can set this document title for each menu item individually—a new feature that many developers will certainly appreciate.
RSS Feeds
Joomla! makes the contents of a page available as RSS (Really Simple Syndication) feeds as well. It is done in the index.html file by the statements:
<link
href="/joomlabuch_installation/index.php?format=feed&type=rss"
rel="alternate" type="application/rss+xml" title="RSS 2.0" />
and:
<link
href="/joomlabuch_installation/index.php?format=feed&type=atom"
rel="alternate" type="application/atom+xml" title="Atom 1.0" />
RSS is a platform-independent, XML-based format that exchanges information in a very simple way. Unlike HTML pages, RSS files are structured purely logically. Content is output without any formatting and can be taken over by other applications depending on how you want to use it.
With RSS readers you can simply subscribe to news from different providers in an application. You can find an overview of different RSS readers at http://blogspace.com/rss/readers.
Atom is also a platform-independent, XML-based, exchange format in competition to be the successor to RSS. Whereas the contents of the RSS feed can contain pure text and HTML without having to specify clearly that it is HTML, Atom offers the option of marking contents as HTML code. The advantage is that the processing program knows what it is dealing with and can react accordingly.
Favicon
The favicon referenced in the following link is also added automatically. It appears as the little icon next to the URL in the browser address bar:
<link href="/joomlabuch_installation/templates/beez_20/favicon.ico"
rel="shortcut icon" type="image/vnd.microsoft.icon" />
Integrating CSS and JavaScript
Each template needs one or more CSS files to design its content. Almost all modern sites also integrate JavaScript or whole JavaScript libraries to enable certain behavior of individual elements. The following statement integrates the CSS file layout.css, which is located in the CSS folder:
<link rel="stylesheet" href="<?php echo
$this->baseurl ?>/templates/beez_20/css/layout.css"
type="text/css" media="screen,projection" />
This statement does the same as those you may have used to call external CSS files in static Web sites. The only difference is that it uses PHP variables to create the right address to the CSS file. The following code always references the current base path of the relevant Joomla! installation, which makes the template more flexible:
$this->baseurl
If you integrate JavaScript files, you will also use this code. Here’s an example from an early Beez template:
<script type="text/javascript" src="<?php echo $this->baseurl ?>
/templates/beez_20/javascript/hide.js"></script>
You simply refer to the template via the template name. If you like, you can also use the Joomla! variable $this->template, which is particularly useful if your template is also intended to serve as a pattern for other templates. The current Beez templates use this variable so that if you copy the file to use as a base for your template, you don’t need to change the folder name to your template folder name.
<link rel="stylesheet" href="<?php echo
$this->baseurl ?>/templates/<?php echo
$this->template; ?>/css/layout.css"
type="text/css" media="screen,projection" />
Integrating MooTools
MooTools is a JavaScript framework with a multitude of functions that can save you a lot of work when programming your own scripts (see Chapter 6, “MooTools”).
The MooTools framework is not exactly small, so loading it does not make sense if you do not really need it. But if you do want to use it in your template, you can easily do so by inserting a line of PHP code:
<?php JHtml::_('behavior.framework', true); ?>
You may still remember this statement:
JHTML::_('behavior.mootools')
It has now been replaced by <?php JHtml::_('behavior.framework', true); ?>.
Reading Direction from Right to Left
As mentioned previously, Joomla! can manage multilingual content. Depending on the target group and area of use, it can be necessary to optimize your template and its display for use, say, in Arabic-speaking countries. For designers from the West, this is not easy, because in most cases, you cannot actually read what you can see. We are so formed by our Western direction of reading that our creativity can desert us in such cases.
If you need to adapt your CSS for a right-to-left language, it can sometimes help to place a mirror in front of the monitor so you can get a feel for the proportions.
Technically, the integration is simple: the Joomla! framework automatically provides the currently used reading direction in the variable $this->direction. You just have to fetch it and then adjust accordingly.
<?php if ($this->direction == 'rtl') : ?>
<link rel="stylesheet" href="<?php echo
$this->baseurl ?>/templates/beez_20/css/template_rtl.css"
type="text/css" />
<?php endif; ?>
And Off We Go: The Body
The basic framework of our template is still the HTML code that we determine. It is the basis for the organization of the content and, together with the CSS files, determines the visual design.
You can build your HTML here as you are used to and use dynamic content only in certain places. With PHP you can deal with the presence of certain elements and page components and then adapt the source code accordingly. A number of templates use this option because it is significantly more flexible.
So what can be dynamically inserted?
• The actual content (the Joomla! component)
• Modules
• Error messages/system notices
Perhaps I should add a quick side note on how components and modules actually differ: while both are extensions, components are significantly more complex and have a lot more program logic. Modules are usually responsible for outputting some content. The exception is the login, because it expects input.
As mentioned before,
<jdoc:include.... />
is part of the Joomla! internal language range and integrates both components and modules.
<jdoc:include type="component" />
is of central importance and integrates the actual content. Depending on the menu structure, the text content can be output here (com_content) or, for example, in the form of the contact component.
The statement type="component" may be used only once in a file.
With the following statement you can integrate modules:
<jdoc:include type="modules" name="position-12" />
This code loads all modules to be displayed on position-12.
Integrating modules is discussed in Chapter 13, “Modules—Dynamics within the Presentation.”
The last types of dynamic content that can be added are the error messages and notices. Anyone who uses Joomla! will certainly have come across error messages or notices. If not, try logging in to the front end with an incorrect password. You will see a screen similar to that shown in Figure 10.1.
Figure 10.1. Notice displayed when using an incorrect password
You will see an error message. The following statement is responsible for the error message:
<jdoc:include type="message" />
The visual design of the error messages is done using CSS. The CSS instructions can be found in the general.css file of the included templates. You can easily inspect them with Firebug and adapt them as you wish. For more information, see Chapter 15, “The System Template: Adapting and Modifying Output.”