Actions

Difference between revisions of "Adding JavaScript"

From Joomla! Documentation

m
m
Line 1: Line 1:
{{inuse}}
 
 
{{cookiejar}}
 
{{cookiejar}}
  

Revision as of 08:10, 17 September 2012

Javascript (also known as ECMAScript) is a scripting language and is primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include Javascript in their extensions using existing API methods.

There are a number of methods for including Javascript in your Joomla extensions; some of these are described below.

Contents

Usage

Inline Javascript

Blocks of Javascript code can be declared directly within a component or module's display template using the JDocument class' addScriptDeclaration method:

<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
    window.event("domready", function() {
        alert("An inline Javascript Declaration");
    });
');
?>

External Javascript

Alternatively, you may wish to separate your Javascript into a separate file. Separating your Javascript into an external file can make your template code easier to read especially if the Javascript is lengthy or complex.

There are two ways to include a Javascript file using the Joomla API. The first involves using the JDocument class' addScript method:

<?php
$document = &JFactory::getDocument();
$document->addScript('/media/system/js/sample.js');
?>

The second uses the JHTML class' script method:

<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>

Description

The Joomla API's JDocument::addScriptDeclaration, JDocument::addScript and script methods embed Javascript into Joomla's index.php via the jdoc head tag:

<jdoc:include type="head"/>

Using the JDocument::addScript or script methods to embed Javascript includes would result in the index.php rendering the following HTML:

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

Calling the class method JDocument::addScriptDeclaration would render the following HTML:

<head>
...
<script type="text/javascript">
window.addEvent("domready", function() {
    alert("Embedded block of JS here");
});
</script>
...
</head>

Using these methods is highly recommended as it clearly differentiates another scripting language (Javascript) from the main PHP code, ensures all Javascript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a Javascript file is included only once (I.e. there is no .js file duplication).

Please Note: Joomla 1.6+ may handle MooTools differently than in previous versions. [1]

References

  1. Whitepaper Upgrade to mootools 1.2