Customising Mambo Templates

Packt Publishing has kindly given us permission to republish this tutorial on Customising Mambo Templates.

The source of this content is Chapter 11: Customizing a Template of Learning Mambo: A Step-by-Step Tutorial to Building Your Website by Douglas Paterson (Packt Publishing, 2007).

In this tutorial we'll walk through making some basic customizations to one of the existing Mambo templates to produce a very different looking template for Zak Springs(Sample website). We'll change the header graphic and the page background, customize the main content area, change the way modules and the menus are displayed, and so on.

We'll finish off with the steps required to turn your template into a unit that can be installed onto another Mambo site.

First, let's talk about what you will need to work with templates.

What You Need

We'll be working with three main things in our template activities; PHP code files, the CSS stylesheet, and graphics.

You don't need to know very much about PHP to work with the PHP code file in the template, partly because there isn't much PHP code in the file, it is mostly HTML markup. To edit the PHP code file you can use a standard text editor, like Notepad or one of the other free text editors like the excellent PSPad (available from www.pspad.com). The code file in question isn't that large or complex, and there isn't much to gain from editing this file in a more complex HTML editing application like Adobe's Dreamweaver or FrontPage.

Source

Learning Mambo: A Step-by-Step Tutorial to Building Your Website
ISBN 978-1-904811-62-6
Publisher [Packt Publishing ]
Author(s) Douglas Paterson

This tutorial is copyright (c)2007 Packt Publishing
and is not licensed for reprinting under the
Mambo Manual license.

The Cascading Style Sheet (CSS) is another plain text file, and can also be edited in a text editor. When doing further work on the stylesheet, you may find the extended features of a Dreamweaver-like application helpful, but for our work here, the text editor will suffice.

Editing the CSS file isn't particularly the problem here. The problem could be how comfortable you are working with CSS. As you'll see, most of the formatting for the template is governed by the CSS file. We'll take you through most of what you need to perform the tasks here, but to get serious with Mambo templates, growing your knowledge of CSS is a good idea.

1 What You Need
2 Template File Structure
3 Creating a New Template

3.1 Changing the Template Details
3.2 The Template File Itself
3.3 XHTML Compliance

We'll be doing some work with graphics in the course of making our template as well. For this, you'll need some kind of image editing application, such as PhotoShop, PhotoShop Elements, or something like the open-source GIMP application. Any of these will be able to help you perform the kind of tasks we do in this tutorial, and much more.

There is another set of tools that will be very helpful when working with templates, browser tools. There are a number of tools that you can plug into your browser that can help you work out what style is being applied to what part of the page, and also the overall structure of the page.

If you're using the Firefox browser, there are two particularly useful extensions that can be downloaded, installed, and used from within the browser. The first is the Web Developer extension, available from https://addons.mozilla.org/firefox/60/. The Web Developer toolbar allows you to outline various elements on the page, such as table or block-level elements, see what CSS classes are applied to particular elements, and also see the definition of those classes. The Firebug extension, available from https://addons.mozilla.org/firefox/1843/, offers even more power, including an inspector to reveal the structure of the page and a JavaScript debugger. Installing Firefox extensions is a straightforward operation.

For Internet Explorer 7, there is also a "Web Developer Toolbar", similar to both the Firefox Web Developer Toolbar and the Firebug extension. It can be downloaded from:http://www.microsoft.com/downloads/details.aspx?familyid=e59c3964-672d-4511-bb3e-2d5e1db91038&displaylang=en

There is also a similar toolbar for the Opera web browser, available from:http://operawiki.info/WebDevToolbar

For the Safari web browser, you can try the Web Inspector available from:http://webkit.org/blog/?p=41

One other thing to note: we'll be making changes to the files in our template, and then refreshing our browser pages to see the changes. If you find that refreshing the page in your browser isn't changing anything, you might want to perform a "hard" refresh (Ctrl + F5 in many browsers), which will ignore any items your browser might have cached. Internet Explorer in particular often needs a hard refresh to take notice of a change in the stylesheet of your template.

Template File Structure

A "template" is a folder that contains a couple of files and two folders. First of all, the folders:

css: This folder contains the CSS stylesheet for the template. The stylesheet file is called template_css.css.
images: This folder contains the images that are used by the template. This can be background images, images for the site banner, and so on.

The files in the template folder are as follows:

templateDetails.xml: This is an XML file that contains the metadata about the template; the name of the template, the author, date it was created, and also a full list of the files in the css and images folders.
template_thumbnail.png: This image is a "thumbnail" of the final template as it would be seen on the screen. This is the image that pops up when you hover the cursor over a template in the Template Manager. Typically, this image is around 200 pixels wide.
index.php: This is a PHP code file, and is actually the "template" itself. This file contains the HTML markup for the page, along with some inserts of PHP code that call Mambo functions to display modules and so on.

That doesn't seem so bad, just three files and some images in a template!

Creating a New Template

To get started, create a copy of the waterandstone_green folder and call it zaksprings. We're going to work with the green Water and Stone template, and gradually change it as we go.

Changing the Template Details

The first step is to change the name of the template, so open up the file templateDetails.xml in a text editor, and change the name element as highlighted below:

 
<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall type="template" version="4.5.3">

<name>zaksprings</name>

After you've done this, save the file, and let's move on.

The templateDetails.xml file contains metadata for the template, which is used to identify it to the Template Manager in the Mambo administrator area, and also provide information that can be used by the Universal Installer when the template is installed. We'll talk more about this metadata at the end of the tutorial when we've completed our new template.

Now if you browse to the Template Manager, you will see the zaksprings template in the list; select it, and set it is as the default template so that we'll be able to see how our changes look.

The Template File Itself

Although we are talking about "templates", the index.php file in our template folder can really by called the "template". You can open this file in your text editor to look at as we go further.

The file starts by preventing direct access to the template, and then declaring the document type of the page. The document type is XHTML, which is a "stricter and cleaner" flavor of HTML, intended to add a proper XML structure to HTML pages. You can read more about XHTML at: http://www.w3schools.com/xhtml/xhtml_intro.asp.

 
 <?php
  defined( '_VALID_MOS' ) or
  die( 'Direct Access to this location is not allowed.' );
 // needed to seperate the ISO number from the language
  file constant _ISO
  $iso = explode( '=', _ISO );
 // xml prolog
  echo '<?xml version="1.0" encoding="'. $iso[1] .'"?' .'>';
 ?>
 <!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">
 <head>

The next part of the template sets up the <head> element of the page, which includes such things as the meta tags that Mambo will generate (these are included by the mosShowHead() PHP function), and some references to include the JavaScript required for the HTML editor and also the CSS stylesheet for the template from the css folder of the template. If you wanted to add in references to other stylesheets or JavaScript libraries, you would do that in this part of the template:

 
 <?php mosShowHead(); ?>
 <?php
 if ( $my->id ) {
  initEditor();
 }
 ?>
 <meta http-equiv="Content-Type"
  content="text/html; <?php echo _ISO; ?>" />
 <link href="<?php echo $mosConfig_live_site;?>
  /templates/waterandstone_green/css/template_css.css"
  rel="stylesheet" type="text/css"/>
 </head>

As you continue to look through the file, you'll notice the presence of the word waterandstone_green in links to images and also the stylesheet. For example:

 
 <link href="<?php echo $mosConfig_live_site;?>
  /templates/waterandstone_green/css/template_css.css"
  rel="stylesheet" type="text/css"/>
 ...
 <a href="index.php">
  <img src="<?php echo $mosConfig_live_site; ?>
  /templates/waterandstone_green/images/logo.gif"
  alt="logo image" border="0" align="top" />
 </a>

These are references to our source template, so you will need to change this to point to your new template. If you don't, then you might wonder why nothing is happening when you start adding new graphics it's because the wrong folder is being looked in for that new image!

Using the search and replace feature of your text editor replace all occurrences of waterandstone_green with zaksprings, and then save the file.

Quite a lot goes on in the index.php file, and display of the page only really starts with these lines:

 
 <body class="waterbody">
 
 <div align="center">
 <div id="container">
  <div id="containerbg">

From then on, the file consists mostly of HTML container elements, and some PHP statements (as highlighted below):

 
  <!-- start left column. -->
  <div id="leftcol">

<?php mosLoadModules('left'); ?>
  </div>
  <div id="leftcolmenu">

<?php mosLoadModules('user1'); ?>
  </div>
  <!-- end left column. -->

The file also has a number of HTML comments (enclosed by ), which help to give you an idea of what's going on. The snippet above displays the left‑hand column. An HTML div element is created, with an id attribute of leftcol. This id attribute will be used to identify that particular page element by the CSS stylesheet. What goes into this div element? The output of the

 mosLoadModules('left')

function will be the value of div element.

You can almost guess what

 mosLoadModules('left')

does. It displays all the Mambo modules that have a position of left.

Further down the file, you can see some other functions:

 
 <?php
  if (mosCountModules('user2') >= 1 OR mosCountModules('user3') >= 1 ) {
  ?>
 ...
 <?php mosPathWay(); ?>
 
 ...
 <?php mosMainBody(); ?>

The name, of these functions gives a big clue to what they are expected to do. The

 mosCountModules()

function returns the number of modules in a particular position. This function is used in case you wanted to enclose the modules in some kind of container element, but you only wanted the container element displayed if there were actually some modules to go in it.

The

mospathWay()

function displays the breadcrumbs:

The main part of the page is displayed by

mosMainBody()

.

No Logic Here

One thing you will notice is that once the display of the page starts after the

<body>

tag in index.php, there is very little "logic" in the index.php file. There are only two if statements in the entire file and both of these only check if a particular module position has some modules.

There is little point in putting logic into the template file. Through the module and menu management systems of Mambo's administration, you have already encoded a lot of logic on how your site will look and operate; displaying modules in certain positions on certain pages, restricting certain menu items to some types of user, and so on. Also, the ability to select a different template for different sets of pages adds another layer of logic, so there isn't that much left to put into the template. Also, you would need to have a very good knowledge of the inner workings of Mambo to introduce more complex logic into the page output.

Links to Images

Another thing to note is the links to images in the file. They look like this:

 <img src="<?php echo $mosConfig_live_site; ?>
  /templates/zaksprings/images/img_header.jpg"
  alt="header image" />

The

$mosConfig_live_site

variable holds the path to your site (

http://www.zaksprings.com

for example), which is added to the path to an image. The images for a template are found in its images folder, so you might be wondering why you would need a long path to get to that image, why not simply images/img_header.jpg? That's because the browser is not requesting the file index.php in the templates folder. The page requests to Mambo always come through a few files in the root of the Mambo installation, index.php, index2.php, and so on. The index.php file of the template is "included" by Mambo for processing, so although the image looks like it's only one folder away from that index.php file, you need to write the full path to the image, which is

templates/<name of template>/images

for a visitor's web browser to get at an image.

No Layout Here

You may also be wondering where all the layout information in the template is. There doesn't really seem to be very much in the template in terms of HTML markup, just some

<div>

elements. That's because all the formatting is passed on to the CSS stylesheet. The tasks such as where these

<div>

elements go on the page, how big they are, what color they are, and what their text looks like are controlled by the CSS stylesheet.

To get a better picture of the importance of the stylesheet, this image shows the basic Water and Stone template without the stylesheet applied. As you can see, it's not particularly good!

The stylesheet transforms this basic list of items into a web page.

XHTML Compliance

Before we go any further, it's worth reflecting on the idea that the page created by the template is XHTML rather than standard HTML, or put another way, the page is XHTML compliant. One of the obvious differences between XHTML and HTML is that tags need to be closed, in order to be valid XML. In HTML, you can get away with using tags like:

 Time for a line break<br>
 and now a picture: <img src="images/myimage.gif">

However, to be valid XHTML, the <br> tag would need to be closed. This is not done with a

</br>

tag, but with

/>

characters at the end of the tag instead of the

character. The same is true for the

<img>

tag. Thus, to produce valid XHTML, we would want:

  Time for a line break<br/>
 and now a picture: <img src="images/myimage.gif"/>

This might seem like a lot of work to produce XHTML. Every time you used tags like these, you would want to make sure the tags are closed. However, if you think about it for a moment, you really won't have to do this that often.

There are three main ways that text finds it way onto your pages in Mambo

From the HTML editor
From code in Mambo components, modules, and so on
From the markup in the index.php file of the template

Whenever you add marked-up content in Mambo, you would generally find yourself using the HTML editor. When entering content through the HTML editor, if you've had a look at the HTML source as you're editing, you'll see that HTML editor itself ensures that the tags are XHTML compliant, <img> tags become

<img/>

and so on. If you work directly with the HTML source in the HTML editor, then you can try to introduce non-XHTML compliant markup, but even then, the HTML editor will do its best to make it XHTML compliant!

Mambo components produce their own output. It is up to the programmer of these components to make sure that the output is XHTML compliant, and generally, they do a good job of this.

The markup in the index.php file of the template looks like the only place you can really mess things up! This is one reason why the markup in the template looks simple; it basically consists of a number of <div> elements, and as we'll see, the formatting and layout of these elements is controlled by the CSS stylesheet. In addition to decoupling the layout of the page from the markup, this approach gives less opportunity for creating non XHTML-compliant markup as well.

So, keep an eye on the markup you add to the template, keep it XHTML compliant, and the rest of Mambo will keep things XHTML compliant as well. This is something to watch out for if you are editing the index.php file in some HTML editing application, such as FrontPage, which often has its own ideas about what kind of HTML it thinks you want to enter.

Continued on the next page: Customizing the Page Layout