Template overrides allow you to override the layout-files used within the SimpleLists component without changing the original code.

This method ensures that you can upgrade the original component without loosing your own changes. This is not for the weak of heart. If you’re not familiar with PHP and/or new to the concept of template overrides, you may experience difficulties with this tutorials.

About template overrides

The SimpleLists component follows the Joomla! MVC-principle and within this architecture layout-files are used to display HTML. Layout-files can be seen as simple scripts with a little bit of PHP-code but mostly HTML-tags.

Creating a template override means: Copying a layout-file from the MVC-folders of SimpleLists to your own template-folder. This copy can be edited freely, so you don’t have to modify the original. When searching for layout-files, Joomla! will search your template-folder first before defaulting to the MVC-folder within SimpleLists.

Overriding a layout

Let’s say we want to override the basic-layout of SimpleLists. First we need to locate the right layout-file within the component:

components/com_simplelists/views/simplelist/tmpl/basic.php

SimpleLists has multiple views, each containing a subfolder tmpl containing layout-files:

  • simplelist: for displaying a list of items – the main feature of SimpleLists
  • categories: for displaying a list of categories, which I find less usefull

Now create inside your template-folder a subfolder html if it doesn’t exist. For instance, if you’re using the rhuk_milkyway template, you will be looking at a folder templates/rhuk_milkyway/html. Next, create within html a folder com_simplelists. Next we want to override the view called simplelist and specifically the file basic.php. We copy the file components/com_simplelists/views/simplelist/tmpl/basic.php to the folllowing location:

templates/rhuk_milkyway/html/com_simplelists/simplelist/basic.php

What can you do with it?

Now that you have a copy of the original layout file, you can start changing it. You might want to edit the HTML-code or add some extra PHP-features. In most cases changing the CSS-code is sufficient, but you could create a completely different layout through a template override.

If you think your override is useful for the rest of the world, please post it on the Yireo Forum. It might be included as a new layout in SimpleLists.

Changing CSS code

Some layouts are shipped with their own CSS file (for instance: /components/com_simplelists/css/default.css). If you want to change these CSS-definitions, the first logical step would be to define the same CSS in your own CSS template-files and change it. That’s the cool thing of CSS (Cascading Style Sheets) – your template CSS will override the earlier SimpleLists CSS.

If this doesn’t work somehow, you could also do it the hard way: By using template overrides. Copy the layout-file to your template and change the following code:

$document->addStyleSheet($this->baseurl.'/components/com_simplelists/css/default.css');

for instance to:

$document->addStyleSheet($this->baseurl.'/templates/rhuk_milkyway/css/simplelists_default.css');

Now you have full control over the CSS.

Actually with newer versions of SimpleLists, it becomes much simpler (so don’t follow the above). Without changing any HTML/PHP-code, you can just the default.css file to the override-directory straight away:

templates/rhuk_milkyway/html/com_simplelists/css/default.css

Changing headers and footers

For most layouts (basic, default, table, picture) the header and footer is the same. SimpleLists uses its own function from each layout to use the same header-template. The code below refers to the file views/simplelist/tmpl/_header.php:

<?php echo SimplelistsViewHelper::loadTemplate('_header'); ?>

If you want to override the header-output but only for the table-layout, not the default-layout. To accomplish this, override the file table.php in your template (templates/rhuk_milkyway/html/com_simplelists/simplelist/table.php). Next, replace the line containing SimplelistsViewHelper::loadTemplate with the following:

<?php echo $this->loadTemplate('header'); ?>

Joomla! will now look for a file called table_header.php which he hopes to find in either your template-directory or within SimpleLists. It doesn’t exist within SimpleLists, so you have to create it within your template. Of course this can be a copy of _header.php:

templates/rhuk_milkyway/html/com_simplelists/simplelist/header_table.php

Tips

  • Do not create overrides for all layout-files at once. Only copy the file you really need to override. This eases the upgrade process in future versions.

Created on Tuesday, 23 June 2009
Modified on Sunday, 23 May 2010