Actions

Difference between revisions of "Applying custom module chrome"

From Joomla! Documentation

m
 
(4 intermediate revisions by 2 users not shown)
Line 78: Line 78:
 
|-
 
|-
 
|
 
|
<code><jdoc:include type="modules" name="user1" /></code>
+
<code><jdoc:include type="modules" name="user1" style="custom" /></code>
 
|
 
|
 
<source lang="html4strict">
 
<source lang="html4strict">
Line 91: Line 91:
 
|-
 
|-
 
|
 
|
<code><jdoc:include type="modules" name="user1" background="green" /></code>
+
<code><jdoc:include type="modules" name="user1" style="custom" background="green" /></code>
 
|
 
|
 
<source lang="html4strict">
 
<source lang="html4strict">
Line 104: Line 104:
 
|-
 
|-
 
|
 
|
<code><jdoc:include type="modules" name="user1" headerLevel="1" background="yellow" /></code>
+
<code><jdoc:include type="modules" name="user1" style="custom" headerLevel="1" background="yellow" /></code>
 
|
 
|
 
<source lang="html4strict">
 
<source lang="html4strict">
Line 120: Line 120:
 
[[Category:Advanced]]
 
[[Category:Advanced]]
 
[[Category:Modules]]
 
[[Category:Modules]]
[[Category:Templates]]
+
[[Category:Template Development]]
[[Category:Topics]]</noinclude>
+
[[Category:Template Reference]]
 +
</noinclude>

Latest revision as of 08:16, 24 June 2013

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.