Designing your Site with Mambo Templates

For versions lower than Mambo 4.7, Mambo comes with two waterandstone templates. The problem with default templates is that everyone that downloads Mambo gets the same templates, so probably the first thing you will want to do is to customise your template to suit your site. The default templates are not the easiest to change. If you want to use a different header image you need to choose an image file that is the exact same size (height and width) as the waterandstone header image. Changing the colours requires editing the colours in your waterandstone template_css.css AND replacing some of the background images that you will find in the template images folder. Any other changes are likely to take you into some serious web design territory.

There are many free templates around for Mambo. Check on the Mambo forums for announcements and also on the Mambo code forge. Search engines also bring up a large number of results. When you look for free templates just check the date the template was written and which version of Mambo it was written for. There have been some changes to Mambo over the years and this affects template coding.

Difference Between a Mambo Template and a Static HTML Template

Why are Mambo templates different to my HTML template?

Mambo is a database-driven content management system. That means that a Mambo site does not have pages as such, but instead, it uses the one template index.php that includes various calls to the database to dynamically generate pages as they are needed. On a static HTML site, the content of each page is written into the page, with Mambo the content is all stored in the database. So, a Mambo template includes all the code necessary to generate the content as it is required.

Looking Inside a Mambo Template

Mambo templates are found in a sub-folder inside your install directory/templates folder. The Directory structure of a template is as follows:

[installdir]/templates/

index.php is the file that displays all pages in your Mambo site. It is written in a combination of PHP and (X)HTML and lays out the way your site appears in browsers.

template_thumbnail.png is an image file that gives a thumbnail snapshot of what your template looks like.

templateDetails.xml is the xml file that is needed to install your template into your Mambo site. It contains the details of all the files (including images) that are installed for your template.

template_css.css is the name of your .css file. Some templates use different names for the .css.

The images directory is the folder where all your template image files are stored.

So, let's look at the index.php file.

index.php

At the top, you will find this code:

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

Let's look at this in three parts:

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

This line ensures that the file cannot be called directly into a browser and must be called from within Mambo. In other words, if its not called through a valid "MOS" call, then access to the file will "die" and return a message in the browser window saying, "Direct Access to this location is not allowed."

// needed to separate the ISO number from the language file constant \_ISO
$iso = explode( '=', \_ISO );

This line ensures the correct ISO value is returned for your site and affects the language handling of your site.

// xml prolog
echo '<?xml version="1.0" encoding="'. $iso\[1\] .'"?' .'>';
?>

This line is used in many templates and is completely unnecessary. Internet Explorer does not know how to handle xml files and adding the xml declaration throws IE into Quirks Mode, which can impact on how your site renders in the browser. The xml declaration is only needed when you serve a site in XML/XHMTL (most sites are delivered as content="text/html" which makes the xml prolog redundant) and it is a good idea to remove it.

To remove the xml declaration, just replace the code given above with this:

<?php
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
// needed to separate the ISO number from the language file constant \_ISO
$iso = explode( '=', \_ISO );
?>

The next Mambo code you find is this:

HEAD Tags

The <HEAD> tags:

<?php mosShowHead(); ?>

This generates the headers for each page, including such things as metadata, generator tag (for versions before 4.6), the favicon, and the robots directive (ie. index/follow).

After the headers are generated, the WYSIWYG editor is initialised by this code...

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

Note: this is ONLY loaded when a user logs on.
You will see other PHP code between the <HEAD> </HEAD> tags, such as the code contained in

This calls your template's cascading style sheet file.

This part prepends your site's URL to the css file link:

<?php echo $mosConfig_live_site;?>

It uses the $mosConfig_live_site setting you have entered into your site configuration (configuration.php) when you installed Mambo.

Note: You can just as easily use a relative path to your css file and hardcode this into your template like this:

Now, onto the body of your template file...

Inside the <BODY> Tag

A Mambo template contains certain core functionality, but the layout is completely up to the template designer. I will explain the Mambo code here in the order in which it appears on the page, remember though that this is not necessarily the order in which it is written in the index.php file.
So, starting at the top of content, we have

<?php mosPathWay(); ?>

The pathway is the navigation string that lets visitors know where they are within the site structure.
The pathway is displayed inside a span tag in the default Mambo template, eg.

Mambo adds a separator between each item on the pathway. It will first look in your template's image directory for a file called 'arrow.png' and if it does not find this image file it will use the default image from your site images directory (/M_images/arrow.png).

In layout terms, modules are essentially the building blocks of a page. Mambo comes with several built-in modules, including the Main Menu (mod_mainmenu), Login Form (mod_login), Who's Online (mod_whosonline), and Polls (mod_poll). If you take a look at Site Module Manager in your Administrator backend (Modules -> Site Modules), each module is assigned a position (left, right, top, etc) and modules may be assigned to the same position. In your template, Mambo uses this position name to group modules into blocks. (Note: If you have several modules assigned to one position, you must use the Site Module Manager to determine the order of how they are displayed. Just reorder modules to get them in the order in which you want them to appear).

<?php mosLoadModules('left'); ?>

This loads the display of all published modules that have been assigned a 'left' position in your Site Module Manager.

You can assign 10 modules to the "left" position, if the template doesn't use a call somewhere to load modules into a position called "left", they simply won't show up!

Other module loading positions are represented by the following:

<?php mosLoadModules('top');?>
<?php mosLoadModules('right');?>

You will also see other module positions such as:

<?php mosLoadModules('user1'); ?>

NOTE: "user1", 2,3,4 does not have any meaning other than as a positioning name for module positions. (You can add your own custom position name or change these "user" names to something more descriptive. Doing this is a little more involved, so I won't be going into this here).

When a module is called in the index.php, there are five options on how it is displayed. The syntax is:

mosLoadModules('$position_name'\[, $style\] )

Read more about:Positioning and Displaying Modules

The main content in a Mambo page is generated from:

<?php mosMainBody();?>

Looking further down the page, we come to code such as this:

<?php if (mosCountModules('banner') >= 1) {&nbsp; ?>
and
<?php mosLoadModules('banner'); ?>

This essentially tells Mambo to see whether there is a banner that can be loaded, and if so, then load it. If not, then no banner is displayed.

Close to the bottom of your index.php you will see the default footer code:

<?php include_once( $mosConfig_absolute_path .'/includes/footer.php' );?>

This loads the Mambo default footer that includes the copyright notice. This can be removed and replaced with your own custom footer.

In some templates, you will also see:

<?php mosLoadModules('debug', \-1);?>

This is not essential and it does not affect the performance of your Mambo template. This snippet of code simply allows you to easily switch on debugging, which can be useful if you have problems on your site and want to see what calls are being made to the database.

So, that's it!

The key points to remember are:
Mambo generates the pages your visitors see, using your template's index.php to call the data. Modules that are published cannot be seen on your site unless you have allocated a position to them in your template's index.php. Modules can be placed virtually anywhere in index.php, so it is wise to decide in advance how you want your site to look, then group the modules and make sure they are set to the right position in your site's Module Manager.

TIP:

If you are starting out with a Mambo site the best way to become familiar with templates is by downloading one of the many free templates available and playing with it!