Add custom module proportions before Warp

This tutorial shows you how to add custom module proportions in a YOOtheme template before we implemented the Warp framework in all templates since July 2009.

With the module proportion feature YOOtheme offers a new way to manage your module positions! This approach makes it even easier to create customized module proportions you need for your unique website template. This guide will show you how to create your own module proportions for a module position. In this example you will add a new module proportion called main-top-custom to the top module position. Currently the existing module proportions are main-top-equal and main-top-goldenratio.

First you need to add a new module proportion definition in the template layout setup. To do this you open the template's /lib/php/yoolayout.php file with your favorite text editor. In this file you will find all module proportions defined for the template layout. The following one defines the 'main-top-equal' module position:

// set maintop module variations
$yootools->setModulePosition('main-top-equal', array(
		1 => array('width100'),
		2 => array('width50', 'width50'),
		3 => array('width33', 'width33', 'width33')
	));

As you can see the method setModulePosition(<MODULE_POSITION>, <MODULE_PROPORTION_DEFINITION>) takes two parameters, the first is the name of the module position followed by an array which defines all possible module proportions which depend on how many modules are published inside this module position. So if one module is published inside the 'main-top-equal' position the module will take the complete width of 100%. Further, if you publish 2 modules inside the 'main-top-equal' position, each module takes a width of 50% and so on, since 'main-top-equal' divides the module position space equally for all modules.

Now you create our own custom module proportion definition, which will offer the following proportions:

1 Module = 100%
2 Modules = 80%, 20%
3 Modules = 40%, 40%, 20%

So next you need to add this custom definition to the yoolayout.php file, which will look like this:

// set maintop custom proportion
$yootools->setModulePosition('main-top-custom', array(
		1 => array('width100'),
		2 => array('width80', 'width20'),
		3 => array('width40', 'width40', 'width20')
	));

Since all module widths we defined above, are the CSS styles which will be added to each module html class tag to set the width. We need to make sure all these CSS styles exist in the template /css/layout.css file. To verify this open the layout.css file and scroll to the very bottom where you'll find all CSS styles to control the widths. Now we insert the ones we need for the 'main-top-custom' module proportion:

.width15 { width: 14.999%; }
.width18 { width: 18.333%; }
.width20 { width: 19.999%; }
.width25 { width: 24.999%; }
.width33 { width: 33.333%; }
.width38 { width: 37.999%; }
.width40 { width: 39.999%; } <- add this style
.width45 { width: 44.999%; }
.width50 { width: 49.999%; }
.width62 { width: 61.999%; }
.width75 { width: 74.999%; }
.width80 { width: 79.999%; } <- add this style
.width100 { width: 100%; }

After this little CSS excursion we continue to open the templates index.php to add the new main-top-custom module proportion. First we search for the module position we want to extend which is main-top-equal. Which will look like this:

<?php if ($pos = $yootools->getModulePosition(array('main-top-equal', 'main-top-goldenratio'))) : ?>
 <?php while ($param = $yootools->renderModulePosition($pos)) : ?>
  <div class="maintopbox <?php echo $param['width'].' '.$param['separator']; ?> float-left">
   <jdoc:include type="modules" name="<?php echo $param['name']; ?>" style="yoo" order="<?php echo
   $param['order']; ?>" />
  </div>
 <?php endwhile; ?>
<?php endif; ?>

As you can see the method getModulePosition(<MODULE_POSITION>) takes one parameter which sets the module position names which will be rendered within the template. Currently they are set to main-top-equal' and main-top-goldenratio. This means either the modules published in position main-top-equal or main-top-goldenratio will be rendered to this module position. Since it is not possible to render both at the same time, the method respects module position order. In this example main-top-equal comes first followed by main-top-goldenratio. So if a module is published in ain-top-equal position it will be shown within the template regardless if another module is published in the main-top-goldenratio position.

Next you can add the new main-top-custom module proportion to the getModulePosition() parameter:

<?php if ($pos = $yootools->getModulePosition(array('main-top-equal', 'main-top-goldenratio', 'main-top-
custom'))) : ?>
 <?php while ($param = $yootools->renderModulePosition($pos)) : ?>
  <div class="maintopbox <?php echo $param['width'].' '.$param['separator']; ?> float-left">
   <jdoc:include type="modules" name="<?php echo $param['name']; ?>" style="yoo" order="<?php echo
   $param['order']; ?>" />
  </div>
 <?php endwhile; ?>
<?php endif; ?>

Finally to make the custom module proportion main-top-custom available within the Joomla administration, you have to add the new module position name inside the templateDetails.xml file:

<positions>
...
<position>main-top-equal</position>
<position>main-top-goldenratio</position>
<position>main-top-custom</position>
....
</positions>

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!