I got this email from a reader of JoomlaBlogger a few days ago:
I work a lot with Joomla and while I am not a php coder myself, I do on occasion hack files to make a template or a component work the way I want it to, if I can find good instructions in a forum. I know that with Joomla 1.5 now we have the possibility to make these (or some of these changes) in a "template override", as an exterior file that will not get overwritten when you upgrade the template or the component. I have not yet found a good tutorial on how to do this. I would appreciate a clear and simple (if possible) explanation of WHEN to use a template override, HOW to do it (including code examples if you have to create your own code, where exactly do you put the new file, do you have to create a new folder, etc.), and possibly seeing a case to illustrate it.
I had thought about writing a post about template overrides, and this email got me started.
First, a note of caution
How ever tempting it might be to change the core files themselves, it's not a good idea. Simply put: If you change some of the core files and they are updated in a new Joomla version, the changes will be overwritten by the update.
I will offer an example. It's very easy to change the appearance of one of the core modules by editing the files found in /modules/com_modulename/. Don't do it this way! As Wilco Jansen said during the JoomlaDay Norway 2008: - You should never need to hack the core files of Joomla!
Fortunately, there is a better way.
The solution is called template overrides, output overrides or layout overrides. These are files that reside in the /templates/YOURTEMPLATE/html/ folder. The files located here will override the core files or other files which create some form of output on the finished HTML page.
When to use template overrides
The most widespread use of template overrides is to change the output from com_content. Most professional Joomla templates use this type of overrides. Mainly they use it to create table-less HTML output from the content component and to make custom layout modifications. For instance, you could change the order of the elements, or include hard-coded text and elements, or add custom classes or IDs to facilitate CSS changes.
To create output (or template) overrides, you need to create an HTML folder in your template folder. For instance, you can see that there is an HTML folder already present for the Beez template in /templates/beez/html/. This is where you need to place the files that override the output of the components you want to modify.
This will only work for the specific template
Remember that this HTML folder resides inside the specific template folder. It will not work for other templates. If you switch to another template, you need to copy the content of your HTML folder to your new template folder. In that case, make sure you don't accidentally overwrite any override files that come as a part of the new template.
Examples of Joomla template overrides
There are lots of uses for template overrides. I will show you a few examples. The examples are there to spark your imagination. Come up with your own ways of leveraging this powerful feature of Joomla.
The examples I provide here only details using template overrides for core components. You can do this for any module, plugin or component. I've used template overrides to change the output from YooGallery for instance.
How to customize the output of 'category list layouts'
If you're like me, you have trouble understanding the point of having numbers before each line when displaying articles in the Category List layout. Worse even, is the fact that these numbers are not possible to remove. At least not by using the menu item parameters or other settings in the Joomla admin. The numbers colum is actually hard-coded into the layout of the com_content category list layout files.
To change this, and other parts of the category list layout, you need to create a new directory in the /templates/YOURTEMPLATE/html/com_content/ directory. If it's not already there, it should be named /category/. Now you can copy the file default_items.php from /components/com_content/views/category/tmpl/ and into the folder you just created.
Thus, you will end up with a file located in this folder:
At this point you're ready to customize your template override. The file you copied will override the standard output, leaving the original file intact.
To remove the numbering from the contact category list layout table, follow these steps:
1. Remove the header column
Delete or comment out the following code (around line 42):
<td class="sectiontableheader<?php echo $this->escape($this->params->get('pageclass_sfx')); ?>" align="right" width="5%"
<?php echo JText::_('Num'); ?>
2. Remove the actual number
Delete this code further down in the code:
<?php echo $this->pagination->getRowOffset( $item->count ); ?>
Refresh your category list layout in the front-end to decide if you're happy with the result. You could do other changes as well. For instance, you could change the percentage width (width="20%" etc) for the columns with class names. That way, you can style the individual column widths (and other parameters) using CSS. I think this is a more flexible way of working.
<?php if ($this->params->get('show_title')) : ?>
<td class="headertitle sectiontableheader<?php echo $this->escape($this->params->get('pageclass_sfx')); ?>" width="45%">
<?php echo JHTML::_('grid.sort', 'Item Title', 'a.title', $this->lists['order_Dir'], $this->lists['order'] ); ?>
<?php endif; ?>
How to customize the output of com_contact
The same goes for the Contact category output. If you create a menu item showing a contact category, Joomla 1.5 will present a table with numbers as the first column. This might be OK for some, but most of my customers find it strange. Template overrides to the resque!
We follow the same procedure as in the previous example. However, this time we will have to edit two files. Follow these steps:
1. Create a folder here (see screenshot to the right):
2. Copy these two files from /components/com_contact/views/category/tmpl/:
3. In default.php, delete or comment out this code (around line 62):
<td width="5" align="right" class="sectiontableheader<?php echo $this->escape($this->params->get('pageclass_sfx')); ?>">
<?php echo JText::_('Num'); ?>
4. In default_items.php, delete or comment out this code (around line 7):
<td align="right" width="5">
<?php echo $item->count +1; ?>
This will remove the numbers column. Both in the header and what ever rows there are in the table.
You can see the modified contact category layout here.
You can experiment with changing the different columns around. For instance, one of my clients wanted the cell phone column to appear before the email column. Just remember to move both the header column and the actual data column (as they are in two separate files).
How to create line breaks in Joomla article titles
If you've ever tried putting in a <br /> tag in the Joomla article title to create a line break, you've discovered that this won't work. The HTML is not parsed and thus Joomla will show the tag in clear text.
I've written a tutorial on how to create line breaks in Joomla article titles by using template overrides. This is a powerful technique which can be applied in other situations as well.
Use your imagination
I hope you now have a better understanding of how Joomla template overrides work. They are fun to work with. Start simple and build from that.
Thanks to Alice for sending me the email which got this post started.
And remember: Never hack the core!