Removing JCaption in Joomla! 2.5

In Joomla! 2.5, one small annoyance is the fact that it adds a small block of MooTools code to the head of every page to initialise JCaption image captions. There is no simple option to prevent this in the Joomla! Admin, as it is hard-coded into the Joomla! source. So I thought I'd outline a few of the options to remove it.

For those who are unfamiliar with this, the code being added looks like the following:

window.addEvent('load', function() {
    new JCaption('img.caption');
});

While the javascript file containing the JCaption code is also added as a script tag:

<script src="/media/system/js/caption.js" type="text/javascript"></script>

Removing the caption.js file

Solution

Add the following line of code in your template index.php file, before the html output:

unset($this->_scripts[JURI::root(true).'/media/system/js/caption.js']);

Explanation

Internally, Joomla! stores all javascript files to be added to the page in an array of the JDocument class called _scripts, where each element of the array contains a single javascript file. The '$this' variable within the template's index.php file refers to an instance of JDocument containing the content for that page. Consequently, to remove a script tag, we can simply remove it's element in the $this->_scripts array, which is what the PHP unset function does. As long as this removal occurs before the script tags are added to the page via the <jdoc:include type="head" /> tag, then the script tag wont be added to the page.

JURI::root(true)

The JURI::root(true) part returns the base folder for the current Joomla! installation. This is important if you have installed Joomla! in a sub-folder of your root www folder. If, for example, you have installed Joomla! in a 'myjoomla' folder, then

JURI::root(true).'/media/system/js/caption.js'

becomes '/myjoomla/media/system/js/caption.js', which is the correct file location (Joomla! internally also uses JURI::root(true) when it is building the file paths to these system files).

Example

As an example, we will use the Beez 20 template that ships with Joomla! 2.5. You can find the index.php for the Beez 20 template at /templates/beez_20/index.php. You should be able to find the index.php file for your template in it's corresponding template folder. In this index.php file, there is a section of PHP code that comes before the html output, and it's this section which we want to edit. In the Beez 20 template, it looks like this:

<?php
defined('_JEXEC') or die;
$showRightColumn        = ($this->countModules('position-3') or $this->countModules('position-6') or $this->countModules('position-8'));
$showbottom                        = ($this->countModules('position-9') or $this->countModules('position-10') or $this->countModules('position-11'));
$showleft                        = ($this->countModules('position-4') or $this->countModules('position-7') or $this->countModules('position-5'));
if ($showRightColumn==0 and $showleft==0) {
        $showno = 0;
}
JHtml::_('behavior.framework', true);
$color              = $this->params->get('templatecolor');
$logo               = $this->params->get('logo');
$navposition        = $this->params->get('navposition');
$app                = JFactory::getApplication();
$doc                = JFactory::getDocument();
$templateparams     = $app->getTemplate(true)->params;
$doc->addScript($this->baseurl.'/templates/'.$this->template.'/javascript/md_stylechanger.js', 'text/javascript', true);
?>

After adding the line to remove the caption.js file, it looks like this:

<?php
defined('_JEXEC') or die;
unset($this->_scripts[JURI::root(true).'/media/system/js/caption.js']);
$showRightColumn        = ($this->countModules('position-3') or $this->countModules('position-6') or $this->countModules('position-8'));
$showbottom                        = ($this->countModules('position-9') or $this->countModules('position-10') or $this->countModules('position-11'));
$showleft                        = ($this->countModules('position-4') or $this->countModules('position-7') or $this->countModules('position-5'));
if ($showRightColumn==0 and $showleft==0) {
        $showno = 0;
}
JHtml::_('behavior.framework', true);
$color              = $this->params->get('templatecolor');
$logo               = $this->params->get('logo');
$navposition        = $this->params->get('navposition');
$app                = JFactory::getApplication();
$doc                = JFactory::getDocument();
$templateparams     = $app->getTemplate(true)->params;
$doc->addScript($this->baseurl.'/templates/'.$this->template.'/javascript/md_stylechanger.js', 'text/javascript', true);
?>

Removing the JCaption Code

Having removed the caption.js file, we now need to remove the section of javascript that initialises JCaption. This is where it gets a little more difficult. Unlike with the names of javascript files, Joomla! does not store each block of javascript in an individual array element. There is only one array element, a single element of _script with the key 'text/javascript'. Every time a section of javascript code with type 'text/javascript' is added, it is simply appended to the end of this element. As a result, simply unsetting the array element as we did for the caption.js file will no longer work, as that will remove all the javascript, not just the JCaption javascript. Instead, we have some options.

Option 1: Remove the JCaption code from within the template using a Regular Expression

Solution

Add the following code to the template index.php file, before the html output:

if (isset($this->_script['text/javascript']))
{
    $this->_script['text/javascript'] = preg_replace('%window\.addEvent\(\'load\',\s*function\(\)\s*{\s*new\s*JCaption\(\'img.caption\'\);\s*}\);\s*%', '', $this->_script['text/javascript']);
    if (empty($this->_script['text/javascript']))
        unset($this->_script['text/javascript']);
}

Explanation

Given that the JCaption code is contained within an element of the _script variable which we can access in the template file, we can use a regular expression to match the part of the string that contains the JCaption code, and replace it with an empty string using PHP's preg_replace function.

if (isset($this->_script['text/javascript']))

This checks if the _script['text/javascript'] variable exists. If it doesn't, then no javascript has been added, and we don't need to do anything more.

$this->_script['text/javascript'] = preg_replace('%window\.addEvent\(\'load\',\s*function\(\)\s*{\s*new\s*JCaption\(\'img.caption\'\);\s*}\);\s*%', '', $this->_script['text/javascript']);

This is the line that does all the work. It replaces the block of JCaption code as matched by the regular expression string with an empty string using preg_replace.

if (empty($this->_script['text/javascript']))
        unset($this->_script['text/javascript']);

This checks to see if there is any javascript left after we've removed the JCaption code. If not, then we unset the variable completely. This prevents the renderer from outputting an empty script tag.

Example

This results in our new Beez 20 template index.php file looking like this:

<?php
defined('_JEXEC') or die;
unset($this->_scripts[JURI::root(true).'/media/system/js/caption.js']);
if (isset($this->_script['text/javascript']))
{
    $this->_script['text/javascript'] = preg_replace('%window\.addEvent\(\'load\',\s*function\(\)\s*{\s*new\s*JCaption\(\'img.caption\'\);\s*}\);\s*%', '', $this->_script['text/javascript']);
    if (empty($this->_script['text/javascript']))
        unset($this->_script['text/javascript']);
}
$showRightColumn        = ($this->countModules('position-3') or $this->countModules('position-6') or $this->countModules('position-8'));
$showbottom                        = ($this->countModules('position-9') or $this->countModules('position-10') or $this->countModules('position-11'));
$showleft                        = ($this->countModules('position-4') or $this->countModules('position-7') or $this->countModules('position-5'));
if ($showRightColumn==0 and $showleft==0) {
        $showno = 0;
}
JHtml::_('behavior.framework', true);
$color              = $this->params->get('templatecolor');
$logo               = $this->params->get('logo');
$navposition        = $this->params->get('navposition');
$app                = JFactory::getApplication();
$doc                = JFactory::getDocument();
$templateparams     = $app->getTemplate(true)->params;
$doc->addScript($this->baseurl.'/templates/'.$this->template.'/javascript/md_stylechanger.js', 'text/javascript', true);
?>

Pros

• Unaffected by updates to Joomla! Core

Cons

• Requires code editing
• Will need to be repeated for each template file, if you are actively using more than one.

Option 2: Edit the Joomla! Core

Solution

In the file components/com_content/controller.php (on line 51 in Joomla! 2.5.1), remove this line of code:

JHtml::_('behavior.caption');

Explanation

This line of code is the culprit in adding the JCaption code in the first place. Either remove it, or comment it out by adding // to the start of the line.

Pros

• Will be applied across all templates with only one edit.

Cons

• Requires code editing.
• Will be overwritten when updating the Joomla! core, so you will need to remember to re-do it each time you update.

Option 3: InterExt

Solution

Download and install InterExt from this website. Aside from enabling the plygin itself, there is only one setting that needs to be changed to remove JCaption, and that is Remove JCaption, for which you can select either to always remove it, or only remove if MooTools has been removed.

InterExt is primarily intended to provide a more powerful tool to manage MooTools and jQuery, but it does include an option to remove the JCaption code as well. See the information on this website for more details on how to use it.

Pros

• Can be enabled/disabled in the Joomla! Admin (no code editing required).
• Unaffected by updates to Joomla! Core

Cons

• If only using InterExt to remove JCaption, and not using any of it's other features, this does come with a slightly greater performance impact than the other options.

Conclusion

While it is disappointing that Joomla! adds this JCaption code by default, with no Admin option to remove it, there are several alternative options for removing it. Which is best somewhat depends on your situation. If you don't mind minor code editing, taking option 1 and removing it using a regular expression in the template index.php file is probably the best. If you would much prefer to have the option to manage it in the Joomla! back-end, or you would like more powerful features for managing MooTools more generally, then using InterExt is probably for you.

 

If you have any questions or suggestions, please head over to the topic for this blog in the forum.

PS. If you like the code highlighting in this article, we've developed and use a Joomla! plugin that loads the excellent Syntax Highlighter, called Smart Highlighter.