Agregar JavaScript
From Joomla! Documentation
Note that a more up-to-date Joomla document covering this topic can be found at Adding JavaScript and CSS to the page, although it currently doesn't cover the more advanced topics at the bottom of this page.
JavaScript (también conocido como ECMAScript) es un lenguaje de secuencias de comandos utilizado principalmente en el lado del cliente, desarrollado para ampliar y mejorar la experiencia del usuario final de un sitio web. Joomla! proporciona a los desarrolladores mecanismos de uso-fácil para incluir JavaScript en sus extensiones utilizando los métodos API. Hay varios métodos para incluir JavaScript en tus extensiones de Joomla!; algunos de los cuales se describen a continuación.
Uso
Hay tres métodos para incluir JavaScript en tu código usando el API de Joomla!; JDocument::addScriptDeclaration, JDocument::addScript y script. Estos métodos deben ser llamados en la clase de Vista de tu componente <tucomponente>/views/<tuvista>/view.html.php o la plantilla de secuencia de comandos <tucomponente>/views/<tuvista>/tmpl/<tuplantilla>.php o en el caso de un módulo, en tu plantilla de secuencia de comandos <tumodulo>/tmpl/<tuplantilla>.php.
JavaScript en línea
Los bloques de código JavaScript puede ser declarado directamente dentro de la plantilla de pantalla de un componente o módulo mediante el método addScriptDeclaration de la clase JDocument :
<?php
$document = JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>JavaScript Externos
Alternativamente, puedes desear tener tu código JavaScript en un archivo separado. La separación de tu JavaScript en un archivo externo puede hacer que tu código de la plantilla sea más fácil de leer, especialmente si el JavaScript es largo o complicado.
Hay dos formas de integrar un archivo JavaScript usando el API de Joomla!. La primera consiste en el uso del método addScript de la clase JDocument:
<?php
$document = JFactory::getDocument();
$document->addScript('/media/system/js/sample.js');
?>La segunda utiliza el método script de la clase JHTML:
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>El API ha cambiado en 3.x, por lo que el segundo parámetro no puede ser una cadena. Si realmente necesitas utilizar este método, debes incluir el vínculo absoluto a tu archivo JavaScript:
<?php
JHtml::script(Juri::base() . 'templates/custom/js/sample.js');
?>You can use options in a third parameter. This example shows the options version and relative . The file example should be saved in the folder media/com_example/js/example.min.js. So you do NOT need to insert the js in the path you insert as second parameter.
<?php
JHtml::_('script', 'com_example/example.min.js', array('version' => 'auto', 'relative' => true));
?>Descripción
Los métodos del API de Joomla!, JDocument::addScriptDeclaration, JDocument::addScript y script integran el código JavaScript dentro del index.php de Joomla! a través de la etiqueta jdoc del head:
<jdoc:include type="head"/>El uso de los métodos JDocument::addScript o script para integrar JavaScript daría como resultado el código HTML del index.php representado a continuación:
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>Llamar al método de la clase JDocument::addScriptDeclaration daría el siguiente código HTML:
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>El uso de estos métodos es muy recomendable ya que claramente diferencia el lenguaje de secuencia de comandos (JavaScript) del código PHP principal, lo que asegura a todos que JavaScript esté correctamente integrado entre las etiquetas <head></head> y en el caso de JDocument::addScript y JHTML::script asegura que un archivo JavaScript se integra sólo una vez (Por ej.:. no hay archivos .js duplicados).
El uso de un Framework JavaScript
Un framework Javascript proporciona a los desarrolladores funcionalidades genéricas para el manejo de varias tareas de codificación de una manera familiar, consistente e independiente de la plataforma. Un framework permite a los desarrolladores olvidarse acerca de las complejidades de la implementación de una función determinada en distintos navegadores web y se centran en los requisitos del software.
Dos frameworks de Javascript se proporcionan como parte de Joomla 3.x; jQuery y Mootools. jQuery es un framework recién introducido que integra Joomla! con el nuevo framework Bootstrap HTML; Mootools es el legado de la biblioteca Javascript de Joomla! que ahora es reemplazada por jQuery y se incluye por compatibilidad con extensiones de 3as partes.
En casi todos los casos, debes utilizar un framework Javascript para el desarrollo de tus extensiones o plantillas e integrarlas es muy sencillo con el API de Joomla!.
Joomla 3.x jQuery
Por favor, consulta la guía en Frameworks de Javascript en Joomla 3.x para obtener información acerca de la inclusión de un framework en Joomla 3.x
Joomla 1.5/2.5 Mootools
A menos que estés manteniendo código Javascript que aprovecha Mootools o estás desarrollando una extensión para Joomla 2.5 o anterior se recomienda el uso de jQuery.
En primer lugar, tendrás que incluir el código de Mootools en tu extensión. Para incluir el framework Mootools en tu extensión, agrega el código siguiente a tus archivo view.html.php o tmpl:
PARA JOOMLA 1.5
JHTML::_('behavior.mootools');PARA JOOMLA 2.5
JHtml::_('behavior.framework');Con el código anterior, se obtiene el mismo resultado, en forma similar a una declaración el framework jQuery; asegura que Mootools se incluye correctamente y sólo una vez.
A continuación, el uso de Mootools es casi idéntico a la de jQuery:
JFactory::getDocument()->addScriptDeclaration('
window.addEvent("domready", function() {
alert($("list").getElements("li").length);
});
');Más información acerca de Mootools está disponible en http://mootools.net/. Para la documentación de la API, visita http://mootools.net/docs/core.
Notas importantes para los desarrolladores de 3as parte
Si va a crear o modificar una plantilla personalizada o extensión que necesita integrar un archivo JS personalizado, asegúrate de agregar las dependencias importantes tales como Jquery o Mootools antes de tus archivos JS personalizados. Los archivos del framework JS, siempre deben ser cargados antes que cualquier otro archivo para asegurarte de que se ejecutan primero, de lo contrario otros archivos que se cargan antes que los frameworks y que los necesitan, probablemente terminen en excepciones JS.
Algunas plantillas como Protostar o Beez integran todas las dependencias que necesita al usar funciones como
JHtml::_('bootstrap.framework');
para cargar Jquery + Bootstrap, pero no debes confiar en este hecho ya que en tus extensiones o plantillas personalizadas se sobrescriben. Siempre asegúrate que tu extensión o modificación personalizada carga las dependencias que necesitas antes que la plantilla las necesite, voy a explicar por qué a continuación:
Por ejemplo, si tienes una plantilla personalizada modificada que necesita integrar un archivo JS con algunos scripts de Jquery que hace cosas de fantasía (fancy-script.js) en todas las páginas en las que la plantilla modificada está siendo utilizada. En ese caso, debes declarar en la parte superior de la sección de archivo modificado:
JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
Si estás desarrollando una extensión de 3ª parte que vas a poner en el directorio de extensiones de Joomla! debes hacer algo como esto:
if($params->get('add_extension_resources', false))
{
JHtml::_('jquery.framework');
$doc->addScript('media/com_fancy/js/fancy-script.js');
}
La cláusula condicional para decidir si agregar o no los recursos de la extensión es fuertemente alentado y se considera una buena práctica, porque le da flexibilidad a los desarrolladores de 3as partes, que no quieren usar los recursos de la extensión y usar archivos personalizado/modificados sin tener que luchar con Joomla! usando soluciones y hacks para ser capaz de eliminar los recursos originales de las extensiones con el fin de evitar duplicidades y conflictos.
Explicación
Si compruebas el código fuente del index.php de la plantilla Protostar, puedes ver que las declaraciones
JHtml::_('bootstrap.framework');
se agregan antes que la declaración de
<jdoc:include type="head" />
esto puede hacer pensar que los archivos del framework y de la 3ª parte que usan métodos como
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
$doc->addScript('media/com_fancy/js/fancy-script.js');
se agregan en el orden correcto en el lugar correcto, pero ese no es el caso, porque los archivos la extensión y la plantilla reemplazan los archivos que son procesados primero y el archivo index.php de la plantilla actual se procesa último. Esto hará que tus archivos JS personalizados se integren en primer lugar y los archivos del framework de la plantilla se integren después.
Esto sucede debido a que la API de Joomla! (como $doc->addScript) utiliza un array para almacenar las rutas de lo archivos JS y llegan al documento en el mismo orden en que fueron insertados en el array (pila FIFO, el que entra primero sale último). También, una vez que la ruta de acceso del archivo se inserta en el array y otra llamada a la API intenta insertar el mismo archivo esta acción se omite para evitar duplicados. También significa que el orden de los archivos no se ve alterada cuando los mismos archivos se intentó insertar en varias ocasiones.
Después de lo dicho, haremos esto
JHtml::_('jquery.framework');
$doc->addScript('templates/'.$this->template.'/js/fancy-script.js');
en las plantillas personalizadas modificadas y extensiones, es requerido y no causa daño o conflicto con la llamada
JHtml::_('bootstrap.framework');
en el archivo index.php de tu plantilla.
Enlaces Externos
https://api.joomla.org/cms-2.5/classes/JHtmlBehavior.html#method_framework
https://api.joomla.org/cms-3/classes/JHtmlBehavior.html#method_framework
http://en.wikipedia.org/wiki/JavaScript