Buy CIALIS online
Buy SILDENAFIL
Buy Viagra 100mg
Cialis Online
Viagra au

Gantry Framework - Part 2: Layouts

Gantry Framework - Part 2: Layouts

Written by Andy Miller Sunday, 22 November 2009 00:00

Coding

A few days ago I blogged about what we wanted Gantry to be, in this post I'm going to delve into how Gantry looks and works. Gantry involves a bit of a paradigm shift when it comes to thinking about how a template works and is configured. We've tried to make this as simple as possible while still allowing the most flexibility so I'm going go over it from front to back.

This is Part 2 in a series of blog posts on the new RocketTheme Gantry Joomla Template Framework. If you have not already done so, you may find Part 1, Part 3 and Part 4 helpful in understanding what Gantry is and why we created it.

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');
$gantry->init();
$gantry->addStyles(array('template.css','joomla.css','style.css'));
?>

This top code block is all that's needed to get Gantry up and running. The key call here is the call to init(). A lot of heavy lifting gets processed in here, all safely out of sight and mind. 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. The next part of the template is where the HTML starts in earnest:

<!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(); ?>
</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. 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 you 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 modules 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</words>
<maxgrid>12</maxgrid>
</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 positions 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.

Layouts Top Position

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. Below that number you see a block representation of the current layout. We use a system based on the 960 Grid System with a 12 column grid layout. Your layouts are based on this 12 columns, and by default the 3,3,3,3 of the default setting translates into an equal sized block for each of the 4 module positions you have active. In the front-end this would look like:

Layouts Front Top Position

If you slide the slider bar below to select a different layout for these 4 positions and a tooltip on the side will show you the numeric value of the configuration also.

Layouts Top Position 2

In this case you can see we have dragged the slider to the left and have chosen the layout 2|3|4|3, which means that module position top-a is assigned 2 grids, top-b is assigned 3, top-c is assigned 4 and top-d is assigned 3 grids. After hitting Apply or Save this will cause the front-end's layout to change and display:

Layouts Front Top Position 2

You can clearly see the 2|3|4|3 proportions have been applied to the layout. Gantry is so flexible that you can configure different layouts for different numbers of module positions. Joomla has the ability to show different modules on different menu items, so you may have 4 modules published on your Home menu item, but only 2 modules published on one of your internal pages, for example. To accommodate this you can merely click the 2 in the Positions list and choose a layout that suits your needs:

Layouts Top Position 3

This will translate into a 8 | 4 or worded another way, a 2/3 and 1/3 distribution of the 2 modules:

Layouts Front Top Positions 3

Advanced Settings

There are times when you just don't want to have your modules taking up all the room in a horizontal row no matter what the layout. For example you might want to have a module on the left and a module on the right, with nothing in the middle. In traditional Joomla templates you would have to resort to making two specific module positions and using CSS, position them on the left and right sides of your design. With Gantry however, you can use the advanced settings to achieve this goal with no code or special CSS. First in the advanced settings, for the Top Positions, set the Force Positions to On and then set the Position Count to 4. This means that there will always be 4 top module positions (top-a, top-b, top-c, top-d) displayed no matter how many modules you actually have published in the module manager. Then all you need to do is publish a module in the top-a position to show on the left, a module in top-d to show on the right. Just ensure you have nothing published in top-b and top-c, and those will just be left as blank spaces.

Layouts Top Advanced

And the end result will be:

Layouts Front Advanced

As you can see Gantry is providing unprecedented control to the layout that augments the regular Joomla Module Management functionality but does not limit it in any way. This ability to have complete control over your layout with an easy to use all-in-one interface is first for any Joomla template and allows for the creation of extremely rich layouts never before achievable within Joomla.

XHTML Structure

In the original call you will notice there are some extra parameters after the position name. These correspond to the layout to use and also the module chrome.

  <?php echo $gantry->displayModules('top','standard','standard'); ?>
Layouts Diagram

The html layout in the output is broken up into 3 distinct layers. First is the overall structure as defined by the template's index.php. The next layer is what is rendered around a module position, and this is called the layout. Gantry comes with a basic layout that has no extra html in it and does not even include the css required for the grid system to function, the other and much more common layout is called the standard layout. The standard layout just has the required html to render the proper grid structure to ensure the output matches the configuration you have set in the Template Parameters. You can of course create your own layouts.php file in the html/ folder of your template and create your own layouts as you see fit. That way you can actually create custom html for any set of modules positions. The last layer of the layout is the module chrome, and this is the same module chrome you get with regular Joomla templates. You can use the built-in Joomla chrome such as XHTML, or none, but we've provided a standard one as part of Gantry that fits in nicely with the rest of the XHTML structure.

Next Time...

In the next blog post I will delve into how the body area layout works and allows unparalleled layout control for size and ordering of the mainbody in relation to sidebars. Also we will cover our new "Features" functionality allows custom elements such as a Logo, Font Sizer, Menus, etc to function like a pseudo-module enabling them to be positioned in any module position and any layout.