Actions

Difference between revisions of "Applying custom module chrome"

From Joomla! Documentation

(Applying custom Module chrome)
(Applying custom Module chrome)
Line 3: Line 3:
 
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/my_template/html/modules.php.
 
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/my_template/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:
+
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:
  
* the module object;
+
<source lang="php">
* a reference to the Module parameters array;
+
<?php
* a reference to the Module attribute array.
+
function modChrome_STYLE( $module, &$params, &$attribs ) {
 +
  /* chromed Module output goes here */
 +
}
 +
?>
 +
</source>
  
The function should echo the $module->content, wrapped in whatever chrome is requiredTo see how this is done look at the code for the standard Module chromes in [path-to-Joomla!]/templates/system/html/modules.php.
+
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 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.
  
Note that this makes it possible to pass parameters from the <jdoc:include> into the Module chrome function.  See: [[jtopic:115953]]
+
The function is a normal PHP function and so can use any regular PHP code.  One common example is to use an <tt>if</tt> statement to check the value of $module->showtitle, and then include the title or not accordingly:
 +
 
 +
<source lang="php">
 +
<?php
 +
if ($module->showtitle) {
 +
  echo '<h2>' .$module->title .'</h2>';
 +
}
 +
?>
 +
</source>
 +
 
 +
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 <tt>moduleclass_sfx</tt>.  To create a <tt><nowiki>&lt;div&gt;</nowiki></tt> with  a <tt>class</tt> determined by the Module class suffix, you would use:
 +
 
 +
<source lang="php">
 +
<div class="<?php echo $params->get( 'moduleclass_sfx' ); ?>">
 +
  <!-- div contents -->
 +
</div>
 +
</source>
 +
 
 +
It is also possible to pass further attributes into the Module chrome function using the same <tt><jdoc:include /></tt> 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:
 +
 
 +
<source lang="php">
 +
<?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>';
 +
}
 +
?>
 +
</source>
 +
 
 +
You would then set the values for <tt>background</tt> and <tt>headerLevel</tt> in the <tt><jdoc:include /></tt> statement as shown belowIf no values are set, the attributes default to 'blue' and '3' respectively.
 +
 
 +
{| class="wikitable"
 +
|+ Passing attributes to Module chrome from <tt><jdoc:include /></tt>
 +
! <tt><jdoc:include /></tt> statement
 +
! Output
 +
|-
 +
|
 +
<tt><jdoc:include type="modules" name="user1" /></tt>
 +
|
 +
<source lang="html4strict">
 +
<div>
 +
  <h3><!-- Module title --></h3>
 +
 
 +
  <div class="blue">
 +
    <!-- Module content -->
 +
  </div>
 +
</div>
 +
</source>
 +
|-
 +
|
 +
<tt><jdoc:include type="modules" name="user1" background="green" /></tt>
 +
|
 +
<source lang="html4strict">
 +
<div>
 +
  <h3><!-- Module title --></h3>
 +
 
 +
  <div class="green">
 +
    <!-- Module content -->
 +
  </div>
 +
</div>
 +
</source>
 +
|-
 +
|
 +
<tt><jdoc:include type="modules" name="user1" headerLevel="1" background="yellow" /></tt>
 +
|
 +
<source lang="html4strict">
 +
<div>
 +
  <h1><!-- Module title --></h1>
 +
 
 +
  <div class="yellow">
 +
    <!-- Module content -->
 +
  </div>
 +
</div>
 +
</source>
 +
|}
 +
Further information about passing attributes to Module chrome can be found in [[jtopic:115953]].
 
<noinclude>[[Category:Advanced]][[Category:Modules]][[Category:Templates]][[Category:Topics]]</noinclude>
 
<noinclude>[[Category:Advanced]][[Category:Modules]][[Category:Templates]][[Category:Topics]]</noinclude>

Revision as of 15:19, 20 January 2008

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/my_template/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 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>

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" />

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

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

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

<jdoc:include type="modules" name="user1" 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.