Create a new module position

Adding a new position for modules or widgets to your theme is straight forward. We will call the position "top-c" below the already existing "top-a" and "top-b" positions. The following files inside your theme's folder need to be edited:

  • templateDetails.xml (Joomla)
  • template.xml (WordPress)
  • config.xml
  • /layouts/template.php
  • /layouts/module.php
  • /js/template.js

Add a new position to the theme XML file

Open the templateDetails.xml file for Joomla or the template.xml for WordPress. Here you need to add your new position (top-c) to make your CMS know it exists. Simply copy an entry of an existing position and rename it, like in the following example:

<positions>
	...
	<position>top-a</position>
	<position>top-b</position>
	<position>top-c</position>
	<position>bottom-a</position>
	...
</positions>

Define module layout options for the new position

Open config.xml and look for an entry of an already existing positon. Copy the code from "top-b" for example, paste it below it and rename it:

<field name="top-c" type="layout" default="equal" label="Top C Layout" description="Select a grid layout for this module position." />

This allows you to define a layout for your new position in the theme options of your administration.

Add the new position to the main template file

Open layouts/template.php and you see the basic markup of the theme. This is the file to define where modules, published on your new position should be rendered. As before, you should copy the code from an existing position and place it where you need it and rename it. In my example I took the "top-b" code, pasted it below and customized it:

<?php if ($this['modules']->count('top-c')) : ?>
	<section id="top-c">
		<div class="grid-block">
			<?php echo $this['modules']->render('top-c', array('layout'=>$this['config']->get('top-c'))); ?>
		</div>
	</section>
<?php endif; ?>

Note: You can override the template.php in your own style. Just copy /layouts/template.php to /styles/YOUR_STYLE/layouts/template.php.

Define a default module style for the new position

Open layouts/module.php and set a default module style here, add the code for your new position. In my example I want to make the style "line" the default style for top-c:

// set default module types
if ($style == '') {
	if ($module->position == 'top-a') $style = 'line';
	if ($module->position == 'top-b') $style = 'line';
	if ($module->position == 'top-c') $style = 'line';
	...
}

Note: If you create a theme style and want to add some new module styles you can override the default module.php file. Just copy /layouts/module.php to /styles/YOUR_STYLE/layouts/module.php.

Match module heights

To match the height of modules in the same row, open js/template.js. Look for an already existing entry in the matchHeight() function. In my example I copied the entry for #top-b and renamed it to #top-c.

$('#top-c .grid-h').matchHeight('.deepest');

Update your CSS

If you want to style your newly added module position or modules published on that position you need to update the /css/layouts.css file. In our example it would make sense to add all CSS that is applied to top-a and bottom-a also to our new position.

Update your style (Joomla)

In order to make your new module position work with your seleced style, you have to click "save" in the Template Manager of your theme. This will generate a new "config" file out of your "config.xml".

Documentation on Github

Help us out! If you are feeling that our documentation has errors or can be improved, fork it at Github and send us a pull request. Any contribution is much appreciated. Thank you!