Metro Rox HTML5 WordPress Multipurpose Theme

We presenting you our latest Metro Rox HTML5 Wordpress Metro Multipurpose theme. The fast, easy, light theme will decorate almost any site on wordpress. We had made it with a high booster wordpress theme backend option which will help you to change anything from theme settings area. is flexible and comes with a predefined suffix class or widget class suffix. It is easy to customize and arrives with REAL QuickStart Installation Package for wordpress . various widgets and PSD Sources for various graphics used on the demo site. It is fast loading and compatible >IE9+, Firefox, Chrome, Safari etc. This theme includes a rich documentation where you can find documentation, tutorials and find code snippets on how to customize the theme. So “Metro” is here at Themerox for your perfect choice.

Method 1 – Using the WordPress installer

Download plugin from here
Login into the WordPress administrator dashboard (
In the left menu sidebar, go to Plugins ? Add New ? Upload
Select the Choose File button
Locate the file on your computer
Click Install Now
Gantry Framework Plugin will now be installed
Click Activate under the Gantry Plugin

Method 2 – Using FTP

Download plugin from here
Load your FTP client, such as FileZilla
Upload the gantry folder to the
Login into the WordPress administrator dashboard (
In the left menu sidebar, go to Plugins
Click Activate underneath the Gantry Framework Plugin

Uploading Theme

Method 1 – Using the WordPress installer

Login into the WordPress administrator dashboard (
In the left menu sidebar, go to Appearance ? Add New Themes ? Upload
Select the Choose File button
Locate the file on your computer
Click Install Now
Fracture will now be installed
Click Activate under Fracture Theme

Method 2 – Using FTP

Extract rox_metro with extract as file
Load your FTP client, such as FileZilla
Upload the rox_metro folder to the
Login into the WordPress administrator dashboard (
In the left menu sidebar, go to Appearance ? Themes
Click Activate underneath the Fracture section

By dumi content you will get the exact demo site as you had seen in live preview. Its easy to setup. We also attached the Quick Install files by that you will get the esact live preview site in less than minute. 

Lets start with Import dump.XML file. 

After installing wordpress theme rox_metro and the gantry plugin you can able to import dump data from import tools at wordpress admin dashboard.

How to Use the XML File to Import the Demo Site’s Content

Log into your site as an administrator.
Make sure you activated your new theme before proceeding.
Go to Tools ? Import
Choose “WordPress” from the list.
Upload the demo database_dump.xml using the form provided on that page.
You will be asked to map the authors in this export file to users on the blog. For each author, you may choose to map to an existing user on the blog or to create a new user.
You will then have the choice to import attachments, so click on the “Download and import file attachments” box.
Please be patient while WordPress imports all the content. Posts, Pages, Projects, and Menus are imported. You will need assign the menu a theme location & you’ll need to configure widgets. This is a limitation of WordPress’ import system.
If you found difficulties in configuring dummy content then you can do exact demo live preview installation. And then can able to check configuration from there.For doing that read Quick Pack Installation tutorial section.

By this tutorial we will show you how you will get the exact demo site in less than 2 minutes. Its really easy if you follow the tutorial here.

  1. Download wordpress from here
  2. Unzip the file in your localhost or your public_html folder
  3. Check your downloaded folder from themeforest. It will be in main_file download. After that check the folder
  4. Unzip and then go to the dump_files\by_quickstart then copy all the files from dump_files\by_quickstart\wp-content\plugins and then put it to your downloaded wordpress files here wp-content\plugins
  5. Copy rox_metro from by_quickstart\wp-content\themes and put it to wp-content\themes
  6. Copy uploads folders from dump_files\by_quickstart\wp-content and then put it to \wp-content
  7. Copy install.php from dump_files\by_quickstart\wp-content and put it to \wp-content
  8. Copy sample-data.sql from dump_files\by_quickstart\wp-content and then put it to \wp-content
  9. Then install wordpress as regular installation.
Bellow the tutorial video which cover the full process from first to last. If you find any difficulties then you also can check it.

Sample data on local server from ThemeRox on Vimeo.

How to configure metro slider? Check this video tutorial

rox metro slider tutorial from ThemeRox on Vimeo.

How to configure rox scroller? Check this video tutorial.

rox metro scroller widget tutorial from ThemeRox on Vimeo.

In metro we had use gantry page builder features. Its very easy to configure and make page with the gantry override feature. 

How to use dynamic page builder/ override feature? Check this video tutorial

dynamic page builder tutorial portfolio from ThemeRox on Vimeo.

How make a dynamic page in less than 2 minutes? Check this video tutorial.

dynamic page builder tutorial contact us from ThemeRox on Vimeo.


Theme Overrides

Gantry offers users the ability to override default theme configurations for individual overrides. A frequent example is to have a different layout configuration on your site's front page from its subpages. Gantry makes this achievable in just a few clicks. In fact, you can configure different layouts for each of your subpages individually.

Discover the power of Gantry and its ability to configure any parameter based on theme overrides using custom theme styles. Gantry adds the power of inheritance of settings to enable easier per-override custom configurations.


Creating an Override

There are two methods of creating a new set of assignable configurations. The first is the Save as Copy method which involves you editing the Gantry theme at Admin Dashboard ? Theme Settings. Configure your settings, select Save as Copy from the Save dropdown, and change the override name from Duplicate Override to your own.

Alternatively, you can simply click on the New Override button, change the name of the newly created override and modify all of the parameters from scratch. Please note that when creating a new override, the beggining parameters are always the same as the ones set in the Default Settings override.


Configuring an Override

Once an Override has been created, you simply need to switch to it (if you weren't automatically) and configure. Each tab will have greyed out parameters that can be activated via the checkbox.

Configure items, then click on the Assignments tab. All content type items are listed here, so just check the items you want this particular Override to apply to.


Override Examples

Below is an example of an Override. The Layouts ? MainBody Positions setting has been overridden. Therefore, in the screenshots below, you can see that the sidebar allocation can be either left or right of the main body without being applied globally. This is the same for other settings like Gizmos or Styles, as well.




Gantry makes use of a powerful preset system allowing developers and site builders to create preset styles and configurations.

Creating a custom preset is easy with Gantry. Check out this short video on how to customize your layout and create a custom preset based on your configuration options.

Gantry Presets is a combination of Gantry features and configuration settings which allow you to create predefined groupings for the entire template as well as on a per-override basis. Presets can consist of any Gantry configuration option, such as: CSS style, link color, background, body graphic levels, font settings, and much more.


Creating a new Preset

To configure a new preset, go to Admin Dashboard ? Gantry Theme ? Style. From here, you can configure style settings for the template. In the example below, we'll change the link color.

Once configured, click Save Preset from the Save button dropdown.

The Gantry Presets Saver modal dialog box will appear. Enter your Preset Name, and the Key Name will be generated automatically. Then click Save.


Select your new Preset

Click on the Presets button to display all available presets. Your new preset will display in the slider. Click on the preset to load your custom style settings. Select Save to load the preset.

After a preset is created, you can create a thumbnail image in the admin/presets/ folder with the filename structure keyname.png where keyname is the Keyname from the modal dialog box.



The Style panel in the Gantry based template administration interface provides several options for configuring the main stylistic aspects of the template. While the default Gantry template includes several options, you can easily add and configure many more based on your template's needs. The following configuration options are available by default:



The Logo setting provides the ability to change its type. The default setting is Gantry Template, which loads the included template logo.

The second logo type option is Custom. This will load the Custom Logo field, where you can Select an image through the Media Manager.


Link Color

The Link Color setting provides the ability to easily change the main color for template links. Colors can be inputted via the color chooser pop-up selector. You can also do this manually using a hex code in the input field.


Font Settings

The Font Settings setting provides the ability to change the font size as well as the default font family used in the template. Many popular web fonts are included as options. Some templates also include additional custom font options.



The Pagination Settings setting allows you to decide how the pagination between content pages should look. This parameter allows you to decide if user should be able to see total number of pages, and how many side pages should be displayed next to the current page.


Use WordPress Comments

The Use WordPress Comments setting gives you ability to disable the WordPress core comments on the front-end in case if you prefer to use a third-party solution.


Custom CSS

The Custom CSS setting allows you to input your own, custom CSS code that will be added inline to the head section of the page. This way you can add custom styling (globally or per-override) to your page without modifying any of the template files.



A quick way to see the power of Gantry gizmos is to check out this short screencast. It covers some of the basics of gizmos and how they work and how they can be easily integrated into your design.


Page Suffix

The Page Suffix gizmo allows you to add extra CSS classes to the <body> tag of your site. This allows you to apply your CSS styles on a per-page basis.


Feed Links

The Feed Links gizmo decides whether WordPress should add the feed links to the <head> tag, allowing various feed readers to access them.


Custom Title Tag

The Custom Title tag allows you to customize your site's <title> tag to replace the default title placed in the head section of your page(s). This, combined with our Overrides system, gives you a possibility of having a completely different site title for each element of your content. There are a number of tokens available for usage:

Front Page / Home Page

Static Page

Category Pages

Archive Pages

Tags Pages


Shortcodes in Widgets

The Shortcodes in Widgets gizmo allows you to use WordPress shortcodes in Widgets when disabled shortcodes syntax placed in widgets won't get parsed.



The RokStyle gizmo allows you to easily add inline CSS or JS code to the <head> tag of your site by placing a shortcode syntax in your content. Here's an example:

CSS : [rokstyle type="css"].example {font-weight: bold;}[/rokstyle]

JavaScript : [rokstyle type="js"]InputsExclusion.push('.example')[/rokstyle]


Google Analytics

The Google Analytics gizmo allows you to enable Google Analytics tracking on your site in a quick and easy way. Just enable the feature and input your UA Key assigned to you by Google in the field provided.



The Layouts panel in the Gantry-based template administration interface provides several options for configuring the layout of the template. Each widgetized section of the template design offers six widget positions by default.

To find out about layouts and widget widths, check out this quick screencast. It covers some of the basic concepts involved in understanding and configuring layouts with a combination of widget configuration and Gantry layout control.


Gantry Divider Widget

Gantry Divider is a widget used to tell Gantry where you want to split your widget position and create another column.

If you placed two widgets in one position, they will be displayed in one column in two rows (one above another), but if you're going to place a Gantry Divider Widget between them, they'll be displayed in two columns (one next to each other) with widths set in the Layout settings of that position (for two-widget columns variation). The example below shows the setup where six widgets will be displayed in six columns within a single position.

The same rule applies to the MainBody layout configuration. Splitting your sidebar widgets with one Gantry Divider will result in breaking them into a two sidebar layout, exactly in the place where you placed your divider widget. A three-sidebar layout is just a matter of adding a second Gantry Divider widget in the sidebar widget position.


Using Layouts

Each of the major widget positions is represented with a slider to allow for dynamic control widget layout. This is based on how many widgets are placed in that position. By default, placed widgets will be displayed at equal sizes.

At the top of the slider are numbered links from 1 to 6 which represent the number of placed widgets you want to configure for. For example, if you are setting up the layout for a position which has four widgets in use (split using three Gantry Divider widgets), you will want to first select the #4 link at the top of the slider for that position.

If you had four widgets in one position separated with the Gantry Divider widget, your active positions would be 4. The layout slider will always show you the current number of placed widgets in that position. Below that number, a block representation of the current layout is displayed.

We use a system based on Twitter's Bootstrap. Layouts are base 12, and by default, the 12 column 3 | 3 | 3 | 3 of the translates to an equal sized block for all four widgets place in the position.

Based on the 12-column layout with four widgets of equal width published, the front-end will look like this:

When you slide the slider bar below to select different widths for these 4 widget columns, a tooltip on the side will also show you the numeric value of the configuration.

In this case, we have positioned the slider to the left and selected the layout 2 | 3 | 4 | 3, which means that widget column utility-a is assigned 2 grids, utility-b is assigned 3, utility-c is assigned 4 and utility-d is assigned 3 grids. After hitting Save, this will cause the front-end's layout to change and display:

You can 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 placed widgets in a position. Gantry also has the ability to show different widgets on different overrides, so you may have 4 widgets placed on your Home page, but only 2 widgets placed 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:

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


Mainbody Layouts

The layouts for the mainbody area is slightly different from the other widget layouts. The primary difference is that the mainbody is generally displayed along side up to 3 sidebars. This provides the ability for a Gantry-powered template to effectively support a 4 column layout. We researched a wide variety of sites and determined that more than 4 columns for a layout is very rare and quickly becomes unreadable due to the limited amount of space available. Generally speaking 2 or 3 columns is the preferred layout for a modern website.

The layout for this is controlled in the template settings. As you can see below, Gantry understands that there are 3 sidebar columns (widgets in sidebars have been splitted using two Gantry Divider widgets), so when the mainbody is taken into account, this creates a 4 column layout. The current configuration is set to 6 | 2 | 2 | 2 where the mainbody is using 6 grid units, and the 3 sidebars each use 2. This adds up to the 12 grid system we are using in this example.

If you drag the slider to the right, you will see the positions shuffle around to display different layout options for the mainbody. With four total columns, there is not much room to have widely varying column widths. So, let's turn off one of the columns by removing one of the Gantry Divider widgets in the sidebar position using the WordPress widget manager. Below, you will see how the default layout is currently set to display when we have only two sidebars:

As you can see: It's set for the two sidebars to be displayed on the right. Each sidebar is taking up two grid units while the mainbody is on the left occupying eight grid units. Dragging the slider to the right will provide a wide variety of layout options. As you can see below, this example shows a layout of 3 | 6 | 3 with the mainbody in the middle:

After you click the Save button in the toolbar, you will be able to see this layout applied to the frontend:


The Advanced panel in the Gantry based template administration interface provides several options for configuring the advanced options for the template. The following configuration options are available:

Maintenance Mode

Maintenance Mode allows you to block the non logged in visitors from viewing your site for the time you're making changes to it. This way you can do modifications and test them without unnecessary rush. By default the front end will display the message specified in the Message field, but you can also create your own custom file called maintenance.php in the template root directory which will be used instead.

Display Content

The Display Content option allows you to enable/disable the output of the WordPress content on the front end. This is useful for sites and templates that want to make use of a page that consists entirely of widgets but preserving all Mainbody widget positions.

Mainbody Enabled

The Mainbody Enabled option allows you to enable/disable the entire Mainbody section. This is useful for sites and templates that want to make use of a page that consists entirely of widgets.

RTL Support

RTL means “right-to-left” and is a key component when trying to deliver a website in a RTL language such as Hebrew, Arabic, Urdu, etc. Gantry has built in RTL support which will automatically “flip” the content layouts and ordering to support RTL. This option allows you to enable or disable the built-in RTL support which is automatically detected and displayed based on the language file setting.

Disable Auto Paragraphs

The Disable Auto Paragraphs option allows you to remove the WordPress filter responsible for automatic <p> tag content wrapping. This can be very useful when creating a complex content.

Disable Texturize

The Disable Texturize option disables some text transformations like smart (curly) quotes for content and comments. This can be very useful for example for placing code inside your content.

Template Typography

The Template Typography option allows you to enable/disable specific typography elements from loading, as well as allowing you to select between light and dark typography.


Enable or disable Selectivizr support for IE8 providing support for additional CSS selectors for better compatibility.

LESS Compiler

LESS is commonly used in our Gantry 4 CSS as a server side compiler. Its options allow you to determine the delay on that compiling process, whether CSS compression is also infused within it, and if you wish to debug the header. There is also an option to clear the LESS cache.



Adding Widget Positions

This section covers how to add a new widget position to the Gantry Framework, and to your Gantry-enabled template.

Check out this quick screencast on Widget Positions to get an overview of how widget positions work within WordPress and the Gantry Framework.


Step 1: Getting Ready

Determine the position name and location on your theme where you would like your new position to appear. In our example, we will use "Example."


Step 2: Adding Position to index.php

Open your template index.php file and go to where you would like to add your new position. Using $gantry, we will make a call to the object using the function: displayModules(positionname, widgetlayouttype, widgetchromelayout);. This call will need to be echoed.


  1. <div id="rt-exampleposition">
  2. <?php echo $gantry->displayModules('example','standard','standard'); ?>
  3. <div class="clear"></div>
  4. </div>

The new position now will appear after we have configured the Gantry portion to recognize it. Until then, it will not work properly.


Step 3: Adding Position to Gantry Framework

Open templateDetails.xml and scroll down to the "positions" tag where the default Gantry positions are listed. Under here, we will need to add our "row module" positions a through f.


  1. <position id="example" name="Example" max_positions="6">Example</position>

Next: Scroll down to the line which says:

  1. <fieldset name="layouts" label="LAYOUTS">

This is where we add our new position layout slider. We need to add the following XML block to make this appear in Template Settings:

  1. <fields name="example" type="position" label="Example" description="LAYOUT_POS_DESC">
  2. <field name="layout" type="positions" default="3,3,3,3" label="">
  3. <schemas>1,2,3,4,5,6</schemas>
  4. <words>2,3,4,5,6,7,8,9,10</words>
  5. </field>
  6. <field name="showall" type="toggle" default="0" label="FORCE_POS"/>
  7. <field name="showmax" type="showmax" default="6" label="POS_COUNT"/>
  8. </fields>
Attribute Description
name Name of position
type Must always be "position"
default Default layout for the widget position any combination of 12 separated by commas.
label Label in Template Settings for this position.
description Description of what this area is used for.


Moving Widget Positions

This section covers moving a widget position within your Gantry enabled template.

Check out this quick screencast on Widget Positions to get an overview of how this feature works within Joomla and the Gantry Framework.


Step 1: Planning

Determine which widget position you want to move and where it needs to go within the index.php file of the template.


Step 2: Moving Module

Copy the Gantry widget position block of code you wish to move. It should look similar to this:

  1. <?php /** Begin Top **/ if ($gantry->countModules('top')) : ?>
  2. <div id="rt-top" <?php echo $gantry->displayClassesByTag('rt-top'); ?>>
  3. <div class="rt-container">
  4. <?php echo $gantry->displayModules('top','standard','standard'); ?>
  5. <div class="clear"></div>
  6. </div>
  7. </div>
  8. <?php /** End Top **/ endif; ?>

Move to the desired area and paste the copied block of code into the new location.


Custom Widget Layout

In this section, we will go over creating a custom XHTML layout for widgets in a Gantry enabled template.


Step 1: Preparation

Determine the name of your custom widget layout.


Step 2: Create/Copy New Layout File

The simplest way to do this is to copy an existing layout and modify it after. These files are located under YOUR_SITE/wp-content/plugins/gantry/html/layouts/, however, you do not want to modify the core Gantry files. Instead, copy the new layout file to YOUR_SITE/wp-content/themes/YOUR_TEMPLATE/html/layouts. In this case, use widget_standard.php.


Step 3: File Structure

Each custom widget layout requires a function render() this is what will be called by Gantry to display the layout. In this case, since we have copied an existing layout, it will already be provided.

At the top of this widget layout, there are Gantry-specific items which should not be modified. These are:

  1. function render($params = array()) {
  2. /** @global $gantry Gantry */
  3. global $gantry;
  4. $instance_params = $this->_getWidgetInstanceParams($params[0]['widget_id']);
  5. $chrome_to_use = (isset($instance_params['widget_chrome']) && !empty($instance_params['widget_chrome'])) ? $instance_params['widget_chrome'] : $params[0]['chrome'];
  6. $params = $gantry->renderLayout("chrome_" .$chrome_to_use, $params);
  8. $params[0]['position_open'] = '';
  9. $params[0]['position_close'] = '';
  11. $rparams = $this->_getParams($params[0]);
  12. $start_tag = "";
  14. // see if this is the first widget in the postion
  15. if (property_exists($rparams, 'start') && $rparams->start == $rparams->widget_id) {
  16. $prefixClass = '';
  17. // get the prefix class for the start
  18. if ($rparams->widget_map[$rparams->position]['prefixCount'] != 0) {
  19. $prefixClass = " rt-prefix-" . $rparams->widget_map[$rparams->position]['prefixCount'];
  20. }
  21. ob_start();
  23. .....

After the ob_start();, the layout should be written in XHTML.

After adding your XHTML code block, there must be a return with a call to ob_get_clean();. This is required for this function.

  1. $start_tag = ob_get_clean();
  2. $params[0]['position_open'] = $start_tag;
  3. }
  5. if (property_exists($rparams,'end') && $rparams->end == $rparams->widget_id) {
  6. $params[0]['position_close'] = "</div>";
  7. }
  9. $params[0]['before_widget'] = $params[0]['position_open'].$params[0]['before_widget'] ;
  10. $params[0]['after_widget'] = $params[0]['after_widget'] . $params[0]['position_close'];
  12. return $params;
  13. }

A full override looks like the following:

  1. class GantryLayoutWidget_Standard extends GantryLayout {
  2. var $render_params = array(
  3. 'gridCount' => null,
  4. 'prefixCount' => 0,
  5. 'extraClass' => ''
  6. );
  8. function render($params = array())
  9. {
  10. /** @global $gantry Gantry */
  11. global $gantry;
  12. $instance_params = $this->_getWidgetInstanceParams($params[0]['widget_id']);
  13. $chrome_to_use = (isset($instance_params['widget_chrome']) && !empty($instance_params['widget_chrome'])) ? $instance_params['widget_chrome'] : $params[0]['chrome'];
  14. $params = $gantry->renderLayout("chrome_" .$chrome_to_use, $params);
  16. $params[0]['position_open'] = '';
  17. $params[0]['position_close'] = '';
  19. $rparams = $this->_getParams($params[0]);
  20. $start_tag = "";
  22. // see if this is the first widget in the postion
  23. if (property_exists($rparams, 'start') && $rparams->start == $rparams->widget_id) {
  24. $prefixClass = '';
  25. // get the prefix class for the start
  26. if ($rparams->widget_map[$rparams->position]['prefixCount'] != 0) {
  27. $prefixClass = " rt-prefix-" . $rparams->widget_map[$rparams->position]['prefixCount'];
  28. }
  29. ob_start();
  30. ?>
  31. <div class="rt-grid-<?php echo $rparams->widget_map[$rparams->position]['paramsSchema'] . $prefixClass . $rparams->widget_map[$rparams->position]['extraClass']; ?>">
  32. <?php
  33. $start_tag = ob_get_clean();
  34. $params[0]['position_open'] = $start_tag;
  35. }
  37. if (property_exists($rparams, 'end') && $rparams->end == $rparams->widget_id) {
  38. $params[0]['position_close'] = "</div>";
  39. }
  41. $params[0]['before_widget'] = $params[0]['position_open'] . $params[0]['before_widget'];
  42. $params[0]['after_widget'] = $params[0]['after_widget'] . $params[0]['position_close'];
  44. return $params;
  45. }
  46. }


Step 4: Adding Layout to Template

Open up the templates index.php and find the widget position where we need to use the custom widget layout.

Edit the displayModules functions second parameter to the name of your custom widget layout which was created in step 3.


  1. <?php echo $gantry->displayModules('top', 'example', 'standard'); ?>


Custom Widget Chrome

This section covers the creation of a Chrome custom widget layout and how to link it into your Gantry enabled template.


Step 1: Planning

Determine the name of your custom widget position. In this case we will be using "example" as the custom Chrome widget name.


Step 2: Editing html/layouts/chrome_example.php

The files are located under YOUR_SITE/wp-content/plugins/gantry/html/layouts/, however, you do not want to modify the core Gantry files. Instead, copy the new Chrome file to YOUR_SITE/wp-content/themes/YOUR_TEMPLATE/html/layouts. In this case, use chrome_example.php. Each custom chrome layout requires a function render(). This is what will be called by Gantry to display the widget. Since we have copied an existing Chrome, this will already be provided.


  1. function render($params = array()) {
  2. global $gantry, $wp_registered_widgets;
  3. $rparams = $this->_getParams($params[0]);
  4. $instance_params = $this->_getWidgetInstanceParams($params[0]['widget_id']);
  6. $id = $params[0]['widget_id'];
  7. $classname = $wp_registered_widgets[$params[0]['widget_id']]['classname'];
  9. // gantry render params
  10. $params[0]['pre_widget'] = '';
  11. $params[0]['widget_open'] = '';
  12. $params[0]['title_open'] = '';
  13. $params[0]['title_close'] = '';
  14. $params[0]['widget_close'] = '';
  15. $params[0]['post_widget'] = '';
  16. $params[0]['pre_render'] = '';
  17. $params[0]['post_render'] = '';
  19. // normal wp widget params
  20. $params[0]['before_widget'] = '';
  21. $params[0]['before_title'] = '';
  22. $params[0]['after_title'] = '';
  23. $params[0]['after_widget'] = '';
  25. if (array_key_exists('custom-variations', $instance_params) && $instance_params['custom-variations'] != '') {
  26. $params[0]['pre_widget'] = '<div class="' . $instance_params['custom-variations'] . '">';
  27. $params[0]['post_widget'] = '</div>';
  28. }
  30. $params[0]['widget_open'] = sprintf('<div id="%1$s" class="widget %2$s rt-block">', $id, $classname);
  31. $params[0]['widget_close'] = '</div>';
  33. $params[0]['title_open'] = '<div class="module-title"><h2 class="title">';
  34. $params[0]['title_close'] = '</h2></div>';
  36. if (isset($instance_params['title']) && $instance_params['title'] != '') :
  37. $params[0]['before_widget'] = $params[0]['pre_widget'] . $params[0]['widget_open'];
  38. $params[0]['before_title'] = $params[0]['title_open'];
  39. $params[0]['after_title'] = $params[0]['title_close'] . $params[0]['pre_render'];
  40. $params[0]['after_widget'] = $params[0]['post_render'] . $params[0]['widget_close'] . $params[0]['post_widget']; else :
  41. $params[0]['before_widget'] = $params[0]['pre_widget'] . $params[0]['widget_open'] . $params[0]['pre_render'];
  42. $params[0]['before_title'] = $params[0]['title_open'];
  43. $params[0]['after_title'] = $params[0]['title_close'];
  44. $params[0]['after_widget'] = $params[0]['post_render'] . $params[0]['widget_close'] . $params[0]['post_widget'];
  45. endif;
  47. return $params;
  48. }

A full widget chrome looks like the following:

  1. class GantryLayoutChrome_Standard extends GantryLayout {
  2. var $render_params = array(
  3. 'gridCount' => null,
  4. 'prefixCount' => 0,
  5. 'extraClass' => ''
  6. );
  8. function render($params = array()) {
  9. global $gantry, $wp_registered_widgets;
  10. $rparams = $this->_getParams($params[0]);
  11. $instance_params = $this->_getWidgetInstanceParams($params[0]['widget_id']);
  13. $id = $params[0]['widget_id'];
  14. $classname = $wp_registered_widgets[$params[0]['widget_id']]['classname'];
  16. // gantry render params
  17. $params[0]['pre_widget'] = '';
  18. $params[0]['widget_open'] = '';
  19. $params[0]['title_open'] = '';
  20. $params[0]['title_close'] = '';
  21. $params[0]['widget_close'] = '';
  22. $params[0]['post_widget'] = '';
  23. $params[0]['pre_render'] = '';
  24. $params[0]['post_render'] = '';
  26. // normal wp widget params
  27. $params[0]['before_widget'] = '';
  28. $params[0]['before_title'] = '';
  29. $params[0]['after_title'] = '';
  30. $params[0]['after_widget'] = '';
  32. if (array_key_exists('custom-variations', $instance_params) && $instance_params['custom-variations'] != '') {
  33. $params[0]['pre_widget'] = '<div class="' . $instance_params['custom-variations'] . '">';
  34. $params[0]['post_widget'] = '</div>';
  35. }
  37. $params[0]['widget_open'] = sprintf('<div id="%1$s" class="widget %2$s rt-block">', $id, $classname);
  38. $params[0]['widget_close'] = '</div>';
  40. $params[0]['title_open'] = '<div class="module-title"><h2 class="title">';
  41. $params[0]['title_close'] = '</h2></div>';
  43. if (isset($instance_params['title']) && $instance_params['title'] != '') :
  44. $params[0]['before_widget'] = $params[0]['pre_widget'] . $params[0]['widget_open'];
  45. $params[0]['before_title'] = $params[0]['title_open'];
  46. $params[0]['after_title'] = $params[0]['title_close'] . $params[0]['pre_render'];
  47. $params[0]['after_widget'] = $params[0]['post_render'] . $params[0]['widget_close'] . $params[0]['post_widget']; else :
  48. $params[0]['before_widget'] = $params[0]['pre_widget'] . $params[0]['widget_open'] . $params[0]['pre_render'];
  49. $params[0]['before_title'] = $params[0]['title_open'];
  50. $params[0]['after_title'] = $params[0]['title_close'];
  51. $params[0]['after_widget'] = $params[0]['post_render'] . $params[0]['widget_close'] . $params[0]['post_widget'];
  52. endif;
  54. return $params;
  55. }
  56. }

Upon saving this custom widget, Chrome will be available to use in Gantry.


Step 3: Adding Custom Widget Chrome to Gantry

Open up the templates index.php file and find the Gantry widget position you wish to apply your custom widget layout too. In the third function parameter, add the name you gave to your Chrome widget after the "_" which, in the case of this demonstration, is "example."


  1. <?php echo $gantry->displayModules('top','standard','example'); ?>

If you wish to apply this to the main body sidebars, the layout will look like the following:

  1. <?php echo $gantry->displayMainbody('mainbody','sidebar', sidebarchromelayout, contenttoplayoutname, contenttopchromename, contentbottomlayoutname, contentbottomchromename); ?>

Any widget placed in this position will now use this display format.


Custom Presets

This section covers how to create a new custom preset in a Gantry enabled template.

Creating a custom preset is a remarkably straightforward task with Gantry. Check out this short video on how to customize your layout and create a custom preset based on your configuration options.


Step 1: Preparing

Gantry provides the ability for you to create your own custom presets based on any parameter in the template settings. You should determine which parameters you wish to configure to be a part of the presets. Write down their names as found in the templateDetails.xml file.


Step 2: Saving a Custom Preset

There are two types of presets. The first type of preset is the one defined by the template itself. This is located in the $gantry_presets variable located in the gantry.config.php file.

  1. $gantry_presets = array(
  2. 'presets' => array(
  3. 'preset1' => array(
  4. 'name' => 'Preset 1',
  5. 'cssstyle' => 'style1',
  6. 'linkcolor' => '#2698de',
  7. 'font-family' => 's:helvetica'
  8. ),
  9. 'preset2' => array(
  10. 'name' => 'Preset 2',
  11. 'cssstyle' => 'style2',
  12. 'linkcolor' => '#ff0000',
  13. 'font-family' => 's:helvetica'
  14. ),
  15. ...

This array contains a set of presets comprised of another array of parameters, in addition a special parameter called name, which is the display name for this preset.

The second kind of preset is the custom preset that you can save from the template settings page. If you set a bunch of parameters in the administrator, you can click Save Preset from the Save button dropdown and save as new preset. This will save the same parameters as defined in the $gantry_presets variable. If you want to save new parameters, you will also need to add them to the $gantry_presets variable in order for them to be saved as a custom preset. If you save a custom preset, Gantry will create a file called presets.ini in your YOUR_SITE/wp-content/themes/YOUR_TEMPLATE/custom/ folder.

In the example below, we saved a custom preset and chose the name "New Preset" in the pop-up dialog.

  1. newpreset_name="New Preset"
  2. newpreset_linkcolor="#db2c2c"
  3. newpreset_font-family="s:helvetica"


Step 3: Creating a Custom Thumbnail

When you create a new custom preset, there is a default image used in the preset chooser to represent this. You can create your own thumbnail for each style by creating a png file that is the 'short' name of the preset with the dimensions of 180px x 100px. For example, for my custom preset above, I would just create a small thumbnail called newpreset.png and put this file in the YOUR_SITE/wp-content/themes/YOUR_TEMPLATE/admin/presets/ folder.


Step 4: Adding to Gantry's Presets

To transfer one of the custom presets into the core gantry config file, you just need to convert the values in the preset.ini file into the array format as used in the gantry.config.php file. We've added this custom preset portion to the bottom of the array in the file:

  1. ...
  2. 'preset2' => array(
  3. 'name' => 'Preset 1',
  4. 'cssstyle' => 'style1',
  5. 'linkcolor' => '#2698de',
  6. 'font-family' => 's:helvetica'
  7. ),
  8. 'newpreset' => array(
  9. 'name' => 'New Preset',
  10. 'cssstyle' => 'style2',
  11. 'linkcolor' => '#db2c2c',
  12. 'font-family' => 's:helvetica'
  13. ),
  14. ...


Using Force Positions

There are times when you just don't want to have your widgets taking up all the room in a position no matter what the layout. For example, you might want to have a widget on the left and a widget on the right, with nothing in the middle. In traditional WordPress templates, you would have to resort to making two specific widget positions and using CSS, position them on the left and right sides of your design.

Forcing the widget positions is a powerful layout control. This short screencast provides some insight in how to achieve this and also the layout control that can be attained using this technique.

With Gantry, however, you can use the layouts settings to achieve this goal with no code or special CSS. First in the layouts settings, for the Utility Positions, set the Force Positions to On and then set the Position Count to 4.

This means that there will always be 4 utility widgets placed in the position (utility-a, utility-b, utility-c, utility-d) displayed no matter how many widgets you actually have placed in the widget position. Then all you need to do is place a widget in the utility-a position to show on the left, a widget in utility-d to show on the right.

Please note that you still need to use 3 Gantry Divider widgets in that position, but thanks to this option you don't need to have normal widgets between them.

Enter the Layouts section and toggle on the Force Positions for the widget position you are utilizing.

The result will be:


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 WordPress template. This makes it easier for you, the template developer, to write cleaner code. The Gantry library handles all the complicated bits for you.

Check out the Gantry introductory video to get a feel of the features and capabilities that you Gantry brings to the table. Powerful features, presets, layout configuration, responsive design, and much, much more.


Template index.php

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

  1. // no direct access
  2. defined( 'ABSPATH' ) or die( 'Restricted access' );
  4. global $gantry;

This top code block prevents the file from being called directly by typing its URL in the address bar. The global $gantry is there to provide extra layer of compatibility for third-party plugins.

Next, is the start of the HTML:

  1. <!doctype html>
  2. <html xml:lang="<?php echo $gantry->language; ?>" lang="<?php echo $gantry->language;?>" >
  3. <head>
  4. <?php if ($gantry->get('layout-mode') == '960fixed') : ?>
  5. <meta name="viewport" content="width=960px" />
  6. <?php elseif ($gantry->get('layout-mode') == '1200fixed') : ?>
  7. <meta name="viewport" content="width=1200px" />
  8. <?php else : ?>
  9. <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  10. <?php endif; ?>
  11. <?php
  12. $gantry->displayHead();
  14. $gantry->addStyle('grid-responsive.css', 5);
  15. $gantry->addLess('bootstrap.less', 'bootstrap.css', 6);
  16. $gantry->addLess('global.less', 'master.css', 8, array('headerstyle'=>$gantry->get('headerstyle','dark')));
  18. if ($gantry->browser->name == 'ie'){
  19. if ($gantry->browser->shortversion == 9){
  20. $gantry->addInlineScript("if (typeof RokMediaQueries !== 'undefined') window.addEvent('domready', function(){ RokMediaQueries._fireEvent(RokMediaQueries.getQuery()); });");
  21. }
  22. if ($gantry->browser->shortversion == 8){
  23. $gantry->addScript('html5shim.js');
  24. }
  25. }
  26. if ($gantry->get('layout-mode', 'responsive') == 'responsive') $gantry->addScript('rokmediaqueries.js');
  27. if ($gantry->get('loadtransition')) {
  28. $gantry->addScript('load-transition.js');
  29. $hidden = ' class="rt-hidden"';
  30. }
  31. ?>
  32. </head>

Here, you can see the traditional WordPress calls to get the language have been replaced with equivalent Gantry calls. Also, there's a call to include the head elements. These include CSS and JavaScript that have been initialized and set up in other parts of the Gantry framework. Also, there's a call to add some stylesheets to the head of the template, and a bunch of meta tags that tell the site how to behave for different screen resolutions.

This call has built-in logic, and will include core Gantry CSS files, as well as any CSS files that match these names in the template css folders. Any browser-specific versions of these files will be added, as well. For example, if you have /css/master-ie8.css in the template's CSS folder, it will get picked up, but will only be presented to IE8 browsers.

An important new feature in Gantry 4 is the ability to add and compile LESS files into CSS by using the addLess() method. You can also include JavaScript files with the addScript() method. Let's take a look at the next bit of the file that includes some references to some widget positions.

  1. <?php /** Begin Top Surround **/ if ($gantry->countModules('top')) : ?>
  2. <header id="rt-top-surround">
  3. <?php /** Begin Top **/ if ($gantry->countModules('top')) : ?>
  4. <div id="rt-top" <?php echo $gantry->displayClassesByTag('rt-top'); ?>>
  5. <div class="rt-container">
  6. <?php echo $gantry->displayModules('top','standard','standard'); ?>
  7. <div class="clear"></div>
  8. </div>
  9. </div>
  10. <?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 grabs all the template parameters that have been designated via templateDetails.xml to display them 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 no 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 widget chrome, also standard. More on these a little later.

This function performs all the output logic for a possible 6widget position: top-a, top-b, top-c, top-d, top-e, and top-f. You place your widgets on the Widgets configuration page like you usually would, but this method will do all the calculation concerning how the widgets 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 six individual widget positions within that one top position. Widget 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 template, as Gantry later translates them to the WordPress dynamic sidebars in order to show possible positions to place widgets. All the custom Gantry configuration options are located in the templateDetails.xml file. This file is broken down into fieldsets that define each 'tab' you see in the Template options.

The top of this file contains some base information about the template and its configuraiton. The top widget position has it's own configuration in the layouts section, along with a default value and some configuration settings that define which options are available. The abbreviated XML is demonstrated below:

  1. <positions>
  2. .....
  3. <position id="top" name="Top" max_positions="6">Top</position>
  4. .....
  5. </positions>
  6. .....
  7. <fields name="top" type="position" label="TOP_POS" description="LAYOUT_POS_DESC">
  8. <field name="layout" type="positions" default="3,3,3,3" label="">
  9. <schemas>1,2,3,4,5,6</schemas>
  10. <words>2,3,4,5,6,7,8,9,10</words>
  11. </field>
  12. <field name="showall" type="toggle" default="0" label="FORCE_POS"/>
  13. <field name="showmax" type="showmax" default="6" label="POS_COUNT"/>
  14. </fields>
  15. .....


Template Parameters

At this point, If you don't touch anything, the default layout will be an equal size for the placed widgets. However, with Gantry you can completely control how much room each widget 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 template parameters.

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

Overriding a Gizmo

A fundamental principle of Gantry Framework is its ability to be overridden so it can be as flexible as possible to suit the needs of an individual site or template. Gantry allows you to override Widget Layouts, Widget Chromes, Layouts, and provides a platform for extension overrides. The area of focus in this tutorial is that of Gizmos.


What is a Gizmo?

A gizmo is a standalone element that adds a specific utility to the template. It extends†the functionality of the template and can be configured, either generally or for specific overrides, using the Gantry administrator interface.

Gizmos are located at /wp-content/plugins/gantry/gizmos/ and include a variety of different types such as Google Analytics, Page Suffix and RokStyle. There are many other default gizmos†included.

Below is an example of the /wp-content/plugins/gantry/gizmos/pagesuffix.php gizmo:

  1. <?php
  2. defined('GANTRY_VERSION') or die();
  4. gantry_import('core.gantrygizmo');
  6. /**
  7. * @package gantry
  8. * @subpackage features
  9. */
  10. class GantryGizmoPageSuffix extends GantryGizmo
  11. {
  13. var $_name = 'pagesuffix';
  15. function query_parsed_init() {
  17. /** @global $gantry Gantry */
  18. global $gantry;
  20. //add body class suffix
  21. $gantry->addBodyClass($gantry->get('pagesuffix-class'));
  23. }
  25. }

There are several parts to a gizmo. First, the following sets the file as a Gantry Gizmo, importing the necessary functions:

  1. <?php
  2. defined('GANTRY_VERSION') or die();
  4. gantry_import('core.gantrygizmo');

Next, the feature is then differentiated by a name, in this case GantryGizmoPageSuffix and 'pagesuffix':

  1. class GantryGizmoPageSuffix extends GantryGizmo
  2. {
  3. var $_name = 'pagesuffix';

Immediately following the naming of the feature, there is some additional processing code that should not be modified.

  1. function query_parsed_init() {
  2. ?>

The next area of the feature is the XHTML layout or code you want to execute :

  1. /** @global $gantry Gantry */
  2. global $gantry;
  4. //add body class suffix
  5. $gantry->addBodyClass($gantry->get('pagesuffix-class'));

After the above code, the following completes the gizmo:

  1. <?php
  2. }
  3. }

Overriding a Gizmo

Gantry allows gizmos to be overridden by either copying a gizmo directly from /wp-content/plugins/gantry/gizmos/ or creating a new pagesuffix.php file at /wp-content/themes/[TEMPLATE]/gizmos/.

A gizmo file must follow the format listed in the section above. There are, in effect, just two areas of modification.

The first is the name. This must be unique in order to avoid conflicts.

The second is the XHTML layout or other PHP code where you can construct the gizmos to meet your needs.

Gizmos and the Administrator

Depending on the level of modification you plan for a particular gizmo, you may wish to edit its parameters. For this, you will need to edit the /wp-content/themes/[TEMPLATE]/templateDetails.xml file.

The relevant part of this XML file begins with:

  1. <fieldset name="gizmos" label="GIZMOS">

Here, you can locate the relevant field(s) for the gizmo you wish to modify such as pagesuffix:

  1. <fields name="pagesuffix" type="chain" label="PAGESUFFIX" description="PAGESUFFIX_DESC">
  2. <field name="enabled" type="toggle" default="0" label="ENABLED" enabler="true" />
  3. <field name="class" type="text" default="" class="text-long" label="CLASS"/>
  4. <field name="priority" type="hidden" default="2"/>
  5. </fields>


Creating an Unsupported Page

This tutorial will take you through the steps needed to create an unsupported browser page functionality as used here on You can see what this looks like by pointing your browser to: Users of unsupported browsers (IE6 and IE7) are automatically taken to this page whenever they try to access a page on


Step 1: Unsupported Browser Redirect Feature

The logic for this unsupported browser page is powered by a custom gizmo that we'll call unsupportedredirect.php. This is a custom gizmo that we will create and drop into the template's gizmos/ folder. The code is very simple, as you can see below:

  1. <?php
  2. /**
  3. * @version ${project.version} ${build_date}
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. */
  9. defined('GANTRY_VERSION') or die();
  11. gantry_import('core.gantrygizmo');
  13. /**
  14. * @package gantry
  15. * @subpackage features
  16. */
  17. class GantryGizmoUnsupportedRedirect extends GantryGizmo {
  19. var $_name = 'unsupportedredirect';
  21. function isEnabled() {
  22. return true;
  23. }
  25. function init() {
  27. global $gantry;
  29. $request = basename($_SERVER['REQUEST_URI']);
  31. if ($request != 'unsupported.php' && $gantry->browser->name == 'ie' && ($gantry->browser->shortversion == '6' || $gantry->browser->shortversion == '7')) {
  32. add_filter('template_include', array(&$this, 'unsupported_redirect'));
  33. }
  35. }
  37. static function unsupported_redirect($template) {
  38. return locate_template(array('unsupported.php'));
  39. }
  41. }

This feature is fairly straightforward, but we'll break it down into parts so you can see how it works.



The isEnabled() method is set to true because we are effectively forcing this gizmo to be enabled. We don't need any user interaction to toggle this functionality, though that could easily be added by adding a simple bit of XML in the templateDetails.xml if needed.



This is where the logic actually happens. The init() method is the better place for any non-rendering functionality. As you can see here, a simple if statement ensures that we are not already on the unsupported page, the viewing browser is ie, and the short version is 6 or 7. This ensures that only IE6 and IE7 browsers will enter the if statement and load the unsupported.php page.


Step 2: Unsupported TMPL File

As you saw at the end of Step 1, we've redirected IE6 and IE7 users to unsupported.php, but what does this mean? We are going to filter out the template_include WordPress filter and load our own file when browser conditions are met. By default, WordPress looks for index.php inside your template folder, however, if we are going to use the mentioned previously filter, we can override this behavior. This forces WordPress to load different php file.

The unsupported.php is basically a stripped down version of our existing index.php file as you can see below:

  1. <?php
  2. /**
  3. * @version ${project.version} ${build_date}
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. */
  8. // no direct access
  9. defined('ABSPATH') or die('Restricted access');
  10. ?>
  11. <!doctype html>
  12. <html xml:lang="<?php echo $gantry->language; ?>" lang="<?php echo $gantry->language;?>" >
  13. <head>
  14. <meta name="viewport" content="width=device-width, initial-scale=1.0">
  15. <?php
  16. $gantry->displayHead();
  17. $gantry->addLess('global.less', 'master.css');
  18. ?>
  19. </head>
  20. <div id="body-wrapper">
  21. <div id="rt-showcase">
  22. <div class="rt-showcase-pattern">
  23. <div class="rt-showcase-pattern-2">
  24. <div class="rt-container">
  25. <div class="rt-grid-12 rt-alpha rt-omega">
  26. <div class="rt-block main-showcase-logo">
  27. <div class="module-surround">
  28. <div class="module-content">
  29. <div class="custom main-showcase-logo">
  30. <div class="showcase-image">
  31. <img src="/gantry/g-f/images/gantry_site/showcase-logo.png" alt="">
  32. </div>
  33. <div class="showcase-content">
  34. <h1>
  35. <span class="gantry-logo">Gantry</span> <small>Web Platform Theme Framework</small>
  36. </h1>
  37. <h1>
  38. <b>Unsupported Browser</b>
  39. </h1>
  40. <p>
  41. You are using a browser that is not supported by this website. That probably means your browser is woefully out of date, insecure, and just generally lacking in standards. Luckily for you there are literally 10s of modern, standards compatible browsers available to you at no cost. All you need to do is simply take the time to install one.
  42. </p>
  43. <p>
  44. We suggest installing the latest version of <a href="">Firefox</a>, <a href="">Google Chrome</a>, <a href="">Safari</a>, heck, even <a href="">Opera</a> would be a better option.
  45. </p>
  46. </div>
  47. </div>
  48. </div>
  49. </div>
  50. </div>
  51. </div>
  52. </div>
  53. <div class="clear"></div>
  54. </div>
  55. </div>
  56. </div>
  57. </div>
  58. </html>
  59. <?php
  60. $gantry->finalize();
  61. ?>

Basically, we've removed all the extraneous widget calls and left the page in a basic hard-coded state. You could, of course, keep some of the widget positions (if needed), but we opted for the simple approach and kept the output as basic as possible. This is done while still offering the feel of the regular site.


Step 3: Tweaking and Testing

At this point, you should have a full, functional gizmo. You should be able to tweak and optimize this output to suit your individual needs. We kept ours pretty similar to our regular page, but also included our regular template.css and wordpress.css files, as well as a new unsupported.css file which has some styling that is only needed on this particular page. You can see these in the addStyles() method in the unsupported.php file, listed above.

After you are pretty happy with the way this looks, the final step is to test it against IE6 an IE7.

You should be able to point your IE6 or IE7 browser directly at your site: http://YOUR_SITE, and it should redirect you automatically to the unsupported page. Just tweak and adjust your CSS as needed to ensure that things look correct in IE6, as this is the only browser that really sees it.

That's it! Pretty easy, right?


Creating a Popup Login

This tutorial details how to create a custom widget that will utilize RokBox to present a modal popup box triggered by a link/button on the frontend. For this tutorial, we will be making a login widget popup.

NOTE: The login popup functionality requires that the RokBox Plugin be installed on your site. Before beginning, please ensure that you have downloaded and installed the latest version of RokBox.


Step 1: Creating the Custom Widget

The login form used in our site will be contained in a new file named loginform.php. This is a custom widget created for this example and dropped into the theme's widgets/ directory. Create this new php file with the following code:

  1. <?php
  2. /**
  3. * @version ${project.version} ${build_date}
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. */
  9. defined('GANTRY_VERSION') or die();
  11. gantry_import('core.gantrywidget');
  13. add_action('widgets_init', array("GantryWidgetLoginForm","init"));
  15. class GantryWidgetLoginForm extends GantryWidget {
  16. var $short_name = 'loginform';
  17. var $wp_name = 'gantry_loginform';
  18. var $long_name = 'Gantry Login Form';
  19. var $description = 'Gantry Login Form Widget';
  20. var $css_classname = 'widget_gantry_loginform';
  21. var $width = 200;
  22. var $height = 400;
  24. function init() {
  25. register_widget("GantryWidgetLoginForm");
  26. }
  28. function render_title($args, $instance) {
  29. global $gantry;
  30. if($instance['title'] != '') :
  31. echo $instance['title'];
  32. endif;
  33. }
  35. function render($args, $instance){
  36. global $gantry, $current_user;
  37. ob_start();
  38. ?>
  40. <?php if(!is_user_logged_in()) : ?>
  42. <form action="<?php echo wp_login_url($_SERVER['REQUEST_URI']); ?>" method="post" id="login-form">
  43. <?php if ($instance['pretext'] != ''): ?>
  44. <div class="pretext">
  45. <p><?php echo $instance['pretext']; ?></p>
  46. </div>
  47. <?php endif; ?>
  48. <fieldset class="userdata">
  49. <p id="form-login-username">
  50. <label for="modlgn-username"><?php _re('User Name'); ?></label>
  51. <input id="modlgn-username" type="text" name="log" class="inputbox" alt="username" size="18" value="" />
  52. </p>
  53. <p id="form-login-password">
  54. <label for="modlgn-passwd"><?php _re('Password'); ?></label>
  55. <input id="modlgn-passwd" type="password" name="pwd" class="inputbox" size="18" alt="password" value="" />
  56. </p>
  57. <p id="form-login-remember">
  58. <label for="modlgn-remember"><?php _re('Remember Me'); ?></label>
  59. <input id="modlgn-remember" type="checkbox" name="rememberme" class="inputbox" />
  60. </p>
  61. <input type="submit" value="<?php _re('Log in'); ?>" class="button" name="submit" />
  62. </fieldset>
  63. <ul>
  64. <li>
  65. <a href="/<?php echo wp_lostpassword_url(); ?>"><?php _re('Forgot your password?'); ?></a>
  66. </li>
  67. <?php if(get_option('users_can_register')) : ?>
  68. <li>
  69. <a href="/<?php echo site_url('/wp-login.php?action=register&redirect_to=' . get_permalink()); ?>"><?php _re('Register'); ?></a>
  70. </li>
  71. <?php endif; ?>
  72. </ul>
  73. <?php if ($instance['posttext'] != ''): ?>
  74. <div class="posttext">
  75. <p><?php echo $instance['posttext']; ?></p>
  76. </div>
  77. <?php endif; ?>
  78. </form>
  80. <?php else : ?>
  82. <form action="<?php echo wp_logout_url($_SERVER['REQUEST_URI']); ?>" method="post" id="login-form">
  83. <div class="login-greeting">
  84. <p><?php echo $instance['user_greeting']; ?> <?php echo $current_user->display_name; ?></p>
  85. </div>
  86. <div class="logout-button">
  87. <input type="submit" name="Submit" class="button" value="<?php _re('Log out'); ?>" />
  88. </div>
  89. </form>
  91. <?php endif; ?>
  93. <?php
  95. echo ob_get_clean();
  97. }
  98. }

The xml definition file is also a critical component. Create the new file loginform.xml with following code:

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!-- $Id: style.xml 16565 2010-04-28 12:21:27Z ian $ -->
  3. <form>
  4. <fieldset name="widget">
  5. <field name="title" type="text" label="Title" description="Title" default="Login Form" class="widefat" readonly="false"/>
  6. <field name="user_greeting" type="text" label="User Greeting" description="Text to be displayed as an user greeting" default="Hi," class="widefat" readonly="false"/>
  7. <field name="pretext" type="text" label="Pre-text" description="Text to be displayed before the login form" default="" class="widefat" readonly="false"/>
  8. <field name="posttext" type="text" label="Post-text" description="Text to be displayed after the login form" default="" class="widefat" readonly="false"/>
  9. </fieldset>
  10. </form>

When this widget is placed in a position, it will render the login form we want to appear in the popup.


Step 2: Creating Login Button Widget

The link/button that triggers the popup widget will be contained in a new file that named loginbutton.php. This is a custom widget created for this example and dropped into the theme's widgets/ directory. Create this new php file with the following code:

  1. <?php
  2. /**
  3. * @version ${project.version} ${build_date}
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. */
  9. defined('GANTRY_VERSION') or die();
  11. gantry_import('core.gantrywidget');
  13. add_action('widgets_init', array("GantryWidgetLoginButton","init"));
  15. class GantryWidgetLoginButton extends GantryWidget {
  16. var $short_name = 'loginbutton';
  17. var $wp_name = 'gantry_loginbutton';
  18. var $long_name = 'Gantry Login Button';
  19. var $description = 'Gantry Login Button Widget';
  20. var $css_classname = 'widget_gantry_loginbutton';
  21. var $width = 200;
  22. var $height = 400;
  24. function init() {
  25. register_widget("GantryWidgetLoginButton");
  26. }
  28. function render_widget_open($args, $instance) {
  29. }
  31. function render_widget_close($args, $instance) {
  32. }
  34. function pre_render($args, $instance) {
  35. }
  37. function post_render($args, $instance) {
  38. }
  40. function render_title($args, $instance) {
  41. global $gantry;
  42. if($instance['title'] != '') :
  43. echo $instance['title'];
  44. endif;
  45. }
  47. function render($args, $instance){
  48. global $gantry, $current_user;
  49. ob_start();
  50. ?>
  52. <div id="<?php echo $this->id; ?>" class="widget <?php echo $this->css_classname; ?> rt-block">
  53. <div class="rt-popupmodule-button">
  54. <?php if(!is_user_logged_in()) : ?>
  55. <a href="#" class="buttontext button" rel="rokbox[355 385][module=rt-popuplogin]">
  56. <span class="desc"><?php echo $instance['logintext']; ?></span>
  57. </a>
  58. <?php else : ?>
  59. <a href="/<?php echo wp_logout_url($_SERVER['REQUEST_URI']); ?>" class="buttontext button">
  60. <span class="desc"><?php echo $instance['logouttext']; ?> <?php echo $current_user->display_name; ?></span>
  61. </a>
  62. <?php endif; ?>
  63. </div>
  64. </div>
  66. <?php
  68. echo ob_get_clean();
  70. }
  71. }

This code consists mostly of a standard set of divs to provide styling potential. There are also some key RokBox syntax items, as well as the reference for some dynamic text that we will breakdown in more detail below:


RokBox Syntax

  1. <a href="#" class="buttontext button" rel="rokbox[355 385][module=rt-popuplogin]">

The actual link makes use of the RokBox link syntax for calling a login form widget into the popup. Using the rel= tag we are declaring the size (width height) of our intended popup. ex: rokbox[355 385]. You can adjust these width and height values to match the content you plan to have in your popup.

Immediately following width and height declaration, we are referencing the widget's surrounding div which tells RokBox which item needs to be placed into the popup. This surrounding div (rt-popuplogin in our example) will be placed in a widget chrome later on in the tutorial.

XML definition file goes here as well :

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!-- $Id: style.xml 16565 2010-04-28 12:21:27Z ian $ -->
  3. <form>
  4. <fieldset name="widget">
  5. <field name="title" type="text" label="Title" description="Title" default="" class="widefat" readonly="false"/>
  6. <field name="logintext" type="text" label="Login Text" description="Login Text" default="Login" class="widefat" readonly="false"/>
  7. <field name="logouttext" type="text" label="Logout Text" description="Logout Text" default="Logout" class="widefat" readonly="false"/>
  8. </fieldset>
  9. </form>


Step 3: Creating the Widget Layout

Next, we will be creating a custom chrome that takes advantage of Gantry's ability to define custom layouts for positions. This allows for greater flexibility and significantly cleaner code in the index.

We will be creating a new file named widget_login.php and placing it into the /html/layouts directory of the template. If /html/layouts doesn't exist in your template, you can create this directory.

Paste the following code into your new file:

  1. <?php
  2. /**
  3. * @version ${project.version} ${build_date}
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. *
  8. */
  9. defined('GANTRY_VERSION') or die();
  11. gantry_import('core.gantrylayout');
  13. /**
  14. *
  15. * @package gantry
  16. * @subpackage html.layouts
  17. */
  18. class GantryLayoutWidget_Login extends GantryLayout {
  19. var $render_params = array(
  20. 'gridCount' => null,
  21. 'prefixCount' => 0,
  22. 'extraClass' => ''
  23. );
  25. function render($params = array()){
  26. global $gantry;
  28. $params = $gantry->renderLayout("chrome_".$params[0]['chrome'], $params);
  30. $params[0]['position_open'] ='';
  31. $params[0]['position_close'] ='';
  33. $rparams = $this->_getParams($params[0]);
  34. $start_tag = "";
  36. // see if this is the first widget in the postion
  37. if (property_exists($rparams,'start') && $rparams->start == $rparams->widget_id) {
  38. ob_start();
  39. ?>
  40. <div id="rt-popuplogin">
  41. <?php
  42. $start_tag = ob_get_clean();
  43. $params[0]['position_open'] = $start_tag;
  44. }
  46. if (property_exists($rparams,'end') && $rparams->end == $rparams->widget_id) {
  47. $params[0]['position_close'] = "</div>";
  48. }
  50. $params[0]['before_widget'] = $params[0]['position_open'].$params[0]['before_widget'] ;
  51. $params[0]['after_widget'] = $params[0]['after_widget'] . $params[0]['position_close'];
  53. return $params;
  54. }
  55. }

This custom layout allows us to reference it in our index.php using the name following the widget_ which is simply login. Once it is done, it will render all of the html inside around the entire position allowing us to keep the index.php much more concise. For this example, we've used just a single wrapper div #rt-popuplogin, but you can add as many elements as you need for any design considerations you have.


Step 4: Creating the Widget Chrome

You can also set up a widget chrome for the login widget as defined in the part above. For this, you'll need to create the /html/layouts/chrome_login.php file (if it doesn't exist).

Insert the following:

  1. <?php
  2. /**
  3. * @version ${project.version} ${build_date}
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. */
  8. defined( 'GANTRY_VERSION' ) or die();
  10. gantry_import( 'core.gantrylayout' );
  12. /**
  13. *
  14. * @package gantry
  15. * @subpackage html.layouts
  16. */
  17. class GantryLayoutChrome_Login extends GantryLayout {
  18. var $render_params = array(
  19. 'gridCount' => null,
  20. 'prefixCount' => 0,
  21. 'extraClass' => ''
  22. );
  24. function render( $params = array() ){
  25. global $gantry, $wp_registered_widgets;
  26. $rparams = $this-> _getParams( $params[0] );
  27. $instance_params = $this->_getWidgetInstanceParams( $params[0]['widget_id'] );
  29. $id = $params[0]['widget_id'];
  30. $classname = $wp_registered_widgets[$params[0]['widget_id']]['classname'];
  32. // gantry render params
  33. $params[0]['pre_widget'] = '';
  34. $params[0]['widget_open'] = '';
  35. $params[0]['title_open'] = '';
  36. $params[0]['title_close'] = '';
  37. $params[0]['widget_close'] = '';
  38. $params[0]['post_widget'] = '';
  39. $params[0]['pre_render'] = '';
  40. $params[0]['post_render'] = '';
  42. // normal wp widget params
  43. $params[0]['before_widget'] = '';
  44. $params[0]['before_title'] = '';
  45. $params[0]['after_title'] = '';
  46. $params[0]['after_widget'] = '';
  48. $widget_variations = $pre_widget = $post_widget = $widget_open = $widget_close = $title_open = $title_close = $pre_render = $post_render = '';
  50. $variations = array( 'custom-variations', 'box-variations', 'title-variations' );
  52. foreach ( $variations as $variation ) {
  53. if ( array_key_exists( $variation, $instance_params ) && $instance_params[$variation] != false ) {
  54. if ( $instance_params[$variation] != '' ) $widget_variations .= ' ' . $instance_params[$variation];
  55. }
  56. }
  58. $widget_variations = trim( $widget_variations );
  59. ( $widget_variations != '' ) ? $widget_variations = ' ' . $widget_variations : $widget_variations = '';
  61. ?>
  63. <?php /** Begin Chrome Layout **/ ?>
  65. <?php ob_start(); ?>
  66. <div id="<?php echo $id; ?>" class="widget <?php echo $classname . $widget_variations; ?> rt-block">
  67. <div class="module-content">
  68. <?php $widget_open = ob_get_clean(); ?>
  69. <?php ob_start(); ?>
  70. <h2 class="title">
  71. <?php $title_open = ob_get_clean(); ?>
  72. <?php ob_start(); ?>
  73. </h2>
  74. <?php $title_close = ob_get_clean(); ?>
  75. <?php ob_start(); ?>
  76. <div class="module-inner">
  77. <?php $pre_render = ob_get_clean(); ?>
  78. <?php ob_start(); ?>
  79. </div>
  80. <?php $post_render = ob_get_clean(); ?>
  81. <?php ob_start(); ?>
  82. </div>
  83. </div>
  84. <?php $widget_close = ob_get_clean(); ?>
  86. <?php /** End Chrome Layout **/ ?>
  88. <?php
  90. $params[0]['pre_widget'] = $pre_widget;
  91. $params[0]['post_widget'] = $post_widget;
  93. $params[0]['widget_open'] = $widget_open;
  94. $params[0]['widget_close'] = $widget_close;
  96. $params[0]['title_open'] = $title_open;
  97. $params[0]['title_close'] = $title_close;
  99. $params[0]['pre_render'] = $pre_render;
  100. $params[0]['post_render'] = $post_render;
  102. if( !empty( $instance_params['title'] ) ) {
  103. $params[0]['before_widget'] = $params[0]['pre_widget'] . $params[0]['widget_open'];
  104. $params[0]['before_title'] = $params[0]['title_open'];
  105. $params[0]['after_title'] = $params[0]['title_close'] . $params[0]['pre_render'];
  106. $params[0]['after_widget'] = $params[0]['post_render'] . $params[0]['widget_close'] . $params[0]['post_widget'];
  107. } else {
  108. $params[0]['before_widget'] = $params[0]['pre_widget'] . $params[0]['widget_open'] . $params[0]['pre_render'];
  109. $params[0]['before_title'] = $params[0]['title_open'];
  110. $params[0]['after_title'] = $params[0]['title_close'];
  111. $params[0]['after_widget'] = $params[0]['post_render'] . $params[0]['widget_close'] . $params[0]['post_widget'];
  112. }
  114. return $params;
  116. }
  117. }


Step 5: Defining the position in the index.php

Now, we want to add the new widget position to be called into the RokBox popup. It is important to create a new widget position for this purpose. It will be hidden by CSS until it is triggered, and we want it to be out of the normal flow of the page.

For this example, we are creating a position simply called login. We are going to add the following code near the very end of our template's index.php file, immediately before the closing body tag:

  1. <?php /** Begin Popup **/
  2. echo $gantry->displayModules('login','login','login');
  3. /** End Popup **/ ?>

Inside of the displayModules function, we are making three references. The first refers to the name of the widget position. The second refers to the layout we wish to use for this position.

This is now referencing our widget_login.php layout we created in the Step 3), the third refers to the widget chrome to be applied to each rendering of the widget (this references your login chrome located in /html/layouts/chrome_login.php. For this example, we are simply using the standard style.


Step 6: Adding the Widget Position

Now, it's time to define our new widget position in the administration. All of the widgets placed in that position will be displayed in the RokBox popup.



We want to open up the template's templateDetails.xml file. Inside the first area, we want to add a line to the positions section. Look for the listing of widget positions that begins with the tag <positions>. At the bottom of the list, immediately before the </positions> tag, add the following:

  1. <position id="login" name="Login" max_positions="1">Login</position>

This code adds the login position to Gantry and WordPress. It allows the WordPress to render the Login position in the widgets manager, so you can place any widgets (that you want to appear in the popup) inside.


Step 7: Adding the CSS

Lastly, in terms of coding, CSS will need to be added to style the widget position. Place the CSS in the most appropriate file. If you are using LESS, this will be /less/template.less. If you are just using CSS, then /css/template.css is where you want to go. The following is required for the login to function:

  1. #rt-popuplogin { display: none; }

You will most likely want to add additional CSS, which you can do by using the #rt-popuplogin ID. This will apply strictly to the popup login.


Step 8: Putting it all together

Now, all of our logic and core items are in place. We are ready to place the Login Form widget in the Login position, and the Login Button in any other position you want it to appear.

You can modify the settings of the widgets to match your personal preferences. Once you are done, Save, then refresh your site to review the changes.


Adding a Custom Mainbody Layout

Gantry Framework ships with 38 possible layout combinations for the mainbody area. The mainbody is considered to comprise of the mainbody itself (where the content is displayed), along with up to three additional sidebars for other widgets.

For the 12-column layout variation, these layouts are controlled by two variables called $gantry_default_pushpullschemas and $gantry_default_mainbodyschemacombos which are found in wp-content/plugins/gantry/gantry.config.php. The 12-column portion of this file looks like this:

  1. $gantry_default_pushpullschemas = array(
  2. ....snip....
  3. 'mb12' => array(''),
  5. 'mb6-sa6' => array ('',''),
  6. 'mb7-sa5' => array ('',''),
  7. 'mb8-sa4' => array ('',''),
  8. 'mb9-sa3' => array ('',''),
  10. 'sa6-mb6' => array ('rt-push-6','rt-pull-6'),
  11. 'sa5-mb7' => array ('rt-push-5','rt-pull-7'),
  12. 'sa4-mb8' => array ('rt-push-4','rt-pull-8'),
  13. 'sa3-mb9' => array ('rt-push-3','rt-pull-9'),
  15. 'mb4-sa4-sb4' => array('','',''),
  16. 'mb6-sa3-sb3' => array('','',''),
  17. 'mb8-sa2-sb2' => array('','',''),
  19. 'sa4-mb4-sb4' => array('rt-push-4','rt-pull-4',''),
  20. 'sa3-mb6-sb3' => array('rt-push-3','rt-pull-6',''),
  21. 'sa2-mb8-sb2' => array('rt-push-2','rt-pull-8',''),
  23. 'sa4-sb4-mb4' => array('rt-push-8','rt-pull-4','rt-pull-4'),
  24. 'sa3-sb3-mb6' => array('rt-push-6','rt-pull-6','rt-pull-6'),
  25. 'sa2-sb2-mb8' => array('rt-push-4','rt-pull-8','rt-pull-8'),
  27. 'mb3-sa3-sb3-sc3' => array('','','',''),
  28. 'mb4-sa2-sb3-sc3' => array('','','',''),
  29. 'mb4-sa3-sb2-sc3' => array('','','',''),
  30. 'mb4-sa3-sb3-sc2' => array('','','',''),
  31. 'mb6-sa2-sb2-sc2' => array('','','',''),
  33. 'sa3-mb3-sb3-sc3' => array('rt-push-3','rt-pull-3','',''),
  34. 'sa3-mb4-sb2-sc3' => array('rt-push-3','rt-pull-4','',''),
  35. 'sa2-mb4-sb3-sc3' => array('rt-push-2','rt-pull-4','',''),
  36. 'sa3-mb4-sb3-sc2' => array('rt-push-3','rt-pull-4','',''),
  37. 'sa2-mb6-sb2-sc2' => array('rt-push-2','rt-pull-6','',''),
  39. 'sa3-sb3-mb3-sc3' => array('rt-push-6','rt-pull-3','rt-pull-3',''),
  40. 'sa3-sb2-mb4-sc3' => array('rt-push-5','rt-pull-4','rt-pull-4',''),
  41. 'sa2-sb3-mb4-sc3' => array('rt-push-5','rt-pull-4','rt-pull-4',''),
  42. 'sa3-sb3-mb4-sc2' => array('rt-push-6','rt-pull-4','rt-pull-4',''),
  43. 'sa2-sb2-mb6-sc2' => array('rt-push-4','rt-pull-6','rt-pull-6',''),
  45. 'sa3-sb3-sc3-mb3' => array('rt-push-9','rt-pull-3','rt-pull-3','rt-pull-3'),
  46. 'sa3-sb3-sc2-mb4' => array('rt-push-8','rt-pull-4','rt-pull-4','rt-pull-4'),
  47. 'sa3-sb2-sc3-mb4' => array('rt-push-8','rt-pull-4','rt-pull-4','rt-pull-4'),
  48. 'sa2-sb3-sc3-mb4' => array('rt-push-8','rt-pull-4','rt-pull-4','rt-pull-4'),
  49. 'sa2-sb2-sc2-mb6' => array('rt-push-6','rt-pull-6','rt-pull-6','rt-pull-6'),
  50. ....snip....
  51. );

This is actually quite readable, and you can translate mbX to equal mainbody occupying X column grids. saX means the sidebar-a widget position occupies X column grids. The stuff on the right side of the array relates to the push/pull classes which are needed to achieve this layout. Even though you can change the column order in the layout, you aren't physically moving the columns, it's 100% CSS in order to ensure source-ordering and SEO optimization (unless using ordered mainbody layout).

The second variable contains similar data, but it's laid out in a different way. The 12-column part looks like:

  1. $gantry_default_mainbodyschemascombos = array(
  2. ....snip....
  3. 12 => array(
  4. 1 => array(
  5. array('mb'=>12)
  6. ),
  7. 2 => array(
  8. array('mb'=>6, 'sa'=>6),
  9. array('mb'=>7, 'sa'=>5),
  10. array('mb'=>8, 'sa'=>4),
  11. array('mb'=>9, 'sa'=>3),
  13. array('sa'=>6, 'mb'=>6),
  14. array('sa'=>5, 'mb'=>7),
  15. array('sa'=>4, 'mb'=>8),
  16. array('sa'=>3, 'mb'=>9)
  17. ),
  18. 3 => array(
  19. array('mb'=>4, 'sa'=>4, 'sb'=>4),
  20. array('mb'=>6, 'sa'=>3, 'sb'=>3),
  21. array('mb'=>8, 'sa'=>2, 'sb'=>2),
  23. array('sa'=>4, 'mb'=>4, 'sb'=>4),
  24. array('sa'=>3, 'mb'=>6, 'sb'=>3),
  25. array('sa'=>2, 'mb'=>8, 'sb'=>2),
  27. array('sa'=>4, 'sb'=>4, 'mb'=>4),
  28. array('sa'=>3, 'sb'=>3, 'mb'=>6),
  29. array('sa'=>2, 'sb'=>2, 'mb'=>8)
  30. ),
  31. 4 => array(
  32. array('mb'=>3, 'sa'=>3, 'sb'=>3, 'sc'=>3),
  33. array('mb'=>4, 'sa'=>2, 'sb'=>3, 'sc'=>3),
  34. array('mb'=>4, 'sa'=>3, 'sb'=>2, 'sc'=>3),
  35. array('mb'=>4, 'sa'=>3, 'sb'=>3, 'sc'=>2),
  36. array('mb'=>6, 'sa'=>2, 'sb'=>2, 'sc'=>2),
  38. array('sa'=>3, 'mb'=>3, 'sb'=>3, 'sc'=>3),
  39. array('sa'=>3, 'mb'=>4, 'sb'=>2, 'sc'=>3),
  40. array('sa'=>2, 'mb'=>4, 'sb'=>3, 'sc'=>3),
  41. array('sa'=>3, 'mb'=>4, 'sb'=>3, 'sc'=>2),
  42. array('sa'=>2, 'mb'=>6, 'sb'=>2, 'sc'=>2),
  44. array('sa'=>3, 'sb'=>3, 'mb'=>3, 'sc'=>3),
  45. array('sa'=>3, 'sb'=>2, 'mb'=>4, 'sc'=>3),
  46. array('sa'=>2, 'sb'=>3, 'mb'=>4, 'sc'=>3),
  47. array('sa'=>3, 'sb'=>3, 'mb'=>4, 'sc'=>2),
  48. array('sa'=>2, 'sb'=>2, 'mb'=>6, 'sc'=>2),
  50. array('sa'=>3, 'sb'=>3, 'sc'=>3, 'mb'=>3),
  51. array('sa'=>3, 'sb'=>3, 'sc'=>2, 'mb'=>4),
  52. array('sa'=>3, 'sb'=>2, 'sc'=>3, 'mb'=>4),
  53. array('sa'=>2, 'sb'=>3, 'sc'=>3, 'mb'=>4),
  54. array('sa'=>2, 'sb'=>2, 'sc'=>2, 'mb'=>6)
  55. )
  56. ),
  57. ....snip....
  58. );

Again, this is pretty easy to break down. The key in the associative array relates to the number of columns. In this case there's 12. The second set of keys relates to the number of columns. Here, there's 1 through 4 total columns as options. In the two-column value, you see yet another array with all the combinations available.


Adding A new Custom Layout Combo

For the pupose of this document, we'll assume that you have a specific need for a new layout combination that is not provided in these variables, and therefore not available to you in the template settings. Let's say for some reason you want a really large body on the right, and a very skinny sidebar-a on the left. That would translate into a sidebar-a of 2 columns, and the mainbody with 10 columns of space.

Rather than adding these values directly into the Gantry framework core files, we can override these variables as you can with most things in Gantry.

To do this, simply open up your gantry.config.php file in your Gantry-powered template. In the case of the Gantry core template, this would be located at wp-content/themes/[YOUR_TEMPLATE]/gantry.config.php. Then, copy the Gantry-core $gantry_default_pushpullschemas and $gantry_default_mainbodyschemacombos variables into the template's gantry.config.php file at the bottom.

Next, we'll need to edit the two variables in order to add the appropriate layout:

  1. $gantry_default_pushpullschemas = array(
  2. ....snip....
  3. 'sa6-mb6' => array ('rt-push-6','rt-pull-6'),
  4. 'sa5-mb7' => array ('rt-push-5','rt-pull-7'),
  5. 'sa4-mb8' => array ('rt-push-4','rt-pull-8'),
  6. 'sa3-mb9' => array ('rt-push-3','rt-pull-9'),
  7. 'sa2-mb10' => array ('rt-push-2','rt-pull-10'),
  8. ....snip....


  1. $gantry_default_mainbodyschemascombos = array(
  2. ....snip....
  3. 12 => array(
  4. 1 => array(
  5. array('mb'=>12)
  6. ),
  7. 2 => array(
  8. ....snip....
  9. array('sa'=>6, 'mb'=>6),
  10. array('sa'=>5, 'mb'=>7),
  11. array('sa'=>4, 'mb'=>8),
  12. array('sa'=>3, 'mb'=>9),
  13. array('sa'=>2, 'mb'=>10)
  14. ),
  15. .....snip....

Save the file and you're done! Now, when you visit the template settings, you will have a new option in your mainbody layout slider.


Adding a Custom Stylesheet

This tutorial will take you through the steps needed to add a custom stylesheet to your Gantry template without worrying about lost changes when either the template or Gantry framework is updated. You won't need to change any of the template files, so your custom stylesheet will not be overridden by updates.


Custom Stylesheet with CSS

The Gantry template comes complete with structured CSS rules and properties which are compiled from LESS files. There are, however, some cases where we need to style the template without using LESS. One of the ways to do this involves using the custom CSS file with custom rules and properties to override a particular style in the template.


Step 1: Adding Your Custom CSS File

To create a custom CSS file, you'll need to create a new CSS file at /wp-content/themes/[TEMPLATE]/css/, and name it [TEMPLATE]-custom.css. The new custom CSS file will automatically be loaded by Gantry Framework.


Step 2: Adding Your Custom Rules and Properties

You should be able to add the custom rules and properties inside the [TEMPLATE]-custom.css file in order to customize your Gantry template. If you want to override any existing rules from the template, you can do so using CSS Specificity.

We'll go into more detail about this process below.


Example 1: Override Existing Rules

In this example, we'll explain how to reduce the bottom padding and margin in the showcase position of the default gantry template, which inherits rules from the rt-block element inside rt-showcase.

With Chrome Developer Tools, we can see that the default margin and padding are:

  1. .rt-block {padding: 15px; margin: 10px; position: relative;}

If we want to override the bottom padding and margin, we can not just put the same rule and change the padding or bottom value. Here's an example:

  1. .rt-block {padding: 15px 15px 0; margin: 10px 10px 0;}

There are many elements in the template that utilize rt-block, and these custom rules will affect them. It's also possible that the custom rule will not work at all if your custom CSS file is loaded before the template CSS file, which contains the existing rule.

Hence, we need to put the rule with more specific selectors. We need to create a blank file css/rt_gantry_wp-custom.css. Since rt-block is wrapped inside rt-showcase, we can put the following rule inside css/rt_gantry_wp-custom.css.

  1. #rt-showcase .rt-block {padding: 15px 15px 0; margin: 10px 10px 0;}

Now, we can check the result with the Developer Tools again to confirm that our custom rule overrides the existing one.


Example 2: Per-Browser Specific Custom Stylesheet

Gantry Framework has the ability to load specific CSS file based on which browser and operating system is viewing the template. This ability can be also applied to our custom CSS file. You just need to create a new CSS file at /wp-content/themes/[TEMPLATE]/css/ and name it [TEMPLATE]-custom-[BROWSER].css. Please check the Per-Browser Specific Control page for possible name combinations.

In this example, we will explain how to hide a specific widget viewed with Firefox, while keeping it visible on other browsers. In the case of the gantry default template, we need to create /wp-content/themes/[TEMPLATE]/css/rt_gantry_wp-custom-firefox.css.

Next, we need to put the custom rule inside /wp-content/themes/[TEMPLATE]/css/rt_gantry_wp-custom-firefox.css.

Here's an example:

  1. .rt-hidden-firefox {display: none;}

Now, we can put rt-hidden-firefox in the Custom Variations of the widget we want to hide on Firefox.

Click the Save button before confirming the result in Firefox, as well as other browsers. The widget should be successfully hidden on Firefox, and remain visible on other browsers.

Per-Browser Specific Custom Stylesheet is not just limited to showing or hiding a specific widget. We can also use this ability, for example, to create a new rule or override existing rules just for specific browser, such as Internet Explorer. Any in CSS can be overridden on a per-browser basis using this method.


Custom Stylesheet with LESS

Another way to add the custom style to the Gantry template is to create a custom LESS file inside /wp-content/themes/[TEMPLATE]/less. The custom LESS file name should be formatted as [LESS_FILE_NAME]-custom.less. This file will be compiled in the main CSS file.

For example, in the default Gantry template, there is a file called less/template.less. We can add a custom LESS file named less/template-custom.less and add our custom LESS elements. Gantry will pick up the elements and compile it. You may also use other file names such as less/style-custom.less, less/typography-custom.less, and so on.

The only limitation with Custom LESS file is that we can not use Per-Browser Specific Custom Stylesheet. Such is the case with less/template-custom-firefox.less. If you need to control some elements on specific browsers, we need to use the Custom CSS file as described previously.


Adding a Custom Font

This tutorial will take you through the steps needed to add a custom font to your Gantry template and make it available on the Font Settings dropdown within template settings.

In this example, we will explain how you can add the custom free font Bloody to your Gantry template.


Step 1: Adding Your Custom Font Files

Bloody is a free font that you can download at FontSquirrel. Make sure you've downloaded the @font-face Kit.

Unzip the package, and move the following files to /wp-content/themes/[TEMPLATE]/fonts/:


Step 2: Adding the Necessary CSS

Create your custom stylesheet file, rt_gantry_wp-custom.css, and add it to /wp-content/themes/[TEMPLATE]/css/.

Add the following to the custom CSS file:

  1. /* Adding Font BLOODY */
  3. @font-face {
  4. font-family: 'BloodyNormal';
  5. src: url('../fonts/BLOODY-webfont.eot');
  6. src: url('../fonts/BLOODY-webfont.eot?#iefix') format('embedded-opentype'),
  7. url('../fonts/BLOODY-webfont.woff') format('woff'),
  8. url('../fonts/BLOODY-webfont.ttf') format('truetype'),
  9. url('../fonts/BLOODY-webfont.svg#BloodyNormal') format('svg');
  10. }
  12. .font-family-bloody {
  13. font-family: 'BloodyNormal',Helvetica,Arial,sans-serif;
  14. font-weight: normal;
  15. font-style: normal;
  16. }


Step 3: Adding the Info to the Font Settings Dropdown

With your text/code editor, open /wp-content/themes/[TEMPLATE]/templateDetails.xml, and add the custom font option (line 9 in the below example):

  1. <field name="family" type="fonts" default="s:helvetica" primary="helvetica" label="FONT_FAMILY" isbodyclass="true" setbyurl="true" setinsession="true" setbysession="true" setincookie="true" setbycookie="true">
  2. <option value="geneva">Geneva</option>
  3. <option value="georgia">Georgia</option>
  4. <option value="helvetica">Helvetica</option>
  5. <option value="lucida">Lucida</option>
  6. <option value="optima">Optima</option>
  7. <option value="palatino">Palatino</option>
  8. <option value="trebuchet">Trebuchet</option>
  9. <option value="bloody">Bloody</option>
  10. </field>

Now, go to your template settings, and confirm that the new font option is available.

The Gantry template default font is Helvetica. The frontend will look like the following:

Now, set the default font to Bloody in the Font Settings parameter. Reload the frontend to check the result.

You can add as many custom fonts as you wish, and set the multiple option for the font settings.


Font Usage on Specific Elements

In addition to adding the Bloody font, as outlined above, you can also add it to specific elements such as the content and widget titles. In this example, we'll add the following to the custom CSS file mentioned above:

  1. /* Adding Font BLOODY */
  3. @font-face {
  4. font-family: 'BloodyNormal';
  5. src: url('../fonts/BLOODY-webfont.eot');
  6. src: url('../fonts/BLOODY-webfont.eot?#iefix') format('embedded-opentype'),
  7. url('../fonts/BLOODY-webfont.woff') format('woff'),
  8. url('../fonts/BLOODY-webfont.ttf') format('truetype'),
  9. url('../fonts/BLOODY-webfont.svg#BloodyNormal') format('svg');
  10. }
  12. .font-family-bloody .title, .font-family-bloody .component-content h2{
  13. font-family: 'BloodyNormal',Helvetica,Arial,sans-serif;
  14. font-weight: normal;
  15. font-style: normal;
  16. }

Reload the front end and check the result. Only the component title and module title will use the Bloody font. The rest of the content will use the default font Helvetica.


Creating a New Layout

Layouts are blocks of code that control the HTML structure of a particular section of the template rendering. By default, Gantry comes with several built-in layout files located in the wp-content/plugins/gantry/html/layouts/ folder:

Layouts Description
~~body_iphonemainbody.php~~ Deprecated - Used for iPhone mainbody layout configurations
body_mainbody.php the default mainbody layout. This is the layout that controls the mainbody in relation to the sidebars
doc_body.php a layout to render the body tag, used in displayBodyTag()
doc_tag.php a layout used in the generic rendering of a tag output by the displayClassesByTag() method
widget_basic.php a basic layout for modules
widget_sidebar.php the layout for the sidebars
widget_standard.php the standard layout for modules
orderedbody_mainbody.php renders mainbody and sidebars in order for use with CSS tables


Step 1: Purpose

The default layout that ships with Gantry Framework is designed to be flexible enough to handle the needs of 99% of the possible implementations. However, there are occasions when the default HTML structure does not contain all the blocks elements or class names required to realize a particular design.

In these rare cases, you can utilize the power of the Gantry framework to override the default layout with your own, template-provided one. Certain instances, such as widget layouts, are flexible enough to support your own custom layouts. You can even call them in the same way the default layouts are called.


Step 2: Create/Copy New Layout Files

The simplest way to do this is to copy an existing layout. In this example, we'll copy the body_mainbody.php layout and modify it after. The files are located under:


However, you do not want to modify the core Gantry files. Instead, copy the new layout file to:


You may have to create a layouts/ folder if one does not already exist.

In this case, copy body_mainbody.php from the core layouts location into the template layouts location.


Step 3: File Structure

After you have copied the body_mainbody.php file, you can open it up and edit it to fit your needs. By default, it looks like this:

  1. <?php
  2. /**
  3. * @version $Id: body_mainbody.php 59361 2013-03-13 23:10:27Z btowles $
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. *
  8. */
  9. defined('GANTRY_VERSION') or die();
  11. gantry_import('core.gantrybodylayout');
  13. /**
  14. *
  15. * @package gantry
  16. * @subpackage html.layouts
  17. */
  18. class GantryLayoutBody_MainBody extends GantryBodyLayout
  19. {
  20. var $render_params = array(
  21. 'schema' => null,
  22. 'pushPull' => null,
  23. 'classKey' => null,
  24. 'sidebars' => '',
  25. 'contentTop' => null,
  26. 'contentBottom' => null,
  27. 'component_content' => ''
  28. );
  30. function render($params = array())
  31. {
  32. /** @global $gantry Gantry */
  33. global $gantry;
  35. $fparams = $this->_getParams($params);
  37. // logic to determine if the component should be displayed
  38. $display_mainbody = !($gantry->get("mainbody-enabled", true) == false);
  39. $display_component = !($gantry->get("component-enabled", true) == false);
  40. ob_start();
  42. ?>
  43. <?php if ($display_mainbody) : ?>
  44. <div id="rt-main" class="<?php echo $fparams->classKey; ?>">
  45. <div class="rt-container">
  46. <div class="rt-grid-<?php echo $fparams->schema['mb']; ?> <?php echo $fparams->pushPull[0]; ?>">
  48. <?php if (isset($fparams->contentTop)) : ?>
  49. <div id="rt-content-top">
  50. <?php echo $fparams->contentTop; ?>
  51. </div>
  52. <?php endif; ?>
  54. <?php if ($display_component) : ?>
  55. <div class="rt-block">
  56. <div id="rt-mainbody">
  57. <div class="component-content">
  58. <?php
  59. if ('' == $fparams->component_content) {
  60. $this->include_type();
  61. } else {
  62. echo $fparams->component_content;
  63. }
  64. ?>
  65. </div>
  66. </div>
  67. </div>
  68. <?php endif; ?>
  70. <?php if (isset($fparams->contentBottom)) : ?>
  71. <div id="rt-content-bottom">
  72. <?php echo $fparams->contentBottom; ?>
  73. </div>
  74. <?php endif; ?>
  76. </div>
  77. <?php echo $fparams->sidebars; ?>
  78. <div class="clear"></div>
  79. </div>
  80. </div>
  81. <?php endif; ?>
  82. <?php
  83. return ob_get_clean();
  84. }
  85. }

Feel free to edit this file as needed.


Creating a New Gizmo

In the Gantry framework, we use the term Gizmo to refer to a specific type of functionality. Gizmos are flexible enough that they can be used to perform almost any kind of logic you would need. The base GantryGizmo class contains methods that can be implemented to control how your gizmo functions. Those methods are:

By default, this gets its state from the enabled toggle in the admin. You can override this to force the enabling of a gizmo without any UI interaction.
Returns boolean [true | false]
setPrefix(string $prefix)
This sets a prefix for handling prefixed parameters such as chained elements.
Argument string [prefix name - usually the name of the main chain param]
get($param [, $prefixed = true])
This method gets a param from the gizmo's configuration. Can also take a prefix for more specificity.
Argument string [field name]
Argument [optional] boolean [true | false]
Returns mixed [the current value of the field]
Empty, by default. It's the first method called on initialization of a gizmo. It's used for setup or initialization.
Empty, by default. This method initializes the gizmos after a query gets parsed.
Empty, by default. It's used to initialize a gizmo when the admin dashboard gets initialized.
Empty, by default. This is called at the end of the gizmo.

All core gizmos, and any custom gizmo you create, should extend this GantryGizmo class. To create a new gizmo of your own, you would just have to create a new file in your gizmos/ folder that extended the GantryGizmo class. It will automatically be picked up by the Gantry framework and processed. The best way to see what one can do for you is to examine a few of the core gizmos.


Google Analytics Gizmo

First, let's look at one of the core gizmos called analytics.php. As you can imagine, the analytics gizmo is intended to add the Google Analytics tracking code to your site. The most important part of a gizmo is the actual gizmo PHP file. The core gizmos are located in the YOUR_SITE/wp-content/plugins/gantry/gizmos/ folder. These should never be touched or changed.

If you want to override the behavior of a core gizmo, simply copy the core gizmo to your YOUR_SITE/wp-content/themes/YOUR_TEMPLATE/gizmos folder. Gantry will automatically pick up your version of the file and use it rather than the default version if you have created one with the same name. The other part of a gizmo, and one that is totally optional, is the configuration section. As with other parts of Gantry, the configuration is handled in the templateDetails.xml.

For the Google Analytics gizmo, the section in templateDetails.xml looks like:

  1. <fields name="analytics" type="chain" label="Analytics">
  2. <field name="enabled" type="toggle" default="0" label="Enable" />
  3. <field name="code" type="text" default="" label="Code" class="text-long" />
  4. <field name="priority" type="hidden" default="3"/>
  5. </fields>

What this means is that in the administrator interface, there are going to be two parameters rendered. One is a toggle element that will control the 'enabled' state. The second is a text input for your unique Analytics key that will be added to the JS script. By exposing these elements in the XML, we allow interaction with the user. If you wanted to add new elements in this XML section, you could. They would be available for you to use in your gizmos PHP definition.

Next, let's look at the PHP for this feature:

  1. <?php
  2. /**
  3. * @version $Id: analytics.php 59361 2013-03-13 23:10:27Z btowles $
  4. * @author RocketTheme
  5. * @copyright Copyright (C) 2007 - ${copyright_year} RocketTheme, LLC
  6. * @license GNU/GPLv2 only
  7. */
  9. defined('GANTRY_VERSION') or die();
  11. gantry_import('core.gantrygizmo');
  13. /**
  14. * @package gantry
  15. * @subpackage features
  16. */
  17. class GantryGizmoAnalytics extends GantryGizmo
  18. {
  20. var $_name = 'analytics';
  22. function init()
  23. {
  24. /** @global $gantry Gantry */
  25. global $gantry;
  27. ob_start();
  28. // start of Google Analytics javascript
  29. ?>
  30. var _gaq = _gaq || [];
  31. _gaq.push(['_setAccount', '<?php echo $this->get('code'); ?>']);
  32. _gaq.push(['_trackPageview']);
  34. (function() {
  35. var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  36. ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '';
  37. var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  38. })();
  39. <?php
  40. // end of Google Analytics javascript
  41. $gantry->addInlineScript(ob_get_clean());
  43. }
  44. }

As you can see, the only method that is used is the init() method. Other methods from the base GantryGizmo class are not overridden. That means that the standard methods (to get the enabled state, etc.) are being used, and are pulling that data from the XML, in addition to the admin settings. You can see how custom XML parameters like code are easily available, and are automatically prefixed by the gizmo name. This allows you to just use get->("code") to retrieve the value of of a chained field.

Have a look through all the Default Gizmoz that come with Gantry to see how you can achieve a wide variety of functionality with these incredible tools.



LESS is a dynamic stylesheet language that extends CSS with dynamic behaviours such as variables, mixins, operations and functions. LESS allows your code to be cleaner and optimized, while also reducing the overall time to create and maintain your code base.

Gantry supports LESS, rooting the compiler and core processes into the Framework itself. Furthermore, the administrator and frontend template are constructed with LESS files that are then outputted as CSS files to the browser. Gantry handles all the complex processing, so you can concentrate purely on the styling.

Note, when making modifications, remember to:

  1. Always edit the .less and not the compiled .css files that are output to /css-compiled/ folder
  2. Ensure the /less/, /css/, and /css-compiled/ directories for the template are writeable
  3. Clear the WordPress, Less, Gantry, and browser caches


LESS: the Basics

LESS is designed to extend CSS so you start with the basic principles and attributes that are associated with CSS, IDs, classes and others. Therefore, the format will look familiar. In terms of examples, the /LESS files will be shown first, followed by the Compiled CSS files, which are the outputted files that appear in the /css-compiled/ directory.



These are standard values that can be repeated throughout your stylesheets. As a result, one line change will generate a global change rather than having to change each instant manually. An example from the Gantry template is below:

  1. //LESS
  2. @bodytitle: #303030;
  3. ...
  4. a:hover {
  5. color: @bodytitle;
  6. }
  7. h1, h2, h3, h4, h5, h6 {
  8. color: @bodytitle;
  9. }

  1. /* Compiled CSS */
  2. a:hover {
  3. color: #303030;
  4. }
  5. h1, h2, h3, h4, h5, h6 {
  6. color: #303030;
  7. }

As you can see in the above example, anywhere @bodytitle is used in the LESS files, the value is changed to #303030 in the compiler.



Mixins combine Variables with Functions by allowing you to include all the properties associated with a class into another class. These class injections can include functions, as shown in the example extracted from below:

  1. //LESS
  2. .rounded.corners (@radius: 5px) {
  3. border-radius: @radius;
  4. -webkit-border-radius: @radius;
  5. -moz-border-radius: @radius;
  6. }
  8. #header {
  9. .rounded.corners;
  10. }
  11. #footer {
  12. .rounded.corners(10px);
  13. }

  1. /* Compiled CSS */
  2. #header {
  3. border-radius: 5px;
  4. -webkit-border-radius: 5px;
  5. -moz-border-radius: 5px;
  6. }
  8. #footer {
  9. border-radius: 10px;
  10. -webkit-border-radius: 10px;
  11. -moz-border-radius: 10px;
  12. }


Nested Rules

Nested Rules are for inheritance. These allow your style sheets to be cleaner and shorter by placing selector groups within one another, rather than specifying each instant each time. See a Gantry Template example below:

  1. //LESS
  2. {
  3. list-style: none;
  4. margin: 0;
  5. padding: 0;
  6. ul {
  7. list-style: none;
  8. }
  9. li {
  10. margin-bottom: 8px;
  11. a, .item, .separator {
  12. display: block;
  13. font-size: 1.1em;
  14. font-weight: bold;
  15. }
  16. }
  17. }

  1. /* Compiled CSS */
  2. {
  3. list-style: none;
  4. margin: 0;
  5. padding: 0;
  6. }
  7. ul {
  8. list-style: none;
  9. }
  10. li {
  11. margin-bottom: 8px;
  12. }
  13. li a, li .item, li .separator {
  14. display: block;
  15. font-size: 1.1em;
  16. font-weight: bold;
  17. }


Functions and Operations

Functions & Operations allow you to perform mathematical operations to CSS values as well as manipulate values through functions, as is available with JavaScript. See the example below, extracted from

  1. //LESS
  2. @the-border: 1px;
  3. @base-color: #111;
  4. @red: #842210;
  6. #header {
  7. color: @base-color * 3;
  8. border-left: @the-border;
  9. border-right: @the-border * 2;
  10. }
  11. #footer {
  12. color: @base-color + #003300;
  13. border-color: desaturate(@red, 10%);
  14. }

  1. /* Compiled CSS */
  2. #header {
  3. color: #333;
  4. border-left: 1px;
  5. border-right: 2px;
  6. }
  7. #footer {
  8. color: #114411;
  9. border-color: #7d2717;
  10. }

The above outline introduces you to the basics of how LESS works. For a more detailed overview of how variables, mixins, functions, and operations, please visit:


LESS in the Gantry Template

All LESS files associated with the template are located in the /wp-content/themes/[TEMPLATE]/less/ directory. Gantry 4 utilizes a powerful PHP-based LESS compiler powered by lessphp. Gantry 4 outputs the processed LESS files into the /wp-content/themes/[TEMPLATE]/css-compiled/ directory.

Not all CSS files are compiled into a single file. Any CSS file that requires to be standalone, for purposes of template parameters, such as loading Fusion Menu instead of SplitMenu, will be independent of the main /wp-content/themes/[TEMPLATE]/css-compiled/[OUTPUT_CSSFILE] file.


How are LESS Files Compiled?

When a change is detected, Gantry automagically recompiles your LESS files into CSS files. To add a LESS file, you have two options. You can insert the following function into your PHP code:

  1. $gantry->addLess('NAME.less');

Where NAME.less is the name of your less file in your /wp-content/themes/[TEMPLATE]/less/ directory. The addLess() method takes several optional parameters:


Here's an example as used in the default gantry template:

  1. $gantry->addLess('global.less', $gantry->templateName . '-compiled.css', 8, array('headerstyle'=>'"header-'.$gantry->get('headerstyle','dark').'.less"'));

You can see from this example that global.less is the source LESS file, and the output is going to be gantry-compiled.css. Priority has been harcoded as 8, and the last parameter is an array of a single item headerstyle passed to the LESS compilation. The ability to pass variables makes LESS compilation both powerful and flexible.

When you pass variables to less compilation, your output will take the format of [TEMPLATE]-compiled-[MD5_VARIALBLE_NAME_VALUES]. For example: gantry-compiled-845729384248h3hf4haeioh.css.

An alternative way to add LESS files is to simply create the file and add a reference in the /less/global.less master LESS file. The global.less file imports the other LESS files via the @import function. See the example below:

  1. // Core variables and mixins
  2. @import "variables.less";
  3. @import "mixins/index.less";
  5. // Core and Grid
  6. @import "gantry-core.less";
  7. @import "wordpress-core.less";
  9. // Template core styling and layout
  10. @import "template.less";
  11. @import "style.less";
  12. @import @headerstyle;
  13. @import "prettify.less";

Furthermore, for features that require a separate LESS file, you can use a variety of different techniques. The simplest is to insert the add the addLess function into /gizmos/styledeclaration.php, as noted in the example from the Gantry Template:

  1. if ($gantry->get('typography-enabled')) $gantry->addLess('typography.less');

This adds a conditional, where the parameter typography-enabled is active, the /less/typography.less file will be compiled.


LESS Template Options

You can control CSS compression, compile wait time and debug header, as well as manually clear the cache with the Clear Cache button at Admin Dashboard ? Gantry Theme ? Advanced ? Less Compiler.

Additionally, CSS compression increases site performance and optimization by consolidating all the CSS into a single file, with none or negligible whitespace. This reduces the file size of the CSS file and reduces browser load time.


Custom LESS files

Often, you will have a need to add some custom CSS to override a particular style in the template. You may not want to edit the provided LESS or CSS files. This could potentially cause problems with updates of the template. With Gantry 4, you can create custom LESS files of the format: /less/[LESS_FILE_NAME]-custom.less. These will get picked up and compiled into the main compiled CSS file.

For example, within the default Gantry template, there is a file less/template.less. If you were to create a new file called less/template-custom.less, you could add your own custom LESS elements in it. They would automatically be pulled in to your compiled CSS file.

For Support mail us

Thanks for choosing ThemeRox.