Own module styles

Some code fragments in a template often repeat; there is a additional structure between a code creating template’s configuration and a code generated by a module in the form of additional containers. They are used e.g. in title module presentation, in creating rounded edges around a module or containers famous for debugging template mode. Joomla! offers six styles – their detailed descriptions and structures may be found here.

Sometimes some additional elements or different structure than a standard are needed. Of course it is also possible with Joomla!; we can create as many own module styles which fulfill our needs as we want to create.

A little bit of theory

First of all, how style is specified and which one has to be used for module positions given. While creating a new module positions in a template code we use code below:

<jdoc:include type="modules" name="POSITION_NAME" style="STYLE" />

Style attribute, shown above, is responsible for assigning style given to module positions.

Here is an example:

<jdoc:include type="modules" name="topnav" style="xhtml" />

I will assign it to position with modules with topnav title and xhtml style.

We have to remember that our containers will be attached to every module SEPARATELY. In other words, if we have a style which encloses modules with a “module” class container and there are two or more modules on one position, such a code will be generated:

<div class="module">     
    <!-- first module code --> 
</div> 
<div class="module">     
    <!-- second module code --> 
</div>

Instead of:

<div class="module">
     <!-- first module code -->     
     <!-- second module code --> 
</div>

That’s why, module styles cannot be treated as tools to add an extra code for particular layout parts. It can be done when we are sure that there will be published one module on a position given.

Problem stated above does not occur if we embed modules by using:

<jdoc:include type="module" name="MODULE_NAME" style="STYLE" />

The most important thing is to know where to place a code which is responsible for our module styles; in this case it is html/modules.php file in the main catalog of our template (html catalog in templates is responsible for storing different files overwriting extensions installed).

New style definition is made by creating a function of declaration specified:

function modChrome_NAME( $module, &$params, &$attribs )

This function does not return any value; it displays a module code attached by containers immediately.

A module object is the first argument which will be displayed, the second stores the reference to our module configuration (JParameter class object) and the third argument is closely connected with $options variable.

Module object stores few important information from style module point of view out of which, three will be essential for us:

• $module->title which includes module title
• $module->content which includes module content
• $module->showtitle which includes information whether module title will be displayed or not

JParameter class has a get method which returns a value connected with specified key, e.g.

$params->get('test', 0);

Returns us value of “test” parameter or default value if specified parameter doesn’t exist.

When it comes to $attribs table, it appears in the same form as it was shown in this entry or is a table of additional attributes of jdoc:include tag. We have wide range of possibilities because we can create such a tag:

<jdoc:include type="module" name="MODULE_NAME" style="STYLE" textColor="#000" backgroundColor="#fff" />

In this case, $attribs table will be in the form:

Array (      
    [name] => MODULE_NAME      
    [style] => STYLE      
    [textColor] => #000     
    [backgroundColor] => #fff  
)

As you can see, it is possible to create module styles fully configured, thanks to which there is no need to create few variations of the same style – it is enough to give appropriate parameters.

Create own module style

We are going to create a simple module style which will have such features:

• a module header will have an additional element allowing to get rounded edges of a header
• our style will allow to suffix option for a module shared by majority of Joomla! modules
• thanks to additional attributes, it will be possible to specify id for main module container

We will call our style “simple”.

There is a full code of our style with description below:

function modChrome_simple($module, &$params, &$attribs) {         
    // id attribute is defined ?         
    $id = (isset($attribs['id'])) ? ' id="'.$attribs['id'].'"' : '';                  
    // value of module suffix         
    $suffix = $params->get('moduleclass_sfx');                  
    // main container - start         
    echo '<div class="module'.$suffix.'"'.$id.'>';                   
    // showing title is enabled ?        
    if ($module->showtitle != 0)         {                
        // showing title                 
        echo '<h3><span>'.$module->title.'</span></h3>';          
    }          
    // module content with outer container         
    echo '<div class="module_content">';         
    echo $module->content;         
    echo '</div>';          
    // main container - end         
    echo '</div>'; 
}

In order to load configurative option value which specifies module suffix, it is enough to write a code:

$params->get('moduleclass_sfx')

Suffixes are very useful because its are based on one configuration/module styles, we can specify as many styles as you like, e.g. for classes:

• module_menu
• module_text
• module_small

etc.

Checking whether a title is displayed it is obligatory option for every module style using a module title display.

Content is attached by another “module content” container to make separation from module title easier.

Code:

<jdoc:include type="modules" name="header" style="simple" id="test" />

It will cause wrapping modules from “header” position with a container “test” id (and of course with rest of our code of our style).

Other possibilities

It is worth remembering that code presented in this entry is just a peak of our iceberg of possibilities which overwriting of module styles offer us – thanks to overwriting we can gain a lot of various effects, e.g. rolled up module blocks, advanced styling of module headers or filtrating module content included in $module->content.

For more sophisticated needs, it’s worth considering using an additional class and templates in order to make a code more clear. We add this class to modules.php file.

It is very useful to see different templates’ codes in order to see how their authors used the possibility of own module styles definition; it can be source of some interesting solutions which not only can widen template’s possibilities but also make its creation easier.