Difference between revisions of "Applying custom module chrome"

From Joomla! Documentation

(Marked this version for translation)
(Several markup changes.)
 
Line 1: Line 1:
 
<noinclude><languages /></noinclude> <translate>
 
<noinclude><languages /></noinclude> <translate>
 
<!--T:1-->
 
<!--T:1-->
<includeonly>==Applying custom Module chrome==</includeonly>
+
<includeonly>==Applying Custom Module Chrome==</includeonly>
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.
+
To define custom Module chrome in your template, create a file called ''modules.php'' in your template's ''html'' directory. For example, this might be ''PATH_TO_JOOMLA/templates/TEMPLATE_NAME/html/modules.php''.
  
 
<!--T:2-->
 
<!--T:2-->
In this file you should define a function called <code>modChrome_STYLE</code> where '<code>STYLE</code>' is the name of your custom Module chrome. This function will take three arguments, <code>$module</code>, <code>&$params</code>, and <code>&$attribs</code>, as shown:
+
In this file, 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:
  
 
<!--T:3-->
 
<!--T:3-->
<source lang="php">
+
<syntaxhighlight lang="php">
<?php  
+
<?php
   function modChrome_STYLE( $module, &$params, &$attribs )  
+
   function modChrome_STYLE( $module, &$params, &$attribs )
 
   {
 
   {
 
     /* chromed Module output goes here */
 
     /* chromed Module output goes here */
 
   }
 
   }
 
?>
 
?>
</source>
+
</syntaxhighlight>
  
 
<!--T:4-->
 
<!--T:4-->
Within this function you can make use of any of the available Module properties (i.e. the fields in the <code>jos_modules</code> table in the Joomla database on your server) for that Module, but the main ones you are likely to need are <code>$module->content</code>, <code>$module->showtitle</code> and <code>$module->title</code>. <code>$module->showtitle</code> is a Boolean variable, so is either ''true'' (when the Module title '''should''' be shown) or ''false'' (when it '''shouldn't''' be shown). <code>$module->content</code> and <code>$module->title</code> will return the main Module content and the Module title respectively.
+
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.
  
 
<!--T:5-->
 
<!--T:5-->
The function is a normal PHP function and so can use any regular PHP code. One common example is to use an <code>if</code> statement to check the value of <code>$module->showtitle</code>, and then include the title or not accordingly:
+
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:
  
 
<!--T:6-->
 
<!--T:6-->
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
   if ($module->showtitle)  
+
   if ($module->showtitle)
 
   {
 
   {
 
     echo '<h2>' .$module->title .'</h2>';
 
     echo '<h2>' .$module->title .'</h2>';
 
   }
 
   }
 
?>
 
?>
</source>
+
</syntaxhighlight>
  
 
<!--T:7-->
 
<!--T:7-->
The Module parameters are accessed using the <code>$params</code> 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 <code>moduleclass_sfx</code>. To create a <code>&lt;div&gt;</code> with a <code>class</code> determined by the Module class suffix, you would use:
+
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 ''&lt;div&gt;'' with a ''class'' determined by the Module class suffix, you would use:
  
 
<!--T:8-->
 
<!--T:8-->
<source lang="php">
+
<syntaxhighlight lang="php">
 
<div class="<?php echo $params->get( 'moduleclass_sfx' ); ?>">
 
<div class="<?php echo $params->get( 'moduleclass_sfx' ); ?>">
 
   <!-- div contents -->
 
   <!-- div contents -->
 
</div>
 
</div>
</source>
+
</syntaxhighlight>
  
=== Custom chrome attributes === <!--T:9-->
+
=== Custom Chrome Attributes === <!--T:9-->
It is also possible to pass further attributes into the Module chrome function using the same <code><jdoc:include /></code> statement that sets the Module chrome. These additional attributes can be anything you like, and are stored in the <code>$attribs</code> array. Take the following example Module chrome function:
+
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:
  
 
<!--T:10-->
 
<!--T:10-->
<source lang="php">
+
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
   function modChrome_custom( $module, &$params, &$attribs ) {
 
   function modChrome_custom( $module, &$params, &$attribs ) {
     if (isset( $attribs['headerLevel'] ))  
+
     if (isset( $attribs['headerLevel'] ))
 
     {
 
     {
 
       $headerLevel = $attribs['headerLevel'];
 
       $headerLevel = $attribs['headerLevel'];
Line 58: Line 58:
  
 
     <!--T:11-->
 
     <!--T:11-->
if (isset( $attribs['background'] ))  
+
if (isset( $attribs['background'] ))
 
     {
 
     {
 
       $background = $attribs['background'];
 
       $background = $attribs['background'];
Line 69: Line 69:
  
 
     <!--T:13-->
 
     <!--T:13-->
if ($module->showtitle)  
+
if ($module->showtitle)
 
     {
 
     {
 
       echo '<h' .$headerLevel .'>' .$module->title .'</h' .$headerLevel .'>';
 
       echo '<h' .$headerLevel .'>' .$module->title .'</h' .$headerLevel .'>';
Line 83: Line 83:
 
   }
 
   }
 
?>
 
?>
</source>
+
</syntaxhighlight>
  
 
<!--T:16-->
 
<!--T:16-->
You would then set the values for <code>background</code> and <code>headerLevel</code> in the <code><jdoc:include /></code> statement as shown below. If no values are set, the attributes default to 'blue' and '3' respectively.
+
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.
  
 
<!--T:17-->
 
<!--T:17-->
 
{| class="wikitable"
 
{| class="wikitable"
|+ Passing attributes to Module chrome from <code><jdoc:include /></code>
+
|+ Passing attributes to Module chrome from ''<jdoc:include />''
! <code><jdoc:include /></code> statement
+
! ''<jdoc:include />'' statement
 
! Output
 
! Output
 
|-
 
|-
 
|
 
|
<code><jdoc:include type="modules" name="user1" style="custom" /></code>
+
''<jdoc:include type="modules" name="user1" style="custom" />''
 
|
 
|
<source lang="html4strict">
+
<syntaxhighlight lang="html4strict">
 
<div>
 
<div>
 
   <h3><!-- Module title --></h3>
 
   <h3><!-- Module title --></h3>
Line 106: Line 106:
 
   </div>
 
   </div>
 
</div>
 
</div>
</source>
+
</syntaxhighlight>
 
|-
 
|-
 
|
 
|
<code><jdoc:include type="modules" name="user1" style="custom" background="green" /></code>
+
''<jdoc:include type="modules" name="user1" style="custom" background="green" />''
 
|
 
|
<source lang="html4strict">
+
<syntaxhighlight lang="html4strict">
 
<div>
 
<div>
 
   <h3><!-- Module title --></h3>
 
   <h3><!-- Module title --></h3>
Line 120: Line 120:
 
   </div>
 
   </div>
 
</div>
 
</div>
</source>
+
</syntaxhighlight>
 
|-
 
|-
 
|
 
|
<code><jdoc:include type="modules" name="user1" style="custom" headerLevel="1" background="yellow" /></code>
+
''<jdoc:include type="modules" name="user1" style="custom" headerLevel="1" background="yellow" />''
 
|
 
|
<source lang="html4strict">
+
<syntaxhighlight lang="html4strict">
 
<div>
 
<div>
 
   <h1><!-- Module title --></h1>
 
   <h1><!-- Module title --></h1>
Line 134: Line 134:
 
   </div>
 
   </div>
 
</div>
 
</div>
</source>
+
</syntaxhighlight>
 
|}
 
|}
 
Further information about passing attributes to Module chrome can be found in [[jtopic:115953]].
 
Further information about passing attributes to Module chrome can be found in [[jtopic:115953]].

Latest revision as of 17:10, 10 October 2022

Other languages:
Deutsch • ‎English • ‎中文(台灣)‎

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

In this file, 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[edit]

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.