This chapter is from the book
This chapter is from the book
This chapter is from the book
Advanced Templating Features
Joomla 1.5 offers a number of advanced template features that significantly expand what is possible with templates. We have already seen one example in this chapter, the ability to create custom chrome or output for modules.
Let's examine each of these in turn:
- Template Parameters
- Template Overrides
Template Parameters
New in 1.5 is the addition of template parameters for templates. This allows you to pass variables to the template from options selected in the administrative backend.
We can add a relatively simple parameter function to our template. In the templateDetails.xml file, add the following:
<params> <param name="template_width" type="list" default="fluid" label="Template Width" description="Width style of the template"> <option value="fluid">Fluid with maximum and minimum</option> <option value="medium">Medium</option> <option value="small">Small</option> </param> </params>
You also need a file called params.ini in your template folder. It can be a blank file, but Joomla needs this file to store what settings you have. For example, an INI file for the previous example might look like this:
template_width=2
You need to make sure that this file is writable so changes can be made.
We also need to add that as a file in the templateDetails.xml file.
In the Template Manager for that template, you see the settings for the parameter, as shown in Figure 9.11.
)
Figure 9.11 Template parameters in admin backend
We can see that it is a simple drop-down with three options.
<param name="template_width" type="radio" default="0" label="Template Width" description="Change width setting of template"> <option value="0">800x600</option> <option value="1">1024x756</option> <option value="2">fluid (min/max with FF and IE7, 80% with IE6)</option> </param>
Then we change the body tag in our index.php to the following:
<body class="width_<?php echo $this->params->get('template_width'); ?>">
We then add the following to the CSS file:
body.width_0 div#wrap {
width: 760px;
}
body.width_1 div#wrap {
width: 960px;
}
body.width_2 div#wrap {
min-width:760px;
max-width:960px;
width:auto !important;
width:960px;
}
#wrap {
text-align:left;
margin:0 auto;
}
This gives us three options: a fixed narrow width, fixed wide width, and a fluid version.
Using template parameters in this way can give the site administrator flexibility in almost any facet of a template, width, color, and so on, all controlled with conditional PHP setting CSS styles.
Template Overrides
Perhaps the most powerful new feature of templates in 1.5 is the ability to easily override core output. This is done with new output files called template files that correspond to the layout views of components and modules. Joomla checks in each case to see if one exists in the template folder, and if one does, uses that one and overrides the normal output.
Override Structure
All of the layout views and templates are in the main core in a /tmpl/ folder. The location is slightly different for components as for modules because modules essentially have only one view. For example
modules/mod_newsflash/tmpl/ modules/mod_poll/tmpl/ components/com_login/views/login/tmpl/ components/com_content/views/section/tmpl/
The basic structure of all components and modules is View→Layout→Templates.
Table 9.3 shows some examples; note that modules only have one view.
Table 9.3. Example overrides
|
View |
Layout |
Templates |
|
Category |
Blog.php |
blog_item.php blog_links.php |
|
Category |
default.php default.php |
default_items.php |
|
(Newsflash module) |
horz.php vert.php |
_item.php |
There are usually several template files involved for a particular layout. They have a common naming convention (see Table 9.4).
Table 9.4. Naming convention of overrides
|
Filename Convention |
Description |
Example |
|
layoutname.php |
The master layout template |
blog.php |
|
layoutname_templatename.php |
A child layout template called from the master layout file |
blog_item.php blog_links.php |
|
_templatename.php |
A common layout template used by different layouts |
_item.php |
Overriding Modules
Each module has a new folder that contains its templates, which is called tmpl. Inside are PHP files that create the output. For example
/modules/mod_newsflash/tmpl/default.php /modules/mod_newsflash/tmpl/horiz.php /modules/mod_newsflash/tmpl/vert.php /modules/mod_newsflash/tmpl/_item.php
The first three are the three layouts of Newsflash based on which module options are chosen, and the _item.php file is a common layout template used by all three. Opening that file, we find
<?php // no direct access
defined('_JEXEC') or die('Restricted access'); ?>
<?php if ($params->get('item_title')) : ?>
<table class="contentpaneopen<?php echo $params->get( 'moduleclass_sfx' ); ?>">
<tr>
<td class="contentheading<?php echo $params->get( 'moduleclass_sfx' ); ?>"
width="100%">
<?php if ($params->get('link_titles') && $item->linkOn != '') : ?>
<a href="<?php echo $item->linkOn;?>" class="contentpagetitle<?php
echo $params->get( 'moduleclass_sfx' ); ?>">
<?php echo $item->title;?>
</a>
<?php else : ?>
<?php echo $item->title; ?>
<?php endif; ?>
</td>
</tr>
</table>
<?php endif; ?>
<?php if (!$params->get('intro_only')) :
echo $item->afterDisplayTitle;
endif; ?>
<?php echo $item->beforeDisplayContent; ?>
<table class="contentpaneopen<?php echo $params->get( 'moduleclass_sfx' ); ?>">
<tr>
<td valign="top" colspan="2"><?php echo $item->text; ?></td>
</tr>
</table>
<?php if (isset($item->linkOn) && $item->readmore) :
echo '<a href="'.$item->linkOn.'">'.JText::_('Read more').'</a>';
endif; ?>
We could change this to remove the tables to make it a little more accessible:
<?php // no direct access
defined('_JEXEC') or die('Restricted access'); ?>
<?php if ($params->get('item_title')) : ?>
<div class="contentpaneopen<?php echo $params->get( 'moduleclass_sfx' ); ?>">
<div class="contentheading<?php echo $params->get( 'moduleclass_sfx' ); ?>">
<?php if ($params->get('link_titles') && $item->linkOn != '') : ?>
<a href="<?php echo $item->linkOn;?>"
class="contentpagetitle<?php echo $params->get( 'moduleclass_sfx' ); ?>">
<?php echo $item->title;?>
</a>
<?php else : ?>
<?php echo $item->title; ?>
<?php endif; ?>
</div>
</div>
<?php endif; ?>
<?php if (!$params->get('intro_only')) :
echo $item->afterDisplayTitle;
endif; ?>
<?php echo $item->beforeDisplayContent; ?>
<div class="contentpaneopen<?php echo $params->get( 'moduleclass_sfx' ); ?>">
<?php echo $item->text; ?>
</div>
<?php if (isset($item->linkOn) && $item->readmore) :
echo '<a href="'.$item->linkOn.'">'.JText::_('Read more').'</a>';
endif; ?>
This new file should be placed in the template directory in a folder called html as follows:
templates/templatetutorial15bold/html/mod_newsflash/_item.php
We just took the tables out of the Newsflash module—as easy as that!
Component Overrides
Components work almost exactly the same way, except there are several views associated with many components.
If we look in the com_content folder, we see a folder called views.
/components/com_content/views/ /components/com_content/views/archive /components/com_content/views/article /components/com_content/views/category /components/com_content/views/section
So these folders would match the four possible views for content, archive, article, category, and section.
Inside a view, we find the tmpl folder, and in that, the different layouts that are possible.
If we look in the category folder, we see
/components/com_content/views/category/blog.php /components/com_content/views/category/blog_item.php /components/com_content/views/category/blog_links.php /components/com_content/views/category/default.php /components/com_content/views/category/default_items.php
Note that in the case of com_content, the default.php layout is referring to the standard layout that presents articles as a link list.
Opening up the blog_item.php file we see the tables currently used. If we want to override the output, we put what we want to use in our template/html/ folder, for example:
templates/templatetutorial15bold/html/com_content/category/blog_item.php
It's a relatively simple process to copy and paste all these views from the /components/ and /modules/ folders into the templates/yourtemplate/html folder.
The template override functionality provides a powerful mechanism to customize your Joomla site through its template. You can create output templates that focus on SEO, accessibility, or the specific needs of a client.
Tableless Joomla
The Joomla download also contains a template called Beez that is a developed example of the template overrides in action. The Design and Accessibility team have created a full example set of overrides as contained in the html folder. Our final example is a template that uses these overrides to remove all tables from the output of Joomla.
CSSTemplateTutorialStep4
We now have a template based on a comp (or design). More visual typography has been added, but more importantly, we have used our pure CSS layout to create a template that has dynamic collapsible columns and a slick tabbed menu. We have then overridden the output of Joomla so that no other tables are used. I have created an installable template that is available from www.joomlabook.com:
CSSTemplateTutorialStep4.zip