Preferred Platform:

Gantry has built-in CSS and javascript compression tools allowing for fewer page requests and also adds compression for maximum page optimization. Find out more...

Home DocumentationJoomlaBasicsGantry Core Concepts

Gantry Core Concepts

One of the key concepts that make Gantry so powerful is that it provides a wealth of power and functionality that can easily be accessed by the Joomla template. This makes it easier for you the template developer to write cleaner code and as a side benefit, provide a level of abstraction that will allow you to go from Joomla 1.5 to 1.6+ without changing anything in your template. The Gantry library handles all the complicated bits for you.

Template index.php

Let's start digging into Gantry by taking a look at how the index.php looks:

// no direct access
defined( '_JEXEC' ) or die( 'Restricted index access' );

// load and inititialize gantry class
require_once('lib/gantry/gantry.php');

This top code block is all that's needed to get Gantry up and running. By including the gantry.php bootstrap file, you are connecting to the Gantry framework and initializing it. A lot of heavy lifting gets processed in here, all safely out of sight and mind. Next is the start of the HTML:


<!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 $gantry->language; ?>" lang="<?php echo $gantry->language;?>" >
<head>
    <?php 
        $gantry->displayHead();
        $gantry->addStyles(array('template.css','joomla.css','style.css'));
    ?>
</head>

Here you can see the traditional Joomla calls to get the language have been replaced with equivalent Gantry calls. Also there's a call to include the head elements. These include the CSS and JavaScript that have been initialized and setup in other parts of the Gantry framework. Also there's a call to add some stylesheets to the head of the template. This call has built in logic and will include core gantry css files, as well as including any css files that match these names in the template css folders. Also any browser-specific versions of these files will be added also. For example, if you have template-ie6.css in the template's css folder, it will get picked up also, but will only be presented to IE6 browsers. Let's take a look at the next bit of the file that includes some references to some module positions:


<body <?php echo $gantry->displayBodyTag(); ?>>
    <?php /** Begin Top **/ if ($gantry->countModules('top')) : ?>
    <div id="rt-top">
        <div class="rt-container">
            <?php echo $gantry->displayModules('top','standard','standard'); ?>
            <div class="clear"></div>
        </div>
    </div>
    <?php /** End Top **/ endif; ?>

Now you can see some of the elegance that Gantry provides. First in the body tag, you see a call to displayBodyTag() method. This is grabbing all the template parameters that have been designated via the templateDetails.xml to display in the body tag. It will output these in the format of PARAM_NAME-PARAM_VALUE. This makes it really easy to style your CSS based on a template parameter, with no coding required on your part. Below that you can see the comments that designate the "Top" position. First there's an "if" block to check to ensure there is content assigned to these positions, if there is not any content, then the entire "rt-top" HTML structure is not displayed. Inside the "rt-container" div is a call to displayModules() that takes a position name, in this case "top", a layout type, "standard", and a module chrome, also "standard", more on these a little later. This function performs all the output logic for a possible 6 module positions: top-a, top-b, top-c, top-d, top-e, and top-f. You configure your modules with the Joomla Module Manager as you usually would, but this one method does all the calculation concerning how the modules should display.

XML Configuration

In the case of the example we are discussing we refer to a "top" position, but this really represents a group of up to 6 individual module positions within that one top position. The possible module positions available to you are defined in the templateDetails.xml file, in the "position" XML element. This is the standard location to define positions for Joomla, as this is what is used by the Module Manager to show possible assignable positions to modules. A little further down in the templateDetails.xml file we have the template parameters, there's a section for configuring the Layouts. The "top" module position has it's own configuration along with a default value and some configuration settings that define which options are available. The abbreviated XML for this looks like:


<positions>
.....
<position>top-a</position>
<position>top-b</position>
<position>top-c</position>
<position>top-d</position>
<position>top-e</position>
<position>top-f</position>
.....
</positions>
.....
<param name="topPosition" type="positions" default="3,3,3,3" label="Top Positions" description="Top Positions">
    <schemas>1,2,3,4,5,6</schemas>
    <words>2,3,4,5,6,7,8,9,10,11,12,13</words>
</param>
.....

Template Parameters

At this point, If you don't touch anything, the default layout will be an equal size for the published modules. However, with Gantry you can completely control how much room each module position has to work with and this is controlled via the Template Parameters user interface. Below you see a screenshot of how this "topPosition" parameter element is rendered in the template parameters.

Gantry Core

The "Positions:" along the top represent the scenarios for the different number of populated module positions. If you had modules in 4 different module positions top-a, top-b, top-c, and top-d that would mean your active positions would be 4. The layout widget will always show you the current number of active positions in bold.

Full coverage of the Gantry module layout configurations and how to set up different widths can be found in the Layouts section.