Actions

Difference between revisions of "Customising the way modules are displayed"

From Joomla! Documentation

m (advanced category)
(Remove rounded corners page)
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{version|2.5,3.x}}
 
This document explains different ways of customising your template to change the way modules are displayed.
 
This document explains different ways of customising your template to change the way modules are displayed.
  
Line 7: Line 8:
  
 
{{:Collapsing columns|Collapsing columns}}
 
{{:Collapsing columns|Collapsing columns}}
 
{{:Creating rounded corners|Creating rounded corners}}
 
  
 
{{:What is module chrome?|What is module chrome?}}
 
{{:What is module chrome?|What is module chrome?}}
  
 
{{:Applying custom module chrome|Applying custom module chrome}}
 
{{:Applying custom module chrome|Applying custom module chrome}}
 
{{:Cascading module chrome styles|Cascading module chrome styles}}
 
  
 
<noinclude>[[Category:Modules]][[Category:Templates]][[Category:Tutorials]][[Category:Advanced]]</noinclude>
 
<noinclude>[[Category:Modules]][[Category:Templates]][[Category:Tutorials]][[Category:Advanced]]</noinclude>

Revision as of 18:28, 30 September 2013

This document explains different ways of customising your template to change the way modules are displayed.

Contents

Counting modules in a given module position

The countModules method can be used within a template to determine the number of modules enabled in a given module position. This is commonly used to include HTML around modules in a certain position only if at least one module is enabled for that position. This prevents empty regions from being defined in the template output and is a technique sometimes referred to as “collapsing columns”.

For example, the following code includes modules in the 'user1' position only if at least one module is enabled for that position.

<?php if ($this->countModules( 'user1' )) : ?>
  <div class="user1">
    <jdoc:include type="modules" name="user1" style="rounded" />
  </div>
<?php endif; ?>

The countModules method can be used to determine the number of Modules in more than one Module position. More advanced calculations can also be performed.

The argument to the countModules function is normally just the name of a single Module position. The function will return the number of Modules currently enabled for that Module position. But you can also do simple logical and arithmetic operations on two or more Module positions.

For example, to determine the total number of Modules enabled in the 'user1' and 'user2' positions together, you can use the function call:

$this->countModules( 'user1 + user2' );

Although the usual arithmetic operators, +. -. *, / will work as expected, these are not as useful as the logical operators 'and' and 'or'.

For example, to determine if the 'user1' position and the 'user2' position both have at least one Module enabled, you can use the function call:

$this->countModules( 'user1 and user2' );

Careful: A common mistake is to try something like this:

$this->countModules( 'user1' and 'user2' );

This is pretty much guaranteed to always return false regardless of the number of Modules enabled in either position, so check what you are passing to countModules carefully.

You must have exactly one space character separating each item in the string. For example, 'user1+user2' will not produce the desired result as there must be a space character either side of the '+' sign. Also, 'user1 + user2' will produce a PHP error message as there is more than one space separating each element.

Example: The user1 and user2 Module positions are to be displayed in the region, but you want the region to not appear at all if no Modules are enabled in either position.

<?php if ($this->countModules( 'user1 or user2' )) : ?>
        <div class="rightcolumn">
                <jdoc:include type="modules" name="user1" style="xhtml" />
                <jdoc:include type="modules" name="user2" style="xhtml" />
        </div>
<?php endif; ?>

Example: The user1 and user2 Module positions are to be displayed side-by-side with a separator between them. However, if only one of the Module positions has any Modules enabled then the separator is not needed. Furthermore, if neither user1 or user2 has any Modules enabled then nothing is output.

<?php if ($this->countModules( 'user1 or user2' )) : ?>
        <div class="user1user2">
 
                <?php if ($this->countModules( 'user1' )) : ?>
                        <jdoc:include type="modules" name="user1" style="xhtml" />
                <?php endif; ?>
 
                <?php if ($this->countModules( 'user1 and user2' )) : ?>
                        <div class="greyline"></div>
                <?php endif; ?>
 
                <?php if ($this->countModules( 'user2' )) : ?>
                        <jdoc:include type="modules" name="user2" style="xhtml" />
                <?php endif; ?>
 
        </div>
<?php endif; ?>

Notice how the first countModules call determines if there any Modules to display at all. The second determines if there are any in the 'user1' position and if there are it displays them. The third call determines if both user1 and user2 positions have any Modules enabled and if they do then if provides a separator between them. Finally, the fourth call determines if there are any enabled Modules in the 'user2' position and displays them if there are any.

Collapsing columns

A common requirement when designing web pages in Joomla! is for a Module position to be removed when no Modules are enabled in that position so that the space is available for other page elements. The region removed is referred to as a "collapsed column". This can be achieved using the countModules function.

For example, if you want to include a "user1" module position only if there are modules enabled in that position, then you could use this code:

<?php if ($this->countModules( 'user1' )) : ?>
  <div class="user1">
    <jdoc:include type="modules" name="user1" style="xhtml" />
  </div>
<?php endif; ?>

Notice that the <jdoc:include /> tag and its surrounding <div> are only included if the countModules call returns a non-zero value (the PHP if statement treats zero as being false and any non-zero value as being true.

Sometimes you may want a pair of module positions to collapse either singly or together.

<?php if ($this->countModules( 'user1 or user2' )) : ?>
  <div class="user1user2">
    <?php if ($this->countModules( 'user1' )) : ?>
      <jdoc:include type="modules" name="user1" style="xhtml" />
    <?php endif; ?>
 
    <?php if ($this->countModules( 'user2' )) : ?>
      <jdoc:include type="modules" name="user2" style="xhtml" />
    <?php endif; ?>
  </div>
<?php endif; ?>

Notice how the region (which is styled by the CSS class "user1user2") is only output if either 'user1' or 'user2', or both, have at least one Module enabled.

If you want a divider to separate the two Module positions then you must be careful to only output the divider if both Module positions have Modules enabled in them. For example,

<?php if ($this->countModules( 'user1 or user2' )) : ?>
  <div class="user1user2">
    <?php if ($this->countModules( 'user1' )) : ?>
      <jdoc:include type="modules" name="user1" style="xhtml" />
    <?php endif; ?>
 
    <?php if ($this->countModules( 'user1 and user2' )) : ?>
      <div class="divider"></div>
    <?php endif; ?>
 
    <?php if ($this->countModules( 'user2' )) : ?>
      <jdoc:include type="modules" name="user2" style="xhtml" />
    <?php endif; ?>
  </div>
<?php endif; ?>

See also


<translate> Module chrome allows template designers to have a certain amount of control over the way the output from a Module is displayed in their template. Essentially, it consists of a small amount of predefined HTML which is inserted before, after, or around the output from each module, and which can then be styled using CSS. Module chrome is commonly used to provide borders around modules, especially with rounded corners, but it can be used for much more than that.

Module chrome is determined by using the 'style' attribute in the statement calling the module. For example, the following statement may be used in the index.php file of a template to insert the Modules in the 'user1' position and apply the 'custom' Module chrome:

<jdoc:include type="modules" name="user1" style="custom" />

It can be seen that the same Module chrome is applied to every Module in that position - in other words, if you want to have two Modules in a column, but want them to have different Module chrome, then they would need to be set up as two different 'positions' (e.g. 'user1' and 'user2').

The standard Joomla! 1.5+ package includes six default Module chrome styles. However, the flexibility of the template system means that you are not limited to these styles - it's very easy to create as many new styles as you want!


See also: Standard Module Chromes


</translate>

Applying custom Module chrome

To define custom Module chrome in your template you need to create a file called modules.php in your template html directory. For example, this might be PATH_TO_JOOMLA/templates/TEMPLATE_NAME/html/modules.php.

In this file you should define a function called modChrome_STYLE where 'STYLE' is the name of your custom Module chrome. This function will take three arguments, $module, &$params, and &$attribs, as shown:

<?php 
  function modChrome_STYLE( $module, &$params, &$attribs ) 
  {
    /* chromed Module output goes here */
  }
?>

Within this function you can make use of any of the available Module properties (i.e. the fields in the jos_modules table in the Joomla! database on your server) for that Module, but the main ones you are likely to need are $module->content, $module->showtitle and $module->title. $module->showtitle is a Boolean variable, so is either true (when the Module title should be shown) or false (when it shouldn't be shown). $module->content and $module->title will return the main Module content and the Module title respectively.

The function is a normal PHP function and so can use any regular PHP code. One common example is to use an if statement to check the value of $module->showtitle, and then include the title or not accordingly:

<?php
  if ($module->showtitle) 
  {
    echo '<h2>' .$module->title .'</h2>';
  }
?>

The Module parameters are accessed using the $params object. For example, it is possible to assign a Module class suffix to a Module in the backend of your Joomla! site; this is then stored in the parameters for that Module as moduleclass_sfx. To create a <div> with a class determined by the Module class suffix, you would use:

<div class="<?php echo $params->get( 'moduleclass_sfx' ); ?>">
  <!-- div contents -->
</div>

Custom chrome attributes

It is also possible to pass further attributes into the Module chrome function using the same <jdoc:include /> statement that sets the Module chrome. These additional attributes can be anything you like, and are stored in the $attribs array. Take the following example Module chrome function:

<?php
  function modChrome_custom( $module, &$params, &$attribs ) {
    if (isset( $attribs['headerLevel'] )) 
    {
      $headerLevel = $attribs['headerLevel'];
    } else {
      $headerLevel = 3;
    }
 
    if (isset( $attribs['background'] )) 
    {
      $background = $attribs['background'];
    } else {
      $background = 'blue';
    }
 
    echo '<div class="' .$params->get( 'moduleclass_sfx' ) .'" >';
 
    if ($module->showtitle) 
    {
      echo '<h' .$headerLevel .'>' .$module->title .'</h' .$headerLevel .'>';
    }
 
    echo '<div class="' .$background .'">';
    echo $module->content;
    echo '</div>';
 
    echo '</div>';
  }
?>

You would then set the values for background and headerLevel in the <jdoc:include /> statement as shown below. If no values are set, the attributes default to 'blue' and '3' respectively.

Passing attributes to Module chrome from <jdoc:include />
<jdoc:include /> statement Output

<jdoc:include type="modules" name="user1" style="custom" />

<div>
  <h3><!-- Module title --></h3>
 
  <div class="blue">
    <!-- Module content -->
  </div>
</div>

<jdoc:include type="modules" name="user1" style="custom" background="green" />

<div>
  <h3><!-- Module title --></h3>
 
  <div class="green">
    <!-- Module content -->
  </div>
</div>

<jdoc:include type="modules" name="user1" style="custom" headerLevel="1" background="yellow" />

<div>
  <h1><!-- Module title --></h1>
 
  <div class="yellow">
    <!-- Module content -->
  </div>
</div>

Further information about passing attributes to Module chrome can be found in jtopic:115953.