J3.x

Agregar JavaScript y CSS a la página

From Joomla! Documentation

This page is a translated version of the page J3.x:Adding JavaScript and CSS to the page and the translation is 42% complete.

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎中文(台灣)‎

This is one of a series of API Guides, which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

Insertar desde un Archivo

Joomla allows you to add Javascript and CSS files to your HTML document, and it puts the associated <script> and <link> elements within the HTML <head> section. To do this you call the addScript and addStyleSheet methods of the Joomla object which represents the HTML document. Since Joomla! buffers all the HTML-related data that makes up a page before output, it is possible to call these methods anywhere within your code.

En primer lugar, obtener una referencia al objeto del documento actual:

use Joomla\CMS\Factory;
$document = Factory::getDocument();
// above 2 lines are equivalent to the older form: $document = JFactory::getDocument();

Luego para una hoja de estilos, usa este código:

$document->addStyleSheet($url);

Para agregar un archivo Javascript, utiliza este código:

$document->addScript($url);

donde $url es la variable que contiene la ruta de acceso completa al archivo javascript o CSS por ejemplo:
JUri::base() . 'templates/custom/js/sample.js'

Nota esto **NO** incluye Mootools o jQuery. Si el código requiere Mootools o jQuery mira Frameworks Javascript para más información sobre cómo incluirlos (nota jQuery sólo puede ser incluido de forma nativa en Joomla! 3.0+).

Esta es una opción mucho menos flexible. Sin embargo, es más eficiente para un gran número de escenarios tales como la inclusión de una hoja de estilos en una plantilla. Por supuesto, también tendrás que agregar manualmente el código de algunos de los pasos que se haría de forma automática utilizando el método JHtml siguiente.

$options and $attributes Parameters

You can add $options and $attributes parameters to the above methods. The $options control overall how the <script> and <link> elements are output while the $attributes get set as HTML attributes within those tags. (Note that although there are Deprecated markers against the addScript and addStyleSheet methods of the Joomla Document API, these markers refer just to the signature of these methods; the form of the signature using $options and $attributes parameters is not deprecated). The $options parameter should be an array, and 2 different options are currently supported:

  • 'version' => 'auto' If this is set then a "media version" is appended as a query parameter to the CSS or JS URL within the <script> or <link> element. This is a string (an md5 hash) which is generated from factors including the Joomla version, your Joomla instance secret and the date/time at which the media version was generated. The media version is regenerated whenever anything is installed on the Joomla instance, and its purpose is to force browsers to then reload the CSS and JS files instead of using possibly outdated versions from cache.

For example

$document->addStyleSheet("...demo.css", array('version'=>'auto'));
// leads to something like
// <link href="...demo.css?37e343bbb4073e0dfe5b1eb40b6" rel="stylesheet">

The string of characters after the ? is the md5 hash, which will change when extensions or Joomla itself are installed/upgraded/deinstalled.

  • 'conditional' => 'lt IE 9' (as an example). This outputs the <script> or <link> within a Conditional Comment which earlier versions of Internet Explorer interpreted.

For example

$document->addScript("...demo.js", array('conditional'=>'lt IE 9'));
// leads to
// <!--[if lt IE 9]><script src="...demo.js"></script><![endif]-->

The $attributes parameter should also be an array, and these are mapped to be html attributes of the <script> or <link> element. For example,

$document->addScript("...demo.js", array(), array('async'=>'async'));
// leads to
// <script src="...demo.js" async></script>

Agregar opciones a tu código JavaScript

Joomla! 
≥ 3.7
Solo disponible en Joomla! 3.7 y superior

(Note that these Options are different from the $options parameter described above).

Además de agregar scripts, Joomla! ofrece un mecanismo para almacenar las opciones en "optionsStorage". Esto permite administrar las opciones existentes en el lasdo del servidor y en el cliente. Esto permite ubicar toda la lógica de JavaScript en el archivo JavaScript, el cual se agrega al caché del navegador.

Joomla! utiliza un mecanismo especial para aplicar "lazy loading" en las opciones del lado cliente. No utiliza JavaScript inline, lo cual es mejor para la velocidad de renderización de la página, y hace el sitio web más amigable para un verificador de velocidad (ej. Google).

Es mejor usar "optionsStorage" que JavaScript inline para agregar las opciones del script.

"'Ejemplo de uso"'

Agregar las opciones del script a tu módulo:

$document = JFactory::getDocument();
$document->addScriptOptions('mod_example', array(
    'colors' => array('selector' => 'body', 'color' => 'orange'),
    'sliderOptions' => array('selector' => '.my-slider', 'timeout' => 300, 'fx' => 'fade')
));

Acceso a tus opciones en el lado del cliente:

var myOptions = Joomla.getOptions('mod_example');
console.log(myOptions.colors); // Print your options in the browser console.
console.log(myOptions.sliderOptions);

Sobreescribir las opciones en el lado servidor (lo cual es posible hasta la renderización del "head"):

$document  = JFactory::getDocument();
// Get existing options
$myOptions = $document->getScriptOptions('mod_example');
// Change the value
$myOptions['colors'] = array('selector' => 'body', 'color' => 'green');
// Set new options
$document->addScriptOptions('mod_example', $myOptions);

Passing language strings to Javascript

There are cases when you may want to output an error message in your JavaScript code and want to use the Joomla mechanism of language strings. You could manage this by using addScriptOptions to pass down each language string you need, but Joomla provides a more succint solution. To pass a language string to JavaScript do in your PHP code, for example,

JText::script('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'); Then in your JavaScript code you can do:

var message = Joomla.JText._('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'); to obtain in the user's language the text message associated with the language constant. Obviously certain language strings have embedded %s characters, so in your JavaScript code you will have to handle that, eg using an external JavaScript sprintf library or string replace, etc.

Insertar secuencias de comandos en línea desde dentro de un archivo PHP

Si Javascript o CSS se generan usando PHP, puedes agregar la secuencia de comandos o la hoja de estilos directamente en la cabeza de tu documento:

$document = JFactory::getDocument();

// Add Javascript
$document->addScriptDeclaration('
    window.event("domready", function() {
        alert("An inline JavaScript Declaration");
    });
');

// Add styles
$style = 'body {'
        . 'background: #00ff00;'
        . 'color: rgb(0,0,255);'
        . '}'; 
$document->addStyleDeclaration($style);

Ejemplo de Javascript

Por ejemplo, el siguiente código se utiliza para definir un texto de ayuda emergente personalizado que toma ventaja de mootools.

For example, the following code is used to define a custom tool tip that takes advantage of Mootools.

function getToolTipJS($toolTipVarName, $toolTipClassName){
    $javascript = 'window.addEvent(\"domready\", function(){' ."\n";
    $javascript .= "\t"  .'var $toolTipVarName = new Tips($$("' . $toolTipVarName .'"), {' ."\n";
    $javascript .= "\t\t"   .'className: "' .$toolTipClassName .'",' ."\n";
    $javascript .= "\t\t"   .'initialize: function(){' ."\n";
    $javascript .= "\t\t\t"    .'this.fx = new Fx.Style(this.toolTip, "opacity", {duration: 500, wait: false}).set(0);' ."\n";
    $javascript .= "\t\t"   .'},' ."\n";
    $javascript .= "\t\t"   .'onShow: function(toolTip){' ."\n";
    $javascript .= "\t\t\t"    .'this.fx.start(1);' ."\n";
    $javascript .= "\t\t"   .'},' ."\n";
    $javascript .= "\t\t"   .'onHide: function(toolTip) {' ."\n";
    $javascript .= "\t\t\t"    .'this.fx.start(0);' ."\n";
    $javascript .= "\t\t"   .'}' ."\n";
    $javascript .= "\t"  .'});' ."\n";
    $javascript .= '});' ."\n\n";
    return $javascript;
}

$document = JFactory::getDocument();
$document->addStyleSheet("/joomla/components/com_mycustomcomponent/css/mytooltip.css",'text/css',"screen");
$document->addScriptDeclaration(getToolTipJS("mytool","MyToolTip"));

Ten en cuenta que para que este Javascript sea funcionalmente útil, sería necesario incluir el nombre de clase apropiado en el archivo HTML, así como proporcionar el archivo mytooltip.css. Ambos están fuera del alcance de este artículo.

Ejemplos de CSS

Esto también es útil si tu insertas un campo de formulario de CSS en el código. Por ejemplo, en un módulo, puedes ser que desees que un usuario pueda elegir el color del borde. Después de llamar al avlro de los campos de formulario y asignarlo a una variable $bordercolor en mod_example.php. A continuación, en tmpl/default.php se puede incluir lo siguientes:

$document = JFactory::getDocument();
$document->addStyleSheet('mod_example/mod_example.css');
$style = '#example {
	border-color:#' . $bordercolor . ';
	}';
$document->addStyleDeclaration( $style );

Aquí mod_example.css contiene el archivo CSS de cualquier no-parámetro base de estilos. A continuación, el parámetro bordercolor/campo de formulario se agrega por separado.

Agregar Etiqueta Personalizada

Habrá algunas ocasiones en las que incluso estas funciones no son lo suficientemente flexibles, ya que están limitadas a escribir el contenido de las etiquetas <script /> o <style />, y no se puede agregar nada fuera de esas etiquetas. Un ejemplo sería la inclusión de un enlace a hojas de estilos dentro de los comentarios condicionales, que son recogidos únicamente por Internet Explorer 6 y anteriores. Para hacer esto, usa $document->addCustomTag:

$stylelink = '<!--[if lte IE 6]>' ."\n";
$stylelink .= '<link rel="stylesheet" href="../css/IEonly.css" />' ."\n";
$stylelink .= '<![endif]-->' ."\n";

$document = JFactory::getDocument();
$document->addCustomTag($stylelink);

If it was necessary to include other conditional CSS, always include the "addCustomTag" method after it is declared.

Sample Module Code

Below is the code for a simple Joomla module which you can install and run to demonstrate adding CSS and JavaScript, and can adapt to experiment with the concepts above. If you are unsure about development and installing a Joomla module then following the tutorial at Creating a simple module will help. In a folder mod_css_js_demo create the following 4 files:

mod_css_js_demo.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
    <name>css js demo</name>
    <version>1.0.1</version>
    <description>Code for including JS and CSS links</description>
    <files>
        <filename module="mod_css_js_demo">mod_css_js_demo.php</filename>
		<filename>demo.css</filename>
		<filename>demo.js</filename>
    </files>
</extension>

mod_css_js_demo.php

<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Factory;

$document = Factory::getDocument();

$options = array("version" => "auto");
$attributes = array("defer" => "defer");
$document->addScript(JURI::root() . "modules/mod_css_js_demo/demo.js", $options, $attributes);
$document->addStyleSheet(JURI::root() . "modules/mod_css_js_demo/demo.css", $options);

$document->addScriptOptions('my_vars', array('id' => "css-js-demo-id2"));

JText::script('JLIB_HTML_EDIT_MENU_ITEM_ID');

echo '<h1 id="css-js-demo-id1">Hello World!</h3>';
echo '<button id="css-js-demo-id2">Click here!</button>';

demo.css

#css-js-demo-id1 {
color: red;
}

demo.js

jQuery(document).ready(function() {
    
	const params = Joomla.getOptions('my_vars');
	console.log(params);
	console.log("JS language constant: " + Joomla.JText._('JLIB_HTML_EDIT_MENU_ITEM_ID'));
	
	var message = Joomla.JText._('JLIB_HTML_EDIT_MENU_ITEM_ID');
	message = message.replace("%s", params.id);
	document.getElementById(params.id).addEventListener("click", function() {alert(message);}); 
});

Zip up the mod_css_js_demo directory to create mod_css_js_demo.zip. Within your Joomla administrator go to Install Extensions and via the Upload Package File tab select this zip file to install this sample mod_css_js_demo module. Make this module visible by editing it (click on it within the Modules page) then:

  1. making its status Published
  2. selecting a position on the page for it to be shown
  3. on the menu assignment tab specify the pages it should appear on

When you visit a site web page then you should see the module in your selected position, and it should display

  • a message Hello World! which the CSS file should change to display in red
  • a button which when you click it will execute an alert() showing the language string and variable which were passed down from the PHP code.

Using your browser's development tools you can also view the <script> and <link> elements within the HTML and see the JavaScript output on the console.