8. Creating Your Own Simple Joomla! Template
After Joomla! itself and your site content, templates are the most important aspect of your Joomla! site. In this chapter we will explain the details of templates in more depth by taking you through the steps of creating your own simple template. To build the template we will take advantage of Twitter Bootstrap, which forms the basis of the Joomla! user interface package beginning with Joomla! 3. However, the concepts and procedures are exactly the same whether or not you use Bootstrap.
Basic Template Structure
Web pages that you see in your browser are made up of HTML (HyperText Markup Language) code, which in turn works with other files, such as images, Cascading Style Sheets (CSS), and JavaScript (js) files. PHP is a programming language that is designed to make creating dynamic pages easier. In Joomla!, templates, and specifically the index.php file of a template, are used by PHP to provide the basic structure for the HTML in a page. If you look at an index.php file for a template, such as Beez3, you will see that it is quite complex, containing many elements. Commercially available templates are often even more complex. Before we go deeper into making and working with templates, it is useful to review the basic structure of an HTML page and then of a template index.php file.
Tip
To follow along with this step by step, go to your /template folder and create a new folder, ourtemplate, within it. You will do this using your File Manager in Cpanel or the interface you use on your server, or if you are working on a local installation, simply use your normal procedure for creating folders and files. Once you have created the index.php file and the templateDetails.xml file as described below, you can use the Discover method to install the template.
You can see an example of the most minimal possible HTML page in the index.html file that is found in every Joomla! folder. If you navigate using your browser to http://mydomain.com/components/index.html, you will see a blank page. These files contain this code:
<html>
<body>
</body>
</html>
Copy this file to the templates/ourtemplate folder. This is the absolute minimum HTML page you can have, but you should really add two additional pieces, a head tag and a document type. The head tag consists of <head></head> and goes between the <html> tag and the body tag:
<html>
<head>
</head>
<body>
</body>
</html>
We use indenting to help make a file readable and to make sure we have not forgotten any tags. Create an index.php file in the same folder. This will contain the exact same text for now. Now if you browse to http://mydomain.com/templates/ourtemplate/index.php, you will have a blank page.
Web pages are rendered with HTML, but there are actually a number of variations of HTML. Newer templates such as those for Joomla! 3 are usually HTML5. In Joomla! 2.5, most Joomla! templates use XHTML, or Extensible HyperText Markup Language. You need to tell the browser which is being used. This is done using a !DOCTYPE tag, so you will almost always see these in the index.php file. They define what set of standards will be used to validate the HTML (or XHTML) on your page. Most Joomla! 3 templates use a plain HTML doc type. Most Joomla! 2.5 templates use what is known as the XHTML 1.0 Transitional standard, but there are other standards available. Therefore, a tag is usually included to indicate the type.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
</head>
<body>
</body>
</html>
For Joomla! 3 this will normally be
<!DOCTYPE html>
<html>
<head>
</head>
<body>
</body>
</html>
Tip
An index.html file is put in every folder in order to keep curious people from seeing what files your folder contains, including what extensions you have installed. This is a simple security measure that is considered a best practice for Joomla! At some point this may change, but it will never hurt for you to include these files.
There are several document types you can choose from, and a number of options are available from the www.w3.org Web site. That Web site also includes a validation service which will check to see if your site complies with the standards for that document type.
This is the point at which Joomla! index.php files start to differ in more important ways from index.html files.
Adding Joomla! Content
If we were doing simple HTML, the next thing we would do would be to add a <title></title> tag in the header. This would not define the title on the page you see in the main part of your browser, but instead the title you see in bookmarks and on the tabs or similar display areas of the browser. So a simple index.html page would look like this:
<!DOCTYPE html>
<html>
<head>
<title>My Site Name</title>
</head>
<body>
</body>
</html>
In contrast to a plain HTML page, in a Joomla! template PHP will pull the title from the information you have entered elsewhere, most simply from the Site Name setting in the Global Configuration. It will do this by using something called a jdoc with this tag:
<jdoc:include type="head" />
So now our index.php will look like this:
<!DOCTYPE html>
<html>
<head>
<jdoc:include type="head" />
</head>
<body>
</body>
</html>
This will still render a blank page in your browser. Next, we want to add content. In an HTML page you would do this by adding something like
<h1>This is a Web Page Headline</h1>
<p>This is a paragraph of text.</p>
In Joomla!, of course, we get the text we want to display from the articles and other content we have created using components. So instead of actually typing in each page of text, we include a second kind of document, a component, by adding <jdoc:include type="component" />. Now our template index.php looks as shown here:
<!DOCTYPE html >
<html>
<head>
<jdoc:include type="head" />
</head>
<body>
<jdoc:include type="component" />
</body>
</html>
Adding templateDetails.xml
To make our template work, we need to do one additional step which is to create a file called templateDetails.xml, also in the /templates/ourtemplate folder.
The smallest possible templateDetails.xml file consists of
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 3//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.6/template-install.dtd">
<extension version="3" type="template" client="site">
<name>ourtemplate</name>
</extension>
client="site" means that this template is used for the front end, not the administrator. Of course, more complex templates will include many additional elements.
As with index.php, this file gives the !DOCTYPE but in this case it refers to a standard specifically set up for Joomla! templates.
Tip
To use Discover installation, go to the Extension Manager, then the Discover page. Click on the Discover icon on the toolbar. ourtemplate will appear on the list if your two files (index.php and templateDetails.xml) are present (as shown in Figure 8.1). Select the template and click on the Install icon. Browsing to the Template Manager, you will see that ourtemplate is now installed with a default template style, as shown in Figure 8.2.
Figure 8.1. Discover view in the Extension Manager with ourtemplate discovered
Figure 8.2. Template Manager Styles view with ourtemplate installed
At this point if the template is installed (you can do this with the Discover installation method if both your index.php and templateDetails.xml files are in place) and we have made its style the default style, we start to see content on our pages when viewed in the browser. The content will be the same content you have in your site components. Figure 8.3 shows our home page using our template at this point.
Figure 8.3. A page rendered with the simplest possible Joomla! template
Tip
How does Joomla! know what content to display?
If you turn off search-engine-friendly URLs, you will see that a Joomla! URL typically appears like this example for a single article:
http://mydomain.com/index.php? option=com_content&view=article&id=5
This translates into: Display using the Content component, Article view; the article with ID of 5 indicates which specific article to display.
Adding Module Positions
Tip
Since we will be working with module positions, at this point it makes sense to have modules in each position so that you can see how they work. If you have installed sample data for Joomla!, you will have many instances of modules in the Module Manager and can simply assign the modules to each of the empty positions. You will want to create instances of modules (use anything besides Related Items and Syndication) and assign them to each position. Assign a Menu module to position-1 and a Search or Smart Search module to position-0. If you want to make it easy to follow, you can make the module titles match the names of the positions to which they are assigned.
Next, we want to add some modules to our pages. As you already know, each module is assigned to a specific position. So the most common way to add modules to a page is to add a jdoc with the type of modules:
<jdoc:include type="modules" name="position-1" />
If we have many positions, we add each one where desired. If we wish, we can put some before and some after the component:
<!DOCTYPE html >
<html>
<head>
<jdoc:include type="head" />
</head>
<body>
<jdoc:include type="modules" name="position-0" />
<jdoc:include type="modules" name="position-1" />
<jdoc:include type="modules" name="position-2" />
<jdoc:include type="modules" name="position-3" />
<jdoc:include type="modules" name="position-4" />
<jdoc:include type="modules" name="position-5" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="position-6" />
<jdoc:include type="modules" name="position-7" />
<jdoc:include type="modules" name="position-8" />
<jdoc:include type="modules" name="position-9" />
<jdoc:include type="modules" name="position-10" />
<jdoc:include type="modules" name="position-11" />
<jdoc:include type="modules" name="position-12" />
<jdoc:include type="modules" name="position-13" />
<jdoc:include type="modules" name="position-14" />
</body>
</html>
As shown in Figure 8.4, this will render your modules and component in one long column on your page. We’ll return later to making a more interesting-looking layout. Because there is no CSS styling, everything renders in a single column. The menu is present twice because we have two menu modules, the original in position-7 and the new one in position-1.
Figure 8.4. A page rendered with module positions added
Tip
Usually you do not need this many module positions. Also, it can be very useful to give the positions meaningful names such as “right-sidebar” or “top-navigation” once you have settled on locations for them.
You will also want to include <jdoc:include type="message" /> which is what puts messages such as “Article Successfully Saved” on the page. Usually you would put this above the component so that the message is easily visible to your site visitors.
There are two other jdoc types that are used less often. The first, type="installation", is used only when installing. The second, type="module", loads a single module using the name rather than the position. So if you know you always want to use a module called Search in a specific location, you can specify <jdoc:include type="module" name="search" />.
Adding Style Sheets
As you can see, the Web pages themselves are pretty boring at this point. They have simple Times Roman for a font, and the headings are twice the size of the print in the rest of the body. Links are blue and visited links are red. And the background is white. This is where the other part of the index.php—the head—comes in. The head can be used to include a file called a Cascading Style Sheet.
The idea of a style sheet comes from the print publishing world, where a style sheet is used to define elements of writing and page design so that each publication is consistent. For example, the New York Times Style Guide requires that a person’s last name always be preceded by a title (such as Mr., Miss, Dr., or President) and for many years was known for prohibiting the use of Ms. as a title. A style sheet in HTML won’t monitor your spelling or grammar, but it will allow you to control fonts, colors, widths, and other elements of your Web site. These style sheets are incorporated into your template by including them between the <head> and </head> tags. If we made a style sheet called template.css, we would put it in a folder inside our template called css, and then add it to our index.php file. Traditionally, pulling the CSS into the page would be done by inserting
<link rel="stylesheet"
href="<?php echo $this->baseurl ?>/templates/ourtemplate/css/template.css"
type="text/css" />
In this line, Joomla! is using information it has to find the location of the style sheet and load it for use in the rendered page. The PHP code $this->baseurl refers to the base URL for your site, which is usually http://mydomain.com but could be http://mydomain.com/site if your Joomla! installation is located in a folder called site instead of the root of your domain. In contrast, in a static HTML file, the href= would be followed by the full URL.
In Joomla! 3 templates this is usually done with this line of PHP code:
<?php $doc->addStyleSheet('templates/'.$this->template.'/css/template.css'), ?>
Add this line after <head>.
Doing this requires us to define $doc, and it also requires us to use PHP rather than HTML. In a template you tell the browser to use PHP. First, you can surround PHP code with these tags: <?php ?>. To define $doc we also need to add PHP. Traditionally this is done at the top of the index.php file, as part of a block of PHP that comes before everything else:
<?php
defined('_JEXEC') or die;
$doc = JFactory::getDocument();
?>
Complex templates often include a great deal of PHP in this block. The first line makes it so that your template will be executed only inside of Joomla! This is a good security measure especially as a template gets more powerful.
Many templates have multiple style sheets, including one for printing, print.css, specialized ones for specific browsers, and one to make the template work in right-to-left-reading languages. We will not cover these, but you can see examples in Beez3.
Joomla! 3 provides you with what you need for a basic template.css file in the file media/jui/css/bootstrap.css. Copy the whole contents of that file into your template.css file. Now your page is starting to have some style and will look like Figure 8.5.
Figure 8.5. A page rendered with Joomla!’s basic Bootstrap styling included as part of template.css
If your site will use a right-to-left language, you should also add this line:
JHtmlBootstrap::loadCss($includeMaincss = false, $this->direction);
We are going to add one more line to the top block of PHP code that will include the JavaScript from Bootstrap:
Jhtml::_('bootstrap.framework'),
At this point you should also copy the img folder and the fonts folder from the media/jui folder to your template (so that they are at the same level as the CSS).
Tip
Twitter Bootstrap is a CSS and JavaScript framework for designing Web sites. It is widely used and has been adopted by Joomla! to help make it easy for extension developers to design their work so that it integrates easily with the core of Joomla! and with other extensions and create a unified design. The Protostar template in Joomla! 3 is fully Bootstrap based.
You can learn more about Bootstrap at http://twitter.github.com/bootstrap/.
Working with the Grid System
Twitter Bootstrap builds in a grid system that divides the Web page into 12 equal-size columns. As we saw in Chapter 7, CSS controls the appearance of the page using a system of classes and IDs. In Twitter Bootstrap the class="span1" will make an entity such as a div one column wide, class="span2" will make it two columns wide, and so on. Remember that on a Joomla! Web page there is content from one component (such as Web links or contacts) and also usually one or more modules. We want to arrange these elements using the grid system. To see how this works, let’s make a left column with some module positions that has a span of 3, the component column that has a span of 6, and the right column that has a span of 3 by surrounding the jdoc statements with divs with the appropriate classes:
<div class="span3">
<jdoc:include type="modules" name="position-0" />
<jdoc:include type="modules" name="position-1" />
<jdoc:include type="modules" name="position-2" />
<jdoc:include type="modules" name="position-3" />
<jdoc:include type="modules" name="position-4" />
<jdoc:include type="modules" name="position-5" />
</div>
<div class="span6">
<jdoc:include type="component" />
</div>
<div class="span3">
<jdoc:include type="modules" name="position-6" />
<jdoc:include type="modules" name="position-7" />
<jdoc:include type="modules" name="position-8" />
<jdoc:include type="modules" name="position-9" />
<jdoc:include type="modules" name="position-10" />
<jdoc:include type="modules" name="position-11" />
<jdoc:include type="modules" name="position-12" />
<jdoc:include type="modules" name="position-13" />
<jdoc:include type="modules" name="position-14" />
</div>
Your home page will now look like Figure 8.6, which is more like what we would want to see in a Web page.
Figure 8.6. A page rendered with Joomla!’s basic Bootstrap styling with three columns defined
One advantage of using the Joomla! Bootstrap.css as a baseline is that it provides a large number of ready-made classes and IDs that can be used. For example, we can add class="site" to the body tag, which will bring in basic styles for front-end layouts (as opposed to class="admin", which is used for administrator templates). We also add divs with the class’s body and container around everything.
<div class="body">
<div class="container">
(existing positions and divs)
</div>
</div>
body is used to define certain basic characteristics for the whole site such as the base font for text, and container governs the area of the page that actually contains content. By default it will center the main content on the page and use a width of 940px. At this point the home page looks like Figure 8.7.
Figure 8.7. A page rendered with the body and container classes added
Next, we will divide the body area into three main rows—body-top, body-middle, and body-bottom—using divs.
Usually we want some modules across the top; typically a top menu and a search box would be located there. So let’s move position-0 and position-1 to a new row at the top of the page:
<div class="row body-top">
<div class="span8">
<jdoc:include type="modules" name="position-1" />
</div>
<div class="span4">
<jdoc:include type="modules" name="position-0" />
</div>
</div>
We made position-1 wider since our menu will usually be larger than the search box and Joomla! sites typically use position-0 for search. For the bottom we’ll make a row of three module positions evenly divided across the bottom of the page:
<div class="row body-bottom">
<div class="span4">
<jdoc:include type="modules" name="position-12" />
</div>
<div class="span4">
<jdoc:include type="modules" name="position-13" />
</div>
<div class="span4">
<jdoc:include type="modules" name="position-14" />
</div>
</div>
We will add some more commonly used rows. The Breadcrumb module is normally displayed horizontally above the main content of the page, so underneath our top row we will add a full-width row which will use position-2 for breadcrumbs:
<div class="span12 breadcrumb">
<jdoc:include type="modules" name="position-2" />
</div>
Notice that in this case we added the breadcrumb class. This will use the built-in breadcrumbs styling from Bootstrap that is in template.css. We similarly add nav and search as classes to the <div>s containing position-1 and position-0:
<div class="span8 nav">
<jdoc:include type="modules" name="position-1" />
</div>
<div class="span4 search">
<jdoc:include type="modules" name="position-0" />
</div>
Finally, we will want a space to put the header on the page, which will probably include the site name, an image, or other content. Because using a module in this position is very useful—for example, at times you may need to make an urgent announcement—we’ll put position-11 there.
Now we have the basic structure of the page.
If you refresh your home page, it will look like Figure 8.8.
Figure 8.8. The home page after the addition of top and bottom module rows, a breadcrumbs row, and a header row
One thing you may observe about the layout at this point is that the center of the page that contains the article is somewhat narrow, and if it were divided into several columns, as with a Blog layout, they would be extremely narrow. Also, if there were no modules in either the left or right columns, the page might look very narrow and a bit strange. To cope with this we can use PHP to collapse the columns if there are no modules in them on a specific page. Remember that you can control what modules appear on what pages using module assignments to specific menu items.
Near the top of the file, inside the initial block of PHP code, add
$middlespan = 'span6';
$left = true;
$right = true;
if ($this->countModules('position-3') == 0
AND $this->countModules('position-4') == 0
AND $this->countModules('position-5') == 0
AND $this->countModules('position-6') == 0
AND $this->countModules('position-7') == 0
AND $this->countModules('position-8') == 0
AND $this->countModules('position-9') == 0
AND $this->countModules('position-10') == 0):
$middlespan = 'span12';
$left = false;
$right = false;
elseif
($this->countModules('position-3') == 0
AND $this->countModules('position-4') == 0
AND $this->countModules('position-5') == 0):
$middlespan = 'span9';
$left = false;
elseif
($this->countModules('position-6') == 0
AND $this->countModules('position-7') == 0
AND $this->countModules('position-8') == 0
AND $this->countModules('position-9') == 0
AND $this->countModules('position-10') == 0):
$middlespan = 'span9';
$right = false;
endif;
Let’s take a look at what this does. First, it makes a PHP variable called $middlespan and sets it to 'span6', which is what we are using for the div containing the component. It also defines two variables, $left and $right, and says they are both true. Next it says to count how many modules are assigned to all of the positions in the two columns, and if they are all empty, make $middlespan use span12 (full width), and $left and $right will both be false.
If that’s not true, check the positions in the left column, and if they are totally empty, change the $middlespan to use span9 and make $left false.
If that’s not true, count all the modules in the right column, and if they are totally empty, change $middlespan to span9 and change $right to false.
Now you need to do a little PHP. Change this block:
<div class="span6">
<jdoc:include type="component" />
</div>
to this:
<div class=<?php echo $middlespan; ?>>
<jdoc:include type="component" />
</div>
This means that instead of always spanning six of the Bootstrap columns, when there are no modules in either column a span of 12 will be used, and when one column is empty, a span of 9 will be used.
Finally, we have to tell the browser not to use the left and right columns if they are empty (this is commonly called “collapsing the columns” in Joomla! templates). To do this we change the row-middle div to this:
<div class="row-middle">
<?php if (left == true) : ?>
<div class="span3">
<jdoc:include type="modules" name="position-3" />
<jdoc:include type="modules" name="position-4" />
<jdoc:include type="modules" name="position-5" />
</div>
<?php endif; ?>
<div class=<?php echo $middlespan; ?>>
<jdoc:include type="component" />
</div>
<?php if ($right == true) : ?>
<div class="span3">
<jdoc:include type="modules" name="position-6" />
<jdoc:include type="modules" name="position-7" />
<jdoc:include type="modules" name="position-8" />
<jdoc:include type="modules" name="position-9" />
<jdoc:include type="modules" name="position-10" />
</div>
<?php endif; ?>
</div>
What that does is to say if $left is true (which we determined earlier), then make a space to show the left modules. Otherwise, don’t create that <div> </div>. And then it does the same thing for the right column. Notice that == is used. This means “is equal to” in PHP (this notation can take a while to get used to). The site now looks as shown in Figure 8.9.
Figure 8.9. The home page after the addition of column collapsing
Adding Colors and Typography
Now we have a basic skeleton for our page layout. Next, we want to make the page with that layout look the way we want it to, not just with the default colors and typography.
Twitter Bootstrap uses a version of CSS called LESS to generate complex styles. However, for the purposes of this simple template we are going to use standard CSS. Create a blank file called custom.css and store it in the css folder of your template. Then include the style sheet in index.php AFTER the template.css.
<?php $doc->addStyleSheet('templates/'.$this->template.'/css/custom.css'), ?>
You do this after the template.css file because one of the principles of Cascading Style Sheets is that styles that come later override those that come earlier (that is the cascade).
Tip
If you want to learn more about using LESS to create the CSS for your template, please visit http://lesscss.org/ for detailed information and links to resources, including software for compiling your LESS file into CSS. http://docs.joomla.org also has some documentation.
There are many other additional resources that will help you build on what you learned in this chapter and build more complex and detailed templates. One resource is Joomla! Templates by Angie Radtke, who created the Beez templates included in Joomla! 2.5 and 3.
We chose a header image for our site and used a Web-based system (Adobe Kuler) to analyze the colors in it. From this we chose a background color (#5E7339), which is a shade of green, and then two adjacent shades of green, #A3BF72 and #95BF4C. We also found the complementary color, a purple, #663973.
Starting with the basics, we added styles for the backgrounds and basic text color and add a width for the container that will apply no matter what else is done:
body {
color: black;
background-color: #5E7339;
}
.container {
background-color: white;
width: 980px;
}
Then we added a header image and colors and fonts for the headers and links:
.header {
background-color: #040404;
min-height: 180px;
background-image: url('../images/orange_leaves.jpg'),
}
a, h1, h2 {
font-family: lucida sans;
color: #A3BF72;
}
h3 {
font-family: arial;
font-size: 1.5em;
}
Next, we wanted to change some other details in the styling for specific elements by overriding styles from the Bootstrap file. We use a browser-based tool to do this. The best known of these are Firebug, which works in the Firefox browser, and Developer Tools for Chrome. These tools allow you to examine specific parts of your page to determine which styles control it.
The top menu is controlled by the nav class, so we modified that to add a small margin on the left. We also styled the menu links using .nav > li > a to add a specific color just for the menu links:
.nav {
margin-left: 5px
}
.nav > li > a {
color: #5E7339;
}
.nav-pills > .active > a, .nav-pills > .active > a:hover {
color: white;
background-color: #663973;
}
We went to the Module Manager and edited the top menu, entering a blank space followed by nav-pills (the space is important—the CSS will work differently if there is no space) in the field called Menu Class Suffix on the Advanced Options tab. Not only will this add the purple background when a menu link is active (the link for the page is displayed) or when a user’s cursor hovers over a link, but it also will make the menu display horizontally.
Currently we have three modules in the right column, all in position-7. We unpublished the Login module and moved the banner to position-8. We modified our index file for position-8 to use the Bootstrap well class that we saw in Protostar for any module in that position:
<div class = "well">
<jdoc:include type="modules" name="position-8" />
</div>
We also edited the Smart Search module to set Search Field Label to Hide in the Advanced Options tab.
We want to display our site name in white over the header image. So again we had to add some PHP and some CSS. To the PHP block in the index file we added
$config = JFactory::getConfig();
$sitename = $config->get('sitename'),
which says to get the site name from the metadata that we created in Global Configuration. Then we modified the header <div> to add a div showing the site name:
<div class="span12 header">
<div class="sitename">
<?php echo htmlspecialchars($config->get('sitename'));?>
</div>
<jdoc:include type="modules" name="position-11" />
</div>
To the CSS we added some styling for that class:
.sitename {
color: white;
font-size: 80px;
font-family: Georgia;
margin-top: 30px;
margin-left: 20px;
}
Finally, we needed to make some small CSS adjustments to make the Breadcrumb module the same width as the header image:
.breadcrumb {
width: 920px;
margin-left: 20px;
padding-right: 5px;
}
ul.breadcrumb {
width: 880px;
}
Figure 8.10 shows the page with the styles added.
Figure 8.10. A page rendered with custom CSS for styles for colors, fonts, and other details
Conclusion
This chapter took you through the steps of building a basic Joomla! template using Twitter Bootstrap. We encourage you to continue to develop your templating and design skills by experimenting with color, typography, layouts, and other design elements as discussed here and in Chapter 7.