User:Over/Step by step to a Joomla Module - Overrides

Articles in this Series

1. Over/Step by step to a Joomla Module - Basic
2. Over/Step by step to a Joomla Module - Installation package
3. Over/Step by step to a Joomla Module - Data retrieval and styling
4. Over/Step by step to a Joomla Module - Overrides
5. Over/Step by step to a Joomla Module - Advanced installation
6. Over/Step by step to a Joomla Module - A form and ajax

This is a multiple article series on how to develop a module for Joomla! version Joomla 3.x. We go step by step from basic functionality to some more advanced. At the end of the tutorial we'll use your custom module to show you, how you can use the powerful output override ( = change ) methods provided by Joomla!. The only prerequisite for overrides is that the module or component comply to the Joomla! best practices. Navigate the articles in this series by using the navigation box to the right (the Articles in this series). Start with the first and follow them one by one. The next article builds on the knowledge and the files from the previous.

A Tip!

Should have's to complete this tutorial

You should have some knowledge in web technology but you don't have to be an expert at all. If you want to customise or even administrate a web site you will have to learn a little of everything e.g, Html coding, Css styling, Php programming, Sql database, using Javascript and about web servers. If you want to develop extensions for Joomla!, in small or large, you better start with a module before you try a larger project with a component. It is also a nice start to get knowledge on how to modify your sites template design. A Joomla! module is similar to a widget in other contexts. Even if plugins are the shortest extension type in sake of code, they require a little more advanced system knowledge to implement.

Introduction

In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

Your site template directory

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

...
/templates
  ...
  /mytemplate
    /css
      /mod_yourmodule
        yourmodule.css
      ...
    /html
      ...
      /com_mycomponent
        /view1
          default.php
        /view2
          default.php
      ...
      /layouts
        /joomla
          /content
            /info_block
      /mod_yourmodule
        default.php          
        alternative.php
      ...
    /images
      /mod_yourmodule
        yourmodule-logo.png
      ...
    /js
      /mod_yourmodule
        yourmodule.js
    ...
  ...

The illustration above shows the paths and some of the files in your templates folder. If we add files in those directories, they will be used instead of the extensions original files. You can use the Template Manager to easily create overrides in the html path. J3.x:How to use the Template Manager

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

Overriding

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

Examples - optional exclusion of the css and javascript:

default.php Css parameter

defined('_JEXEC') or die('Restricted access');

if ($params->get('load_css', 1)) 
{
   JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?>

default.php Javascript parameter

if ($params->get('load_js', 1)) 
{
   JHtml::_('bootstrap.framework');

   JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
		{
			alert(\'I am an alert box!\');});'
		);

}

The html/layouts path

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

Language string overrides

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own. Do not change the original files.

Go to Extensions → Language Manager → Overrides to create overrides that change texts.