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

Under Construction

Introduction

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!

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 temlate is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

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.

Example - optional exclusion of the css:

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);
}
?>