Gantry Framework - Part 3: Body + Features

In part 3 of this series of blog posts on Gantry we're going to delve into the how the body area of the template is controlled, and also how the power of Gantry Features allows you to add advanced functionality that fits into your customized layout with very little headache.

This is Part 3 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 2 and Part 4 helpful in understanding this post. To learn more about the Gantry Framework as well as view documentation and tutorials, be sure to visit the official Gantry Framework site.

Modules and Overall Layout

Gantry is built to be supremely flexible, so that while it is true that the default Gantry layout has 65 module positions available, you can of course use none, or you can even easily add more. The diagram below shows the available positions that are standard and should suffice with handling any layout chores you can dream up. Of course, all the positions are fully collapsable, and feature our flexible layout control as described in Part 2 of the Gantry blogs. They are all fully independently controlled, and combined with the advanced ability to force a certain number of positions, the sky really is the limit when it comes to design a unique layout.

MainBody and Sidebar Layouts

The MainBody area in the Gantry framework consists of a set of modules above and below the component area (main content area) called "Content Top" and "Content Bottom". These two module positions each have a maximum of 3 module positions available in each position. Along with this MainBody area, there are up to 3 "Sidebar" positions available. This allows a very flexible 4 column design if needed, however if no sidebar's are required, it will automatically adjust to be a full-width design.

Of course, we provide unparalleled control with Gantry and you can use the special MainBody layout control to choose your layout in any combination of columns and Sidebars. Not only can you choose the order of your Sidebars and MainBody, but you can also choose the relative sizes of these. The combination of these two features provided a huge array of possible layout combinations. Below is just a sampling of the 36 possible MainBody/Sidebar combinations!

Mainbody (6) - Sidebar A (3) - Sidebar B (3)

Sidebar A (2) - Mainbody (8) - Sidebar B (2)

Sidebar A (3) - Mainbody (4) - Sidebar B (3) - Sidebar C (2)

Sidebar A (6) - Mainbody 6)

Features

One of the most powerful and flexible components of the Gantry framework are the Features. Features are little chunks of functionality that can handle tasks that are conveniently handled by the template and framework. Traditionally the visual variety of features such as logos, font-sizers, back-to-top links, etc, would have to have been handled with blocks of HTML inserted into "Custom Modules" combined with associated CSS and JavaScript. The more programatic features like loading special CSS for IE6, handling the FusionMenu, inline style declarations, etc, would have been inserted as PHP code in the supporting template utilities files.

Logo Feature

In Gantry the features are a powerful and highly flexible mechanism to handle any kind of visual or programmatic requirement in a simple and unified fashion. Features are treated internally by Gantry as a pseudo-Joomla-module, and as such, you are able to assign them to any module position available. They differentiate from a regular module position in that you do not control their visibility on a menu-item basis, they are either on and active or off and disabled. Let's take a very simple example of a feature, the logo feature:

    class GantryFeaturelogo extends GantryFeature {
        var $_feature_name = 'logo';

        /** function init() {

        }**/

        /**function finalize() {

        }**/

        function render($position="") {
            ob_start();
            ?>
                <div class="rt-block">
                    <a href="/<?php echo JURI::base(); ?>" id="rt-logo"></a>
                </div>
            <?php
            return ob_get_clean();
        }
    } 
   
  

This feature is controlled by a 'chained' parameter in the templateDetails.xml:

  
    <param name="logo" type="chain" label="Logo"  description="">
        <param name="enabled" type="toggle" default="1" label="Show" />
        <param name="position" type="position" default="header-a" label="Position" />
    </param>  
  
  

There are two parameters within the logo 'chain', and these provide functionality to enable/disable the feature, and also a drop-down to select the position in which this feature will be displayed. In the administrator, these are displayed like:

The GantryFeatureLogo class extends the GantryFeature class and as such there are three main events that are supported. Anything that is put in the init() method of the feature is triggered during the $gantry->init(); call. Anything that is put in the finalize() method is triggered during the $gantry->finalize(); call. Lastly, the render() method is called during the rendering of layouts so this is what is output in the assigned module position. In the case of this simple logo feature, there is no need for setup or extra logic steps during initialization, only some simple output is needed.

JSTools Feature

Another kind of feature can be seen in the JSTools example below. This is different from the Logo feature because there is no render() method implemented, and everything is handled in the init() method.

  
  class GantryFeatureJSTools extends GantryFeature {        
        
        var $_feature_name = 'jstools';

        function isEnabled(){
            return true;
        }
        function isInPosition($position) {
            return false;
        }

        function init() {
            global $gantry;

            // date
            if ($gantry->get('date-enabled') && $gantry->get('date-clientside')) {
                $gantry->addScript($gantry->gantryUrl.'/js/gantry-date.js');
                $gantry->addInlineScript($this->_dateFormat());
            }
            // inputs
            if ($gantry->get('inputstyling-enabled') && !($gantry->browser->name == 'ie' && $gantry->browser->shortversion = 6)) {
                $exclusions = $gantry->get('inputstyling-exclusions');
                $gantry->addScript($gantry->gantryUrl.'/js/gantry-inputs.js');
                $gantry->addInlineScript("InputsExclusion.push($exclusions)");
            }
            // scroll to top
            if ($gantry->get('totop-enabled')) {
                $gantry->addScript($gantry->gantryUrl.'/js/gantry-totop.js');
            }
        }

        function _dateFormat() {
            global $gantry;

            $formats = str_replace("%", "$", $gantry->get('date-formats'));

            $js = "
                var dateFeature = new Date().format('$formats');
                window.addEvent('domready', function() {
                    var dates = $$('.date-block .date');
                    if (dates.length) {
                        dates.each(function(date) {
                            date.setText(dateFeature);
                        });
                    }
                });
            ";

            return $js;
        }
    }  
  
  

The first thing you will notice is the isEnabled() and isInPosition() methods are overridden so they do not use the parameters as are expected by default. This feature has no parameters of it's own at all so we've enabled it in code. Also because there is no display, there's no need for a position, so that method returns false. In the init() method itself, you can see that we are checking some other params and if then are enabled, some JavaScript files are added to the <head> tag. As you can see the Features have full access to the Gantry object, and all the parameters that are stored within it.

Predefined Featueres

You can probably see already how powerful Gantry's Features can be, and we already have the following core features:

• copyright.php - Displays customizable copyright text
• date.php - Displays server side or client side date/time in configurable format
• fontsizer.php - Allows font size changing
• fusionmenu.php - Initialize and setup fusion menu
• ie6menu.php - Forces IE6 to use suckerfish menu for better compatibility
• jstools.php - Supports addition of JavaScript functionality
• logo.php - Displays the logo from the provided styles
• splitmenu.php - Initialize and setup splitmenu menu
• styledeclaration.php - Sets up some inline CSS styles like link color
• suckerfish.php - Initialize and setup suckerfish menu
• totop.php - A simple link with JavaScript to smooth scroll to the top of the page

Gantry let's you easily use one of these pre-defined features, or you can copy one of these core features into your template, and modify it. Gantry will use your overridden feature in place of the core one. Also you can easily write your own features, even if they require custom parameters, just include the parameters your need to use in the templateDetails.xml and they will automagically be available in your new custom feature.

Coming Up...

In future posts we'll show you the power of some of the built-in browser detection and what that means for Gantry, also we'll delve into the XML in more detail to show how to enable client side parameter setting, as well as presets and other goodies, so stay tuned...