Develop your own module

Module System

This tutorial explains how you can develop your own module template and module style. After finishing this tutorial you will be able to access your module style by setting "style-mymodule" as the Module Class Suffix in your Joomla backend.

Params and module loader

You can find existing module template files in the folder templates/your_template/lib/modules/. To develop a new module template we recommend that you copy one of the existing files and then customize it. To assign your new template to a module we need an identifier to be associated with the Module Class Suffix. The relationship between the identifier and the module type must be taken into account in the modules.php file, which is located at templates/your_template/html/modules.php. Here, we can find a switch statement that maps the identifiers to the module template files:

// set module template using the style
switch ($style) {

	case 'rounded':
		$template  = '3-1-3';
		$style     = 'mod-'.$style;
		$color     = $style.'-'.$color;
		break;

	case 'postit':
		$template  = '0-2-3';
		$style     = 'mod-'.$style;
		break; 
	
	...

Here we can see that e.g. the rounded class suffix is mapped to the 3-1-3.php file. Let's create a new module type named mymodule by adding these lines to the switch-statement:

case 'mymodule':
	$template  = 'my_module_template';
	$style     = 'mod-'.$style;
	break;

The module template

To make this work, we need a module type file. For this, create a PHP file templates/your_template/lib/modules/my_module_template.php. Now, let's insert these lines of PHP code:

<?php
// no direct access
defined('_JEXEC') or die('Restricted access');
?>

<div class="module <?php echo $style; ?> <?php echo $color; ?> <?php echo $yootools; ?>
<?php echo $first; ?> <?php echo $last; ?>">
	<?php echo $badge; ?>
	<div class="box">
		<?php if ($showtitle) : ?>
		<h3 class="header"><?php echo $title; ?></h3>
		<?php endif; ?>
		<?php echo $content; ?>
	</div>
</div>

The outer DIVelement encapsulates our whole module. We'll have to customize the corresponding CSS file, but first let's have a look a the modules structure. We will create a module that is surronded by a simple black box. The echo badge-PHP line will render a badge if the Module Class Suffix is set. The inner DIVelement will render the black box frame by css. Then, the modules title and content will be displayed.

Naming conventions

If you have a look at the module type files, you will notice that they are named like 0-1-0.php or 3-1-3.php. This is due to the number of div elements used on top, middle and bottom position. For example, the rounded module type is mapped to the 3-1-3.php file. That is, because we need three divs on top and bottom position to contain a border-line in the middle and a left and a right rounded corner. Each of these images is assigned to one of the three div elements.

The module style

Now, let's have a look at the CSS code. It is contained in the file templates/your_template/css/modules.css. Now we insert some CSS to style our module:

/*
 * module: mymodule
 */

div.mod-mymodule div.box {
    padding: 15px;
    border: 1px solid #000000;
    background: #ffffff;
    overflow: hidden;
}

div.mod-mymodule h3.header {
    height: 50px;
}

This CSS will create a black border around our module and gibe the header a height of 50 pixels.

In this tutorial we first evaluated the parameters set in the Module Class Suffix, then loaded our new template and set the CSS class to load the specific CSS for our module. All YOOtheme templates are built this way. It is always a good start to take a look into existing modules in YOOtheme templates to see how the module templating is done.