Difference between revisions of "Applying custom module chrome"
From Joomla! Documentation
m |
(Several markup changes.) |
||
(10 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | To define custom Module chrome in your template | + | <noinclude><languages /></noinclude> <translate> |
+ | <!--T:1--> | ||
+ | <includeonly>==Applying Custom Module Chrome==</includeonly> | ||
+ | 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 | + | <!--T:2--> |
+ | 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--> |
− | <?php | + | <syntaxhighlight lang="php"> |
− | function modChrome_STYLE( $module, &$params, &$attribs ) { | + | <?php |
− | + | function modChrome_STYLE( $module, &$params, &$attribs ) | |
− | } | + | { |
+ | /* chromed Module output goes here */ | ||
+ | } | ||
?> | ?> | ||
− | </ | + | </syntaxhighlight> |
− | 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 | + | <!--T:4--> |
+ | 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. | + | <!--T:5--> |
+ | 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--> |
+ | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
− | if ($module->showtitle) { | + | if ($module->showtitle) |
− | + | { | |
− | } | + | echo '<h2>' .$module->title .'</h2>'; |
+ | } | ||
?> | ?> | ||
− | </ | + | </syntaxhighlight> |
− | The Module parameters are accessed using the $params object. | + | <!--T:7--> |
+ | 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: | ||
− | < | + | <!--T:8--> |
+ | <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> | ||
− | </ | + | </syntaxhighlight> |
− | == | + | === Custom Chrome Attributes === <!--T:9--> |
− | It is also possible to pass further attributes into the Module chrome function using the same | + | 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--> |
+ | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
− | function modChrome_custom( $module, &$params, &$attribs ) { | + | function modChrome_custom( $module, &$params, &$attribs ) { |
− | + | if (isset( $attribs['headerLevel'] )) | |
− | + | { | |
− | + | $headerLevel = $attribs['headerLevel']; | |
− | + | } else { | |
− | + | $headerLevel = 3; | |
+ | } | ||
− | + | <!--T:11--> | |
− | + | if (isset( $attribs['background'] )) | |
− | + | { | |
− | + | $background = $attribs['background']; | |
− | + | } else { | |
+ | $background = 'blue'; | ||
+ | } | ||
− | + | <!--T:12--> | |
+ | echo '<div class="' .$params->get( 'moduleclass_sfx' ) .'" >'; | ||
− | + | <!--T:13--> | |
− | + | if ($module->showtitle) | |
− | + | { | |
+ | echo '<h' .$headerLevel .'>' .$module->title .'</h' .$headerLevel .'>'; | ||
+ | } | ||
− | + | <!--T:14--> | |
− | + | echo '<div class="' .$background .'">'; | |
− | + | echo $module->content; | |
+ | echo '</div>'; | ||
− | + | <!--T:15--> | |
− | } | + | echo '</div>'; |
+ | } | ||
?> | ?> | ||
− | </ | + | </syntaxhighlight> |
− | You would then set the values for | + | <!--T:16--> |
+ | 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--> | ||
{| class="wikitable" | {| class="wikitable" | ||
− | |+ Passing attributes to Module chrome from | + | |+ Passing attributes to Module chrome from ''<jdoc:include />'' |
− | ! | + | ! ''<jdoc:include />'' statement |
! Output | ! Output | ||
|- | |- | ||
| | | | ||
− | + | ''<jdoc:include type="modules" name="user1" style="custom" />'' | |
| | | | ||
− | < | + | <syntaxhighlight lang="html4strict"> |
<div> | <div> | ||
<h3><!-- Module title --></h3> | <h3><!-- Module title --></h3> | ||
− | <div class="blue"> | + | <!--T:18--> |
+ | <div class="blue"> | ||
<!-- Module content --> | <!-- Module content --> | ||
</div> | </div> | ||
</div> | </div> | ||
− | </ | + | </syntaxhighlight> |
|- | |- | ||
| | | | ||
− | + | ''<jdoc:include type="modules" name="user1" style="custom" background="green" />'' | |
| | | | ||
− | < | + | <syntaxhighlight lang="html4strict"> |
<div> | <div> | ||
<h3><!-- Module title --></h3> | <h3><!-- Module title --></h3> | ||
− | <div class="green"> | + | <!--T:19--> |
+ | <div class="green"> | ||
<!-- Module content --> | <!-- Module content --> | ||
</div> | </div> | ||
</div> | </div> | ||
− | </ | + | </syntaxhighlight> |
|- | |- | ||
| | | | ||
− | + | ''<jdoc:include type="modules" name="user1" style="custom" headerLevel="1" background="yellow" />'' | |
| | | | ||
− | < | + | <syntaxhighlight lang="html4strict"> |
<div> | <div> | ||
<h1><!-- Module title --></h1> | <h1><!-- Module title --></h1> | ||
− | <div class="yellow"> | + | <!--T:20--> |
+ | <div class="yellow"> | ||
<!-- Module content --> | <!-- Module content --> | ||
</div> | </div> | ||
</div> | </div> | ||
− | </ | + | </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]]. | ||
+ | </translate> | ||
<noinclude> | <noinclude> | ||
[[Category:Advanced]] | [[Category:Advanced]] | ||
[[Category:Modules]] | [[Category:Modules]] | ||
− | [[Category: | + | [[Category:Template Development]] |
− | [[Category: | + | [[Category:Template Reference]] |
+ | </noinclude> |
Latest revision as of 12:10, 10 October 2022
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.
<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.