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? – George Wilson Apr 25 '14 at 22:08
  • 1
    @GeorgeWilson The Joomla docs have really improved recently. Thanks :) – TryHarder Jul 4 '14 at 11:35
  • Related question about stylesheets: joomla.stackexchange.com/q/10062/5239 – Flimm Jun 18 '15 at 16:33

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

| improve this answer | |
  • 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? – codinghands Apr 25 '14 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 '14 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. – George Wilson Apr 25 '14 at 18:02
  • 2
    This is a cracking answer - thanks @Bakual and @GeorgeWilson! – codinghands Apr 30 '14 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 '15 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.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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