I developed a module recently that required certain JS and CSS files to be injected into the <head> of each page. Initially, I used:

$doc =& JFactory::getDocument();

However, I noticed that when caching was enabled the site loaded both a cached version from /cache and non-cached version from /modules/mod_x/js/, causing JS errors.

When I changed this to:


The script was loaded only once, from cache, resolving these errors.

I read in the docs that the addScript method was more 'low level' than the JHtml:script method, but beyond saying that...

Of course, you will also need to manually code some of the steps [that JHtml:script does for you] that would be done automatically using the [JHtml:script method] above [if you use addScript].

...no further detail is given.

So what's the difference? I assume JHtml:script eventually calls addScript on a document object at some point, but are other intermediary steps taken first?

  • 4
    I've rewritten the joomla docs a bit to try and update it - see if it makes more sense now? Apr 25, 2014 at 22:08
  • 1
    @GeorgeWilson The Joomla docs have really improved recently. Thanks :)
    – TryHarder
    Jul 4, 2014 at 11:35
  • Related question about stylesheets: joomla.stackexchange.com/q/10062/5239
    – Flimm
    Jun 18, 2015 at 16:33

2 Answers 2


JHtml::script has additional logic included. See http://api.joomla.org/cms-3/classes/JHtml.html#method_script for the API reference

By default it will detect debug setting and browser used and load the matching script. For example when debug is enabled it will load an uncompressed version of the file if present.

There are optional settings which allow to override the file on a template level and other things.

Michael Babker wrote a good guide how to use JHtml::script() to allow overrides: http://www.babdev.com/blog/139-use-the-media-folder-allow-overridable-media

Function in repo for reference: https://github.com/joomla/joomla-cms/blob/staging/libraries/cms/html/html.php#L659

Official doc page which is now updated by George: http://docs.joomla.org/J3.3:Adding_JavaScript_and_CSS_to_the_page

  • 2
    thanks for the answer. The API reference is fairly terse - is there a more comprehensive explanation of the effects of detect_browser and detect_debug, and when you say 'optional settings' and 'other things' are these documented anywhere? Apr 25, 2014 at 15:02
  • I've added a link to an article by Michael which explains the override part. As for the debug and browser part, I don't think there is a documentation. You would have to read the code for that.
    – Bakual
    Apr 25, 2014 at 15:53
  • 1
    So if there is a uncompressed and compressed js file for example and debug is on then it will load filename-uncompressed.js and just filename.js when debug is off. For the browser when debug off it looks for filename-browser.js then filename-browser-browserversion.js etc. Apr 25, 2014 at 18:02
  • 2
    This is a cracking answer - thanks @Bakual and @GeorgeWilson! Apr 30, 2014 at 19:13
  • 1
    Don't forget that that JHtml also can append the MD5sum of a script or stylesheet to cache-bust.
    – Flimm
    May 26, 2015 at 14:00

in two words:

  • JHtml::script() - allow you to override the specific script (except that already attached to JDocument), depend from some factors (see @Bakual answer);
  • $doc->addScript() - attach script directly to the document, without checking an overrides;

If you are the extension developer, then highly recommended use JHtml::script() when you add the script. This will allow for your users override some specific scripts, depend from what they want.
Also there similar method for css.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.