- What Is a Joomla! Template?
- The Localhost Design Process
- W3C and Tableless Design
- Creating a Simple Template: CSSTemplateTutorialStep1
- Using CSS to Create a Tableless Layout: CSSTemplateTutorialStep2
- Making a Real Joomla! 1.5 Template: CSSTemplateTutorialStep3
- Advanced Templating Features: CSSTemplateTutorialStep4
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
Advanced Templating Features: CSSTemplateTutorialStep4
Joomla 1.5 offers a number of advanced template features that significantly expand what is possible with templates. You have already seen one example in this lesson: the ability to create custom chrome for modules.
Next, we'll examine template parameters and template overrides.
Template Parameters
New in Joomla 1.5 is the addition of template parameters for templates. Template parameters allow you to pass variables to a template from options selected in the administrative backend.
You can add a relatively simple parameter function to the template. In the templateDetails.xml file, add the following:
<params> <param name="template_width" type="list" default="1" label="Template Width" description="Width style of the template"> <option value="2">Fluid with maximum and minimum </option> <option value="1">Medium</option> <option value="0">Small</option> </param> </params>
You also need a file called params.ini in your template folder. Joomla needs this file, which can be a blank file, to store the settings you have. For example, an .INI file for the previous example would look like this when set to Medium:
template_width=1
You need to make sure that this file is writable so changes can be made. When you use the Template Manager to open a template for editing, Joomla reports whether the parameters file is editable. If it isn't and your template needs to accept parameters, you need to change its permissions in the Cpanel. Unfortunately, there is a bug in Joomla that, based on certain conditions, causes Joomla to think the file is unwritable, when it actually is writable. You need to test this rather than rely on the interface text.
You also need to add params.ini as a file in the templateDetails.xml file list.
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 the administrative backend.
Based on the parameters you created above, you can see that it is a simple drop-down with three options. To display the options as radio buttons with a bit more detail about the choices, the param section of the templateDetails.xml file could look like this:
<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>
For the template width parameter to have an effect, you change the body tag in your index.php file to the following:
<body class="width_<?php echo $this->params->get('template_width'); ?>">
You then add the following to the CSS file, replacing the previous styles for #wrap:
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 you three options: a fixed narrow width, a fixed wide width, and a fluid version.
Using template parameters in this way gives you flexibility in almost any facet of a template—width, color, and so on—all controlled with conditional PHP being used to select from different CSS styles.
Template Overrides
Perhaps the most powerful new feature of templates in Joomla 1.5 is the ability to easily override core output. You do this with new output files called template files that correspond to the layout views of each individual component and module. Joomla checks in each case to see whether an override file exists in the template folder, and if one is found, it uses the file instead of the normal built-in template for that module or component.
Override Structure
All the layout views and templates in the main core are found in a /tmpl/ folder. The location is slightly different for components than for modules because a module essentially has only one view. Here's an example:
modules/mod_newsflash/tmpl/ modules/mod_poll/tmpl/ components/com_user/views/login/tmpl/ components/com_user/views/register/tmpl/ components/com_content/views/article/tmpl/ components/com_content/views/section/tmpl/
The basic structure of all components and modules is View
LayoutTemplates.
Table 9.3 shows some examples; note that a module has only one view.
Table 9.3. Examples of Overrides
|
View |
Layout |
Templates |
|
Category |
Blog.php |
blog_item.php blog_links.php |
|
Category |
default.php |
default_items.php |
|
(Newsflash module) |
default.php horz.php vert.php |
item.php |
There are usually several template files involved for a particular layout. They follow a common naming convention (see Table 9.4).
Table 9.4. Naming Convention for 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 folder, called tmpl, that contains its templates. Inside it are PHP files that create the output. Here's an 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 examples 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. If you open that file, you find this:
<?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; ?>
You could change this to remove the tables and replace them with <div> tags to make the module's output a little more accessible and compliant with standards:
<?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
In general, you can copy a module's template file, edit it, and save it within the template. The path where you place the edited file for modules is templatename/html/modulename/samefilename. The advantage of saving into the template instead of just overwriting the core template file that's being edited is that doing so allows you to upgrade to successive versions of Joomla without fear that your carefully edited template revisions will be lost. Note that after installing an upgrade to the Joomla core, it is wise to check whether the core template files have been modified so that your custom versions of these files can be updated to match and take advantage of any new features.
You just took the tables out of the newsflash module—very easily!
Component Overrides
Components work almost exactly the same way as modules, except that there are several views associated with many components.
If you look in the com_content folder, you see a folder called views, with a subfolder for each view:
/components/com_content/views/archive /components/com_content/views/article /components/com_content/views/category /components/com_content/views/frontpage /components/com_content/views/section
These folders would match the four views for content: archive, article, category, and section. (Recall that Front Page is a special case that draws from the articles in the content component.)
Inside a view, you find the tmpl folder, and in that you find the different layouts that are possible.
If you look in the category folder, in addition to some XML files, you see this:
/components/com_content/views/category/tmpl/blog.php /components/com_content/views/category/tmpl/blog_item.php /components/com_content/views/category/tmpl/blog_links.php /components/com_content/views/category/tmpl/default.php /components/com_content/views/category/tmpl/default_items.php
Note that in the case of com_content, the default.php layout generates the list layout, which presents articles as a list of linked titles.
If you open the blog_item.php file, you see the tables currently used. If you want to override the output, you put what you want to use in your template/html/ folder. The path where you place the edited file for components is templatename/html/componentname/viewname/samefilename; here's an 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 for customizing your Joomla site through its template. You can create output templates that focus on SEO, accessibility, or the specific needs of almost any client.
The Least You Need to Know
Joomla 1.5 offers new features for templates that allow designers to completely control the generated XHTML code and presentation of a Joomla website.
Tableless Joomla!
The Joomla download contains a template called Beez that is a community-developed example of the template overrides in action. The Design and Accessibility team has 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.
To see a simple way to transfer the overrides from Beez to your template, watch this short video clip: screencast.com/t/Gka4ecnYr. This demo video depicts simply copying the entire /html/ folder from the Beez template into your own template to achieve completely tableless layouts for core extensions. An advantage of this approach is that with each Joomla revision, the Beez template is modified with it. If you make no other changes to a specific component or to module template files, you can simply repeat the copy process to bring the latest Beez component and module template revisions into your template's html folder.
Notice, too, that as you add to your site third-party extensions that enhance any core functionality, you can utilize this override capability to implement their features as adaptations of core modules and components. As you install, ensure that your override files are not accidentally overwritten. You may need to edit the files to create a combined file, with code for both sets of features.
Recall that earlier in this chapter, we talked about the chrome options available in modules.php and the idea of adding your own options. As with overrides, the edited modules.php can be saved as templates/mytemplatename/html/modules.php. Be aware that third-party extensions also tend to add more chrome options to this file, so you may need to edit the file to combine the code segments for all the needed options into one file. (If installing a new extension ruins the display of previously working unrelated third-party modules, overwrites of overrides for this file is a likely suspect.)
CSSTemplateTutorialStep4
You now have a template based on a comp (or design). More visual typography has been added, but more importantly, you have used your pure CSS layout to create a template that has dynamic collapsible columns and a slick tabbed menu. You have also 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.
The Completed Template
Note that because the Joomla core's code is frequently changing and that override code needs to match the revision level of the software, the file CSSTemplateTutorialStep4.zip does not include the html folder with the overrides for a tableless layout. As described earlier, you need to copy the latest html folder from the latest Beez template into this template to complete it. Remember that to fully view this template's features with your content, the module suffix needs to be changed for your various menus and that modules such as Newsflash have to be set to certain positions (for example, top, for which you have specified the applicable CSS).