Actions

Difference between revisions of "Adding JavaScript"

From Joomla! Documentation

(External JavaScript)
(add important notes)
Line 127: Line 127:
  
 
More information about Mootools is available at http://mootools.net/. For API documentation, visit http://mootools.net/docs/core.
 
More information about Mootools is available at http://mootools.net/. For API documentation, visit http://mootools.net/docs/core.
 +
 +
== Important notes for 3rd party developers ==
 +
 +
If you are creating a custom template override or extension that needs to add a custom JS file, make sure to add important dependencies such as Jquery or Mootools before your custom JS files. JS framework fiels msut be always loaded before any other files to make sure they get executed the first, otherwise other files that load before the frameworks they need are likely to end in JS exceptions.
 +
 +
Some templates like Protostar or Beez insert all the dependencies you need using functions like
 +
 +
JHtml::_('bootstrap.framework');
 +
 +
To load Jquery + Bootstrap but your should not relay in this fact on your extensions or custom templates overrides, always make sure your extension or custom override load the dependencies you need before the template does it, I will explain why later:
 +
 +
For example if you got a custom template override that need to insert a JS file with some Jquery scripts that does fancy things on all the pages where that template override is being used. In that case you should declare this on the top section of that override file:
 +
 +
JHtml::_('jquery.framework');
 +
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
 +
 +
If you are developing a 3rd party extension that you plan to put on the Joomla! extension directory you should do something like this:
 +
 +
if($params->get('add_extension_resources', false))
 +
{
 +
    JHtml::_('jquery.framework');
 +
    $doc->addScript('media/com_fancy/js/fancy-script.js');
 +
}
 +
 +
The conditional clause to decide whether to add or not the extension resources is '''strongly encouraged''' and considered a '''good practice''' because it gives flexibility to 3rd party developers who don't want to use your extension resources and use custom/modified files without having to battle with Joomla! using workarounds and hacks to be able to remove your original extensions resources in order to avoid duplicates and conflicts.
 +
 +
==== Ask me why ====
 +
 +
If you check the source code of the index.php from the Protostar template, you can see that the statements
 +
 +
JHtml::_('bootstrap.framework');
 +
 +
is added way before the statement
 +
 +
<jdoc:include type="head" />
 +
 +
this can make you think that the framework files and your 3rd party files using methods like
 +
 +
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
 +
$doc->addScript('media/com_fancy/js/fancy-script.js');
 +
 +
will be added in the right order at the right spot, '''but that is not the case''', because extension files and template override files are processed '''first''' and the index.php file of your current template is processed the '''last''', which will cause that your custom JS files get inserted before the framework files inserted from the template.
 +
 +
This happens because the Joomla API (addScript function and others )uses an array to store the JS files paths and they get rendered in the document in the same order they where inserted into that array, also once a file path is inserted on the array and another API call tries to insert the same file this action is ignored to avid duplicates, it also means that the order of the files is not altered on that array when you try to add the same JS file several times.
 +
 +
Having said that doing this
 +
 +
JHtml::_('jquery.framework');
 +
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
 +
 +
at your custom templates overrides and extension is '''required''' and does not cause harm or conflict with the call
 +
 +
JHtml::_('bootstrap.framework');
 +
 +
at your template index.php file.
 +
  
 
== See Also ==
 
== See Also ==

Revision as of 00:52, 20 July 2014