Understanding output overrides

It's always a bad practice to "hack" Joomla's core files. This means making any modifications to the joomla core components or it's libraries is not a good idea. When you later need to update Joomla, the update will wipe out the changes you made. Plus depending on the update your modification to the core may no longer be needed. Anyone who has ever used early versions of Jooomla knows how hard it was to control the output of Joomla. Sometimes its necessary to modify the way a page looks (i.e. the registration page) to make the page work with whatever type of site you are trying to build with Joomla. Output overrides allow you to completely override the way a page looks and the modifications are stored in whatever template you are using so that they won't be overwritten when you upgrade Joomla. It is also worth mentioning that there is a huge difference between the output that is generated on a page and the template. The template just controls the framework of each page and it's positions. The modules and content that is actually displayed in the page is not created by the template but by modules and components.

Joomla Components

Components are the most complex type of extension you can install into your Joomla site. The complexity here is because components can be very large pieces of software with much functionality and because of this components have many views which in turn can have multiple layouts. If this is confusing then please see our article on MVC. Views are the part of Joomla that are in control of displaying output to the user. This is the part you see when you use the site. The point of views is to display data to the users and to give users an place to input data if need be. This data could be a table of something or just a page with a login.

Joomla Modules

Modules are much more simple than components. Modules typically just display a layout to a position on a page and don't have views or multiple layouts. But it is possible to override module layouts as well so that you can get that customized look that you're after.

Overriding the output

Overrides are held in the html folder of your template. To create an override you can just add the components folder with the layouts inside to the html folder of your template. The common location is the html folder but some templates change the location of the template overrides folder so be careful that you know the location on your template. To illustrate how this would work lets pretend we want to override the way the login page looks. We would go to the html folder in the template and add a new directory called com_users and inside this directory we would add the default_login.php file that is present in the com_users component. We can now make our changes to this file and they will show and not be in danger of being overwritten by updates to Joomla's core.

Print Email

Jdoc statements and templatedetails.xml

Jdoc Statements are a little code snippet present in a template that tells joomla where to position content. Because this is a part of the template, these jdoc statements govern where positions and other output is positioned on all pages of your site.

Why do I need to know about this?

You can do so much more with a Joomla site by knowing a little bit about how the basic webpage is put together by Joomla. You can modify your template and make your site much more customized to your purpose. Take a peak at the nuts and bolts of your Joomla template (/templates folder in the root of your joomla installation's file system). Here you can add positions or change the structure of your template to better suited to your needs.

<jdoc:include />

Above is the basic jdoc statement. The statement also needs to have an attribute called type. This teels the template what type of content to display.

Different types


<jdoc:include type="component" />

This is the main output for the page and should only appear once. It would be silly to load a page with an article and see the article display twice.


<jdoc:include type="head" />

This tag should also appear only once in the <head> of the page all styles, scripts and meta tags for that page.


<jdoc:include type="message" />

This tag belongs in the <body> of the page and tells the template where to place system messages. This is generally positioned near the top center of a page on most templates.

Template Positions

The template positions are set in the templatedetails.xml file.

Below are some examples of module statements with module positions used frequently by Joomla! theme developers.

<jdoc:include type="modules" name="debug" />
<jdoc:include type="modules" name="sidebar-a" />
<jdoc:include type="modules" name="sidebar-b" style="rounded" />
<jdoc:include type="modules" name="showcase" style="xhtml" />
<jdoc:include type="modules" name="maintop" style="xhtml" />

You could add your own jdoc statement here to add a new position to your template. It's position in the xml document relative to the other jdoc statements determines where the position will show in your template. If you want to add a new position to the very top part of the page on your template. Your jdoc statement could go first before any of the other statements in the xml file.

Print Email

Adding a new module position in Joomla 2.5 or 3.x Template

The available module positions on your Joomla 2.5 or 3.x website is controlled by the template that you are using. If you would like to add a position to the template that didn't come out of the box, you can add a new position. We are going to outline below the correct steps to take to add a new custom position to your Joomla 2.5 or 3.x template.

Adding the code

Add the below code into the index.php file of the template that needs to have the new position.

<jdoc:include type="modules" name="position_name"   />

Open the TemplateDetails.xml file and add a position as a child element of the <positions></positions> tags.


Below is what the positions tags will look like:


This is all there is to it. Next add any styles that you desire and you are done.

Print Email