Actions

Adding JavaScript

From Joomla! Documentation

Revision as of 07:09, 17 September 2012 by Haydenyoung (Talk | contribs)

Quill icon.png
Page Actively Being Edited!

This article is actively undergoing a major edit for a short while.
As a courtesy, please do not edit this page while this message is displayed. The user who added this notice will be listed in the page history. This message is intended to help reduce edit conflicts; please remove it between editing sessions to allow others to edit the page. If this page has not been edited for several hours, please remove this template, or replace it with {{underconstruction}} or {{incomplete}}.

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