Extension Documentation

Chapter 8. Template Overrides
Prev Part I. Macrotone Issue Tracker Next

Chapter 8. Template Overrides

The area where most work would be required would most likely be where one wishes to change the default front end layout. This is going to be very dependant upon what front end template that is being using. As distributed the front end layout work with the supplied Joomla templates (protostar or beez3) but these may not be sufficient for use with all templates on all sites. If not then there would be a need to create specific template overrides.

If there is ever a need to change something in a core Joomla file, such as the layout, heading tags, etc., their is a proper way to approach this. If one alters the core files you run the risk of breaking the site if done improperly and if one upgrades the version of Joomla, this file is overridden. The same logic applies if one wishes to change a non-core component/module/plugin file.

One needs to copy the original php file from the main directory location and place the copy into the proper place in your template directory. The correct directory structure for your override file is:

TEMPLATE_NAME/html/EXTENSION_NAME/VIEW_NAME/FILE_NAME.php

So for example if one wanted to override the core file that controls the way an article is laid out, one would copy the original into the new directory inside the directory of site template files and edit it from there. Say for example we are using the protostar template. Use the following structure:

Original File location:
      JOOMLA_ROOT/components/com_content/views/article/tmpl/default.php
Override File Location:
      JOOMLA_ROOT/protostar/html/com_content/article/default.php

In our example we are concerned with possibly changing the form output for the Issue Tracker component.

Original File location:
      JOOMLA_ROOT/components/com_issuetracker/views/form/tmpl/edit.php
Override File Location:
      JOOMLA_ROOT/protostar/html/com_issuetracker/form/edit.php

Joomla 3 does all the work

Pull the Extensions menu down, click on Template Manager Extensions -> Template Manager

One will come to a chart of the templates that are installed on the site. The columns are Style, Default, Location, Template and ID

Figure 8.1. Template Manager Overrides: Templates screen.

Template Manager Overrides: Templates screen.

There will always be at least two templates where the Default star is filled in, one is your Administrator Template, whilst the other is the Site Template. There may well be more available as it is dependant upon the site administration.

Click on the name of the default site template in the Template column.

This brings one to the Template Manager: Customise Template screen.

Figure 8.2. Template Manager Overrides: Customise Templates screen.

Template Manager Overrides: Customise Template screen.

Click on the Create Overrides tab.

Figure 8.3. Template Manager Overrides: Edit screen.

Template Manager Overrides: Edit screen.

We are assuming that one has done their research and know what file they wish to override and how to edit the file to accomplish their goals.

We will assume that we wish to change the Issue Tracker form layout. Click on com_issuetracker and all of the views for that component will be displayed.

Figure 8.4. Template Manager Overrides: Issue Tracker views.

Template Manager Overrides: Issue Tracker views.

Click on Form, and after a moment, one should get a green box on top that says that the Override was created and the path to that file. This file will be place in the /templates/TEMPLATE_NAME/html/ directory.

Click on the Editor tab.

Figure 8.5. Template Manager Overrides: Form Edit screen.

Template Manager Overrides: Form Edit screen.

Click on the html folder in the left hand column.

This will open up to the existing sub-folders.

For our example of wishing to edit the Form layout, click on com_issuetracker -> form -> edit.php.

Keep in mind that this is a copy of the file. If one totally messes it up, one can simply delete the file from this directory, and Joomla will go back to using the original core file.

We ourselves have recently been ‘playing’ with a new ‘Bootstrap v3’ template for the front end of our site. This involved use creating a set of template overrides for our Issue Tracker component and some of the details are provided below.

Joomla has long had the ability to create Template Overrides, which are modifications to the Joomla components or modules. This permits changes to be made upon a ‘local site’ basis without the need to change or hack the supplied code.

We are primarily concerned with the Issue Tracker component and we have tried hard to produce front end displays of Individual Issues and of the Issue Entry form that would be usable in the majority of installations. However the differences between the various template used on sites are many and vast, and it is almost inevitable that they will not be suitable for everyone. This was indeed the situation we discovered ourselves when using a BootStrap template for the site.

The mechanism for creating a template override is as described above. Changing of the files themselves does however require a little PHP knowledge. The first thing is to identify the files that we wish to change. In our case we were aware that it was the template fields for the front end ‘itissues’ and ‘form’ views. These files are located in the directories:

components/com_issuetracker/views/itissues/tmpl

components/com_issuetracker/views/form/tmpl

We created copies of all of the files located in these two directories into our template html folder and use the same structure that it has in our component. In this case, it will be: html/com_issuetracker/form/*.php and html/com_issuetracker/itissues/*.php. (Note that we didn't need the view or the tmpl folder here).

Having copied our files, and there are several in each folder we are ready to start changing them.

As mentioned above, making changes here requires basic PHP knowledge, but one will notice that simple changes are also achievable by applying simple logic and identifying the tags used in the HTML generated from Joomla.

The changes one wants to make will obviously depend upon what one is trying to achieve, but here are a few changes that we have made.

a) The use of

<div class=”clr”>

in the files doesn't work in BootStrap v3, so we change it to read

<div class="clearfix">

instead. This change ensure that breaks occur at the correct places in the output display, particularly after ‘editor textarea’ fields.

b) Changes to the div class that surrounds the elements in the form to make use of the BootStrap class equivalents’. We also added layouts for the column widths at the same time.

i.e. Instead of:

<div class="form-group">
   <div class="col-sm-2 control-label">
      <?php echo $this->form->getLabel('alias'); ?>
   </div>
   <div class="col-sm-10" >
      <?php echo $this->form->getInput('alias'); ?>
   </div>
</div>

We changed it to be:

<div class="form-group">
   <div class="col-sm-2 control-label">
      <?php echo $this->form->getLabel('alias'); ?>
   </div>
   <div class="col-sm-10">
      <?php echo $this->form->getInput('alias'); ?>
   </div>
</div>

These changes go some way to creating a more pleasing output. One can go much further and the limit is really ones own limitation. Once the changes are made all that has to be done is to clear any Joomla cache and browser cache that may be in use and to redisplay the output page. If the result is not ideal then one can choose to re-edit the file(s) again confident in the knowledge that we are not changing the ‘base’ code in any way.

The advantage to this approach is that when (or if) the component is updated any changes one has made are preserved. Of course if the ‘updated’ component has changed the ‘base’ files in any way, such as to introduce a new field, it will be necessary to update our overridden template files, but this in not usually a very frequent change between versions. Unfortunately there is no real solution to this, other that keeping a record of all the changes one has made and checking which files are required in each update. It's also highly recommended that one backs up the website each time one updates the components and Joomla version.

Aside:

There is one situation which is often forgotten and that is, sometimes if an AJAX mechanism is being used to create ‘parts’ of a web page, the template overrides will not apply to the part for the page using Ajax. The reason is that the ‘page html’ is generated ‘on the fly’ by the server and then presented to the browser. In this case it is the ‘code generator’ that will require changing. The Issue Tracker component used Ajax to present the ‘Custom Fields’ feature in the front end forms. The reason is that when an Issue is being entered the project against which the issue is being raised is not known until the information is entered by the customer. Only once they have entered the project details is it possible to know which ‘custom fields’ need to be presented, to collect any additional information.

We discovered a few peculiarities in the ‘standard’ output from BootStrap v3 which caused a few 'opportunities for improvement'. The specific problems involve the display of an ‘additional label’ on textarea fields ( despite the label having a marked style of display:none; ), and a mis-formatting on form ‘tooltips’. This was investigated and was not seen when using a BootStrap v2 based template. The reason for the differences (and we mean here the 'peculiarities not the layout etc), that we saw between the BootStrap v3 and BootStrap v2 displays is that the BootStrap v2 template (protostar) is a version modified by Joomla, where as are/were using a 'pure' as released BootStrap v3 version.

Prev Up Next
Common message template changes Home Chapter 9. Custom Fields
Go To Top

Joomla! Debug Console

Session

Profile Information

Memory Usage

Database Queries