Actions

Difference between revisions of "Adding JavaScript"

From Joomla! Documentation

(Usage introduction.)
m (Keep spelling of JavaScript same throughout document.)
Line 1: Line 1:
 
{{cookiejar}}
 
{{cookiejar}}
  
Javascript (also known as ECMAScript) is a scripting language 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.
+
JavaScript (also known as ECMAScript) is a scripting language 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.
+
There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.
  
 
==Usage==
 
==Usage==
Line 9: Line 9:
 
There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).  
 
There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).  
  
===Inline Javascript===
+
===Inline JavaScript===
  
Blocks of Javascript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:
+
Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:
  
 
<source lang="php">
 
<source lang="php">
Line 18: Line 18:
 
$document->addScriptDeclaration('
 
$document->addScriptDeclaration('
 
     window.event("domready", function() {
 
     window.event("domready", function() {
         alert("An inline Javascript Declaration");
+
         alert("An inline JavaScript Declaration");
 
     });
 
     });
 
');
 
');
Line 24: Line 24:
 
</source>
 
</source>
  
===External Javascript===
+
===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.
+
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 [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:
+
There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:
  
 
<source lang="php">
 
<source lang="php">
Line 47: Line 47:
  
 
==Description==
 
==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed Javascript into Joomla's index.php via the jdoc head tag:
+
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:
  
 
<source lang="html4strict">
 
<source lang="html4strict">
Line 53: Line 53:
 
</source>
 
</source>
  
Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed Javascript includes would result in the index.php rendering the following HTML:
+
Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:
  
 
<source lang="html4strict">
 
<source lang="html4strict">
 
<head>
 
<head>
 
...
 
...
<script type="text/javascript" src="/media/system/js/sample.js"></script>
+
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
 
...
 
...
 
</head>
 
</head>
Line 68: Line 68:
 
<head>
 
<head>
 
...
 
...
<script type="text/javascript">
+
<script type="text/javaScript">
 
window.addEvent("domready", function() {
 
window.addEvent("domready", function() {
 
     alert("Embedded block of JS here");
 
     alert("Embedded block of JS here");
Line 77: Line 77:
 
</source>
 
</source>
  
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).
+
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. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>
 
'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

Revision as of 17:55, 17 September 2012

JavaScript (also known as ECMAScript) is a scripting language 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

There are three methods for embedding JavaScript into your code using the Joomla API; JDocument::addScriptDeclaration, JDocument::addScript and script. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

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