I picked up a copy of an excellent book called Joomla! 1.5 Template Design from PACKT publishing, and I must say it’s a good read for anyone wanting to understand how to build a Joomla template. The Joomla template book covers everything step by step and manages to convey the information in a way that beginners will easily understand, but won’t feel slow for readers at an intermediate/advanced level.
With this book in hand I’m fairly confident most of you will be able to produce your first custom Joomla template and website in a weekend.
After reading Tessa’s book I spoke with the good people at PACKT and they agreed to let me publish a sample of the book for our JoomlaBear readers. Have a read below of the Joomla 1.5 Template Reference and if you are like me you will quickly realize this is a great Joomla manual to have on the book shelf.
In this article by Tessa Blakeley Silver from her latest book Joomla! 1.5 Template Design, we’ll go over jdoc tags for templates, the standard CSS class and id rules that Joomla! outputs, how module and template override files are organized, as well as useful Joomla! PHP code you can use in your template to aid in making it more user-friendly and dynamic. Of course, wherever possible, we’ll let get to know the relevant Joomla! documentation links to bookmark, to give you in-depth detail and save you a little time searching through the Joomla! documentation site and the Web.
Take note that we’ll see how these Joomla! 1.5 items differ in use from a Joomla! 1.0 template, so that those of you looking to update a Joomla! 1.0 template to 1.5 can quickly get a handle on what to update in your templates and what new features to add. Consider this article your “cheat sheet”.
Jdoc include tags
The jdoc include tags are new to Joomla! 1.5 templates. Previously in Joomla! 1.0, more complicated, abstract PHP code, originally created for Mambo, was used. The jdoc tags are much cleaner, visually make sense (no more guessing what attribute values like “-3″ mean), and, thus, are much easier to remember.
Site header information tag
This is pretty simple: the tag outputs all the appropriate meta tags and header information that corresponds to your site and each individual page:
Joomla! 1.0 to 1.5 conversion
If you’re converting a 1.0 template to 1.5, you’ll replace this PHP function in your 1.0 template’s header with the above jdoc tag:
<?php mosShowHead(); ?>
The component include tag
Wherever you place this include, all component content will appear (from articles to poll results to contact forms, and so on):
Joomla! 1.0 to 1.5 conversion
The 1.0 equivalent of this tag is the mosMainBody function. You’ll replace this PHP function with the above jdoc include:
Module position tags
With module tags, we have a few options to work with. So, we can control what modules load into the area, thus assigning their positions as well as what style to output the module content with:
Module position styles
In the jdoc include example above, within the style attribute, you can place one of the following six style names to various effect:
none or raw
Modules are displayed in plain
Modules are displayed wrapped
Modules are displayed wrapped
Modules are displayed in a
Modules are again displayed in
This is used to preview
In your Administration panel,
Joomla! 1.0 to 1.5
For those of you trying to update a 1.0 template, replace your oldmosLoadModules tag:
With the new jdoc include:
Where modName is located in your mosLoadModule tag. Be sure to replace it with the module postionName in your jdoc include tag, and where your styleNumber was in your mosLoadModule tag, replace it with the corresponding styleName in your jdoc include tag. The following will help you match up and select the appropriate style name
- table = 0 (this still is
- horiz = 1
- none (or raw) = -1
- xhtml = -2
- rounded = -3
Menu output options
Very similar to 1.0, Joomla! 1.5 does need a little special attention to menu output. Yes, menus are modules, and yes, even though you set your module position to output rounded or xhtml, you might want to log in to your admin panel and make sure that your menus are outputting the XHTML markup you desire.
The default for Joomla! 1.5 is now List, which will also display nested lists for multi-level menu items (the Extend extension is no longer needed). However, if you’re upgrading a 1.0 template and need the menu to output in a horizontal or vertical table, you’ll need to assign the correct XHTML output in the menu’s Module Manager.
Go to Extensions | Module Manager and select the relevant menu item.
On the far right, select the appropriate Menu Style from the drop-down list. Your choices are List, Legacy – Vertical, Legacy – Horizontal, and Legacy – Flat List (note: this won’t include nested lists; not recommended). The following screenshot illustrates selecting the menu style.
- List: This will output your menus in clean WC3-compliant lists and nest any submenu items a parent or top-level or root menu item may have. This is highly recommended, as it allows your menus to be easily (and beautifully) styled with CSS, degrade gracefully in older browsers and yet still appear functional in older, text-based browsers. (Many mobile-and disability-focused browsers are text-based and strip out CSS styles.)
- Legacy – Vertical: This option will display the top-level menu items only in a table format that stacks vertically. You’ll probably select this only if you’re using an older 1.0 that you’ve upgraded to 1.5 or installed in Joomla! 1.5’s “legacy mode”.
- Legacy – Horizontal: This option will display the top-level menu items only in a table that extends out horizontally. You’ll probably select this only if you’re using an older 1.0 that you’ve upgraded to 1.5 or installed in Joomla! 1.5’s legacy mode.
- Legacy – Flat List: This option does display in a W3C-compliant list mode, yet only displays the top-level menu items. Again, you’ll probably select this only if you’re using an older 1.0 that you’ve upgraded to 1.5 or
installed in Joomla! 1.5’s legacy mode.
Template overrides are specialized files the Joomla! system checks for in your template’s html folder. Template overrides include module chrome andcomponent overrides. If Joomla! discovers that a particular file exists, for a specific module or component, in your template’s html folder, Joomla! will reference that file’s output, rather than its core output. The most common approach is to use the Beez template overrides, if you’d like to have truly accessible, table-less XTHML output from Joomla!. You can also create your own files.
Of course, the Joomla! system is not “psychic”! You can’t just create an override and place it anywhere in your template directory, named anything you want, and hope Joomla! figures out your intentions. There is a specific folder and order placement you have to follow in order for Joomla! to understand that your file is intended to override specific core output. We’ll take a closer look at this next.
Module overrides and chrome
In the earlier jdoc section, when we looked at module tags and layout control, we noted that you can specify rounded, xhtml,horiz, and vert styles. You can also easily set up additional chrome by editing or creating a file within the html directory, inside the appropriate mod_moduleName folder.
Inside the html directory, the following files are available to set up your own module chrome (see the next screenshot):
mod_newsflash/_item.php, default.php, horiz.php, andvert.php.
Keep in mind, while the stated folder structure is essential to follow, and each folder should have a default.php file in it, you can also create additional helper or view files if needed to support that layout. Notice that the Beez template mod_newsflash override takes advantage of this. Again, the purpose of overrides is to separate out the Joomla! CMS core from your site’s presentation. This means you can change how your content output from the components and modules are displayed, but any updates to Joomla’s core system will not require you to change your files (or it shouldn’t; It cannot be guaranteed the Joomla! development team will never produce a core system change that stops working with the API hooks used in the template overrides or module chrome, but that is the goal). This aspect gets a bit beyond the scope of this title, but if you’d like to know more, please reference the Joomla!
documentation site: http://docs.joomla.org/Understanding_Output_Overrides.
How module chrome works
If you open up the Beez module.php file, you’ll notice (under quite a bit of useful comments) some PHP code that looks like this (starting around line24):
$headerLevel = isset($attribs['headerLevel']) ? (int)$attribs['headerLevel'] : 3;
if (!empty ($module->content)) : ?>
<div class=”moduletable<?php echo $params->get(‘moduleclass_sfx’); ?>”>
<?php if ($module->showtitle) : ?>
<h<?php echo $headerLevel; ?>><?php echo $module->title;
?></h<?php echo $headerLevel; ?>>
<?php endif; ?>
<?php echo $module->content; ?>
You would reference this chrome override by calling the second half of the function name, after modChrome: modChrome_beezDivision. You would then reference beezDivision in your jdoc module position style tag
in the following fashion:
Your template will now call in this particular chrome override, as opposed to the standard xhtml style previously called in. Unfortunately, for display purposes, this chrome override is not really that much different from the
xhtml chrome style.
That’s OK, if we change the last value of the $headerLevel variable from 3 to 2 (about line 26 in the module.php file) like so:
We can quickly see the end result in our template’s user1 module position, as the header is now an h2 instead of an h3 tag (see the following screenshot):
From this example, you can see how to expand and start creating your own module chrome. You can, basically, copy the above beezDivision function, paste it underneath the existing function, and tweak the $headerLevel
variable as well as any XHTML markup you see surrounding the Joomla! PHP code.
To really construct module chrome from scratch, It is recommended that you be comfortable with PHP and understand the various variable and pJoomla! parameter you can use. You can find out more about these by referencing this page in the Joomla! documentation: http://docs.joomla.org/Applying_custom_module_chrome.
Don’t confuse module chrome with module overrides! You’ll note in the previous screenshot, showing the html directory with its module override directories, that in addition to the modules.php page, there are module overrides for specific module types. You can tweak, adjust, or write up these views from scratch, in addition to the chrome. The chrome that we just tweaked above is for general
output, and most module views that you tweak will also end up being pulled, so to speak, through the chrome. For example, you may tweak the poll’s module view (remember, the poll also has a component view) to be in an ordered list instead of an unordered list. That view, with the ordered list, will then also get pulled through the special chrome you set up, wrapping it in the header and div tags you specified.
Similar to module chrome and overrides, component overrides require that you copy in (or create from scratch) files inside specially named directories inside your html directory. The following screenshot displays these component override directories and files:
Also similar to module view overrides, component overrides just simply need to be there. If they’re not there, Joomla! automatically reverts to its core output. And once again, similar to module view overrides and module chrome, really whipping up component overrides from scratch requires a deeper understanding of Joomla! 1.5 and PHP than a book for creating templates aimed primarily at web designers can really get into.
If you feel your eye for PHP syntax is pretty good and you’d like to try your hand at component overrides, be sure to check out that Understanding Output Overrides in the Joomla! documentation: http://docs.joomla.org/Understanding_Output_Overrides.
You can also override and tweak your pagination layout with a file calledpagination.php inside the html folder. Be aware, this file is entirely PHP. You can look through it and easily see the XHTML markup to tweak,
but be careful! The XHTML markup is being built up and outputted inside the$html variable in PHP. If you accidentally delete or overwrite any of the PHP syntax surrounding the XHTML, you’ll break this file. Having a good eye for PHP syntax is a must for tweaking this file.
Additional template information
OK, we’ve already been chatting about how useful it is to, at the very least, have that eye for PHP syntax. It’s, of course, even more useful to have a little PHP under your belt. We’re going to quickly stray even further into PHP development, and then come right back to templating and Joomla! basics. Even if you have no interest whatsoever in PHP development, this little bit of background information on Joomla! 1.5 may help you better understand controlling your template.
Joomla! 1.5 was rebuilt using object-oriented programming, also affectionately called as OOP. One advantage of OOP is that you can use design patterns to aid in development. Joomla! 1.5 heavily relies on a design
pattern called the Model View Controller or MVC pattern. The MVC design pattern ensures that separate files containing specific PHP code are used to tell the content management system (the CMS) three main things. Mainly: what its purpose and core function is (the Model), how to control visual display (aka the View), and how to do specific things such as update,
delete, and edit content, and set CMS administration preferences, and so on (theControl).
Now, what the heck does this mean to you as a template designer? To start, as we saw above, we’re no longer constrained to that core Joomla! table output. The “View” of MVC is indeed separate from the rest of the system, and thus, we don’t have to go through all sorts of advanced discussions about how to hack tables out of the Joomla! system in a way that makes your CMS vulnerable to being incompatible with updates and has nothing to do with your template.
The next feature is that within this OOP, MVC framework, your whole template can be referenced as an “object”, and that simply means it can be referenced in your index.php file with PHP code using the $this->propertyName variable. We’ve already taken advantage of it several times in our template,mostly to help target our template directory using the baseurl property name. That is:
go_green/css/template.css” type=”text/css” />
The following are additional template properties you might find useful in dynamically enhancing your template:
<?php echo $this->_file; ?> // outputs the server path to the file
called in (not the same as the url path!) i.e.: /~user/httpdocs/1.5dev/templates/go_green/index.php
<?php echo $this->title; ?> //outputs the Article Title
<?php echo $this->description; ?> //outputs the Article Description
<?php echo $this->template; ?> //outputs the template’s Name
For a more complete listing of what’s available in your template’s object array, check out the Joomla! documentation: http://docs.joomla.org/Objects,_methods_and_properties_available_from_your_template.
You’ll also find the countModules method useful for helping you set up dynamic layouts for collapsible columns.
You’d replace positionName with the name of the module position you want to count the modules in; that is, right, user1, left,
footer, and so on.
For more information on the countModules method, check out these links in the Joomla! documentation:
Joomla! 1.5 Template Design
|Create your own professional-quality templates with this fast, friendly guide