How to Create Overrides in Joomla

If you like to change the way a Joomla! Extension is displayed on your site, you can either re-code the extension from the scratch or you can use overrides. The standard output from any Joomla module or component can be overridden by adding code to the html directory of your template.

It is also possible to override two aspects of core functionality: Module chrome, and pagination.

Template Overrides

Template overrides allow you to add, edit, and remove the components of the Joomla core output. Except for files that are provided in the Joomla! distribution itself, the methods for customization eliminate the need for designers and developers to hack core files that could change when the site is updated to a new version.

Because they are contained within the template, they can be deployed to the website without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

Joomla MVC Structure

MVC stands for Model-View-Controller and the concepts behind MVC enable the designers to get this extra flexibility. Components display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view". Most components have multiple views. However, the view doesn't actually display the output. The "layout" actually displays the output and it is possible for a view to have a many layouts.

So, components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table. So this view may have a "list" layout and a "table" layout to choose from.

Modules display one thing one way. Modules don't have views but they do support a layout. Some developers might even support a choice of layout through module parameters.

Template versus Layout

The template sets up a structural framework for the web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

Sub Layouts

In some views, some of the layouts have a group of files that start with the same name. For example, the category view. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php.

These sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:

echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');

When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item'). It is possible to override just a sub-layout without copying the whole set of files.

Component Layout Override

You can start with an existing view of module or component, and modify it to get what you want. Make a copy of the existing view to the html directory of your template, and then modify the copy. Each view is placed in a directory of its own. Under the view directory there is a /tmpl/ directory in which the layout files reside.

The directory structure is like this:

TEMPLATE_NAME/html/EXTENSION_NAME/VIEW_NAME/FILE_NAME.php

For example, if you want to change the way that the 'Article' view displays a com_content article, then you should copy the file at:

PATH_TO_JOOMLA/components/com_content/views/article/tmpl/default.php
to
TEMPLATE_NAME/html/com_content/article/default.php

Module Layout Override

Similarly, if you want to change how the mod_login Module is displayed, then you should copy:

PATH_TO_JOOMLA/modules/mod_login/tmpl/default.php
to
TEMPLATE_NAME/html/mod_login/default.php

If you create overrides in one template, they will not be available in other templates.

Images Override

You can override Joomla's core images that are stored in the /media/ folder. Put an alternative image with the same name in your template folder. For example, the Breadcrumbs Module uses an orange arrow that is retrieved from /media/system/images/arrow.png. Joomla will use your override version if you put it at /templates/your_template_name/images/system/arrow.png.

Module Chrome

There are a number of fixed styles that could display modules in a particular position. These styles are referred to as "chrome". The default chrome is in the system template:

/templates/system/html/modules.php

To create your own chrome or module styles, create or edit modules.php under the your templates /html/ directory.

For example, a module chrome that displays the module in a Definition List (a set of DL's, DT's and DD's). The style is called "dlist", so the name of the function needs to be modChrome_dlist.

/*
 * Module chrome that wraps the module in a definition list
 */
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
 <dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
 <?php if ($module->showtitle != 0) : ?>
 <dt>
 <?php echo $module->title; ?>
 </dt>
 <?php endif; ?>
 <dd>
 <?php echo $module->content; ?>
 </dd>
 </dl>
 <?php
}

The function takes three arguments:

  1. module object
  2. module parameters
  3. $attribs, an array of all the attributes in the jdoc XML tag

There are three main properties in the module object to be concerned with:

  1. showtitle tells whether to show the title of the module of not
  2. title is the title of the module
  3. content is the output of the module (from its layout)

Pagination Links Override

This override can control the display of items-per-page and the pagination links used with lists of information. To create override for pagination, create or edit pagination.php under the your templates /html/ directory.

When the pagination list is required, Joomla looks for this file in the default template. If it is found, it is loaded and the display functions of this file are used. There are four functions that can be used:

  1. pagination_list_footer: This function is responsible for showing the select list for the number of items to display per page.

  2. pagination_list_render: This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

  3. pagination_item_active: This function displays the links to other page numbers other than the "current" page.

  4. pagination_item_inactive: This function displays the current page number, usually not hyperlinked.

Alternate Layouts

Joomla 1.5 introduced the concept of overriding core layouts using the template override system. Joomla 2.5 introduced new features that give the site administrator more control over the display through the use of alternate layouts. There are five types of alternative layouts:

  1. Module
  2. Component
  3. Category
  4. Menu Item
  5. JLayouts

There are two important differences between a template override and an alternative layout:

  1. File name: For the template override, you would call the file default.php to match the core file name. For an alternative layout, you use a different file name. The only rule is that the file name should not have any underscores in it. This allows you to have complex layouts that include multiple files. The initial file to be called is named without underscores and any other files that are called from this initial file have underscores in the name.

  2. Unlike template override files which are called automatically using the template with the override, an alternative layout file is only called if you select it as a parameter in the configuration options of the module or component.

Component alternative layouts are only used when two conditions are met:

  1. They are specified in the component parameters
  2. There is no menu item for this specific component

For example, if you have one or more menu items of type "Single Article" set up for a given article, then the alternative layout for that article will not be used. Instead, the layout specified in the menu item will be used. This is consistent with the general way that component parameters work, where the most specific (in this case a single-article menu item) overrides the less specific (in this case, the article parameters). The same concept applies to category layouts as well.

Example: For articles (com_content), there are two core layouts available: Blog and List. Both of these options show under the "From Component" heading in the layout parameters for article category. So, like other layout options, you can select Blog or List for categories either globally (in the Article Manager Options), or when editing a single category. Like other layout parameters, this option will only take effect when there is no single-category menu item for the category.

Alternative Menu Layouts

To create a menu item alternative layout, you must include an XML file whose name matches the initial layout file. For example, to create an alternative menu item called "myarticle", you have to create two files in templates/YOUR_TEMPLATE/html/com_content/article folder called myarticle.php and myarticle.xml. The XML file uses the same format as the core Menu Item XML files.

This allows you to create a customized layout for this menu item and also customized parameters. These parameters can be used in the layout file. Alternative menu items show up when you select a menu item type in the Menu Manager.

Menu item layouts take priority over component or category alternative layouts.

Micro Layout Override (JLayout)

JLayouts are the micro-layouts for individual elements of Joomla pages. For example, the read more button, the intro image, the full image, are all examples of elements that are controlled via own JLayout.

For example, the Category Blog Layout view has the code to call the article title, an intro image, the intro text, as well as various other relevant parts of the page. This is what it looks like when you call an element using JLayout.

<?php echo JLayoutHelper::render('joomla.content.blog_style_default_item_title', $this->item); ?>

This particular bit of code calls the Article Title within the Joomla! Category Blog. The dots can be replaced with /'s to understand the directory structure. All JLayouts are initially found in JOOMLAROOT/layouts. Using the naming convention, this file is located in:

 JOOMLAROOT/layouts/joomla/content/blog_style_default_item_title.php

You should not edit JLayout files directly as changes would be overwritten during any core upgrade. The correct way to update the JLayout is by finding the element you want to override, and copying the file to your template. Then, copy the folder structure of the element that you want to override that exists within the layouts folder n the Joomla directory.

For example, to copy the intro_image file originally found in: JOOMLAROOT/layouts/joomla/content/intro_image.php

The copied file would be: templates/YOUR_TEMPLATE/html/layouts/joomla/content/intro_image.php