J3.x

Agregar JavaScript y CSS a la página

From Joomla! Documentation

Revision as of 10:28, 13 March 2021 by Pabloarias (talk | contribs) (Created page with "Se pueden añadir los parámetros <tt>$options</tt> y <tt>$attributes</tt> a los anterior métodos. <tt>$options</tt> controla cómo los elementos <tt><script></tt> y <tt><lin...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎中文（台灣）‎

Esta es una de las series de API Guides, con el objetivo de ayudar a entender cómo usar la API de Joomla a proveyendo explicaciones detallasdas y código de ejemplo que puedas instalar y ejecutar fácilmente.

Insertar desde un Archivo

Joomla permite añadir archivos Javascript y CSS a tu documento HTML y ubica los elementos <script> y <link> asociados en la sección de cabecera HTML <head>. Para hacer esto se llama a los métodos addScript y addStyleSheet del objeto Joomla que representa el documento HTML. Desde Joomla! se almacenan todos los datos HTML relacionados que dibujan una página antes de la salida. Es posible llamar a estos métodos en cualquier lugar de tu código.

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+). Era usual hacer esto con JHTML, sin embargo, está obsoleto en Joomla 2.5 y fue eliminado en Joomla 3.x.

Parámetros $options y $attributes

Se pueden añadir los parámetros $options y $attributes a los anterior métodos. $options controla cómo los elementos <script> y <link> salen mientras que $attributes establece los atributos HTML de estas etiquetas. (Nótese que that aunque hay marcadores obsoletos en los métodos addScript y addStyleSheet del Documento Joomla API, estos marcadores se refieren a la firma de estos métodos; el formulario de la firma usando los parámetro $options y $attributes no está obsoleto). 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.

Por ejemplo: 

$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.

Retrieved from "https://docs.joomla.org/index.php?title=J3.x:Adding_JavaScript_and_CSS_to_the_page/es&oldid=785268"