Joomla! Documentation™

Cambio en la API

Insertar desde un Archivo

Para tener un documento HTML bien formateado, debes poner todas las referencias a los archivos Javascript y CSS dentro de la porción <head>. Ya que Joomla! genera todo el código HTML que tiene una página antes de la salida, es posible añadir estas referencias dentro de las etiquetas <head> desde la extensión. La forma más sencilla de hacer esto es hacer uso de la funcionalidad integrada en Joomla!.

JDocument

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.

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

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

JHtml

JHtml ofrece mucha más flexibilidad que JDocument, mientras que utilizan la misma base de funcionalidad - de hecho, al final del camino se llama a JHtml JFactory::getDocument()->addStyleSheet() o JFactory::getDocument()->addScript().

Si sólo deseas incluir una ruta directa al archivo, en una plantilla por ejemplo, entonces es mejor usar JDocument. Sin embargo, si deseas tomar en cuenta que la depuración está habilitada para incluir un comprimido de secuencia de comandos o tomar ventaja de la plantilla con scripts y hojas de estilo reemplazables, a continuación, generalmente es mejor utilizar JHtml. Se recomienda a todos los Desarrolladores de 3ª Parte usar JHtml, para permitir sobrescribir su CSS y javascript de la plantilla por parte de los diseñadores de plantillas.

JHtml::script

La siguiente es la firma de esta función, puedes ver más en JHtml::script en api.joomla.org:

script(string $file, boolean $framework = false, boolean $relative = false, boolean $path_only = false, boolean $detect_browser = true, boolean $detect_debug = true) : mixed

El uso de JHtml para incluir un archivo javascript puede traer varios beneficios. El primero de ellos es que si el archivo javascript tiene una dependencia a mootools, a continuación, se puede incluir automáticamente mediante la configuración del segundo parámetro de este método, de la siguiente forma:

<?php
JHtml::script(JUri::base() . 'templates/custom/js/sample.js', true);
?>

El tercer parámetro de este método permite plantillas y archivos javascript reemplazables para permitir una mayor personalización de las extensiones. El primer parámetro ahora asume que estás comenzando en la carpeta JPATH_BASE/media - dentro de aquí puedes especificar el nombre de tu extensión, seguido por el nombre de tu archivo javascript. La ruta buscada es entonces JPATH_BASE/media/com_search/js/search.js para el siguiente fragmento de código JHtml.

<?php
JHtml::script('com_search/search.js', false, true);
?>

Nota el subdirectorio js que se busca dentro del directorio com_search no debe ser especificado en el método JHtml.

Sin embargo, en la parte superior de este si existe un archivo en js/com_search/search.js entonces esto va a ser incluidos en su lugar. Por ejemplo, digamos que una extensión tiene uan dependencia de mootools, pero el usuario sólo quiere qeu se cargue jQuery. Esto significa que un usuario podría reemplazar el archivo con la versión de jQuery.

De forma predeterminada, Joomla! incluirá automáticamente una versión comprimida y sin comprimir de los scripts dependiendo de si el modo de depuración está habilitado o no. Llama a tu script comprimido search.min.js y a la versión sin comprimir script-uncompressed.js o script.js para utilizar esta funcionalidad y la ayuda a la depuración de los scripts. Debes llamar a la función con la versión comprimida, como sigue:

<?php
JHtml::script('com_search/search.min.js');
?>

Además puedes incluir explorar archivos específicos. Joomla! puede buscar archivos de los siguientes tipos

• nombre_de_archivo.ext
• nombre_de_archivo_browser.ext
• nombre_de_archivo_browser_major.ext
• nombre_de_archivo_browser_major_minor.ext

Esto puede permitir incluir archivos específicos de internet explorer 6, por ejemplo. Por tener un search.js para uso general con una search_msie_6.js para un archivo adicional con las correcciones de internet explorer 6.

JHtml::stylesheet

La siguiente es la firma de esta función, puedes ver más en JHtml::stylesheet en api.joomla.org:

El uso de JHtml para incluir un archivo CSS puede traer varios beneficios. El primero de ellos es que permite plantillas con archivos CSS reemplazables, para permitir una mayor personalización de las extensiones. Ajusta el tercer parámetro a true, ahora se supone que estás comenzando en la carpeta JPATH_BASE/media dentro de aquí puedes especificar el nombre de tu extensión, seguido por el nombre de tu archivo CSS. La ruta buscada es entonces JPATH_BASE/media/com_search/css/búsqueda.css para el siguiente fragmento de código JHtml.

<?php
JHtml::stylesheet('com_search/search.css', array(), true);
?>

Nota el subdirectorio css que se busca dentro del directorio com_search no debe ser especificado en el método JHtml.

Sin embargo, en la parte superior de este si existe un archivo en css/com_search/search.css entonces este va a ser incluidos en su lugar. Esto permite a las personas personalizar la apariencia de una extensión para adaptarse mejor al estilo de sus plantillas.

Además puedes incluir explorar archivos específicos. Joomla! puede buscar archivos de los siguientes tipos

• nombre_de_archivo.ext
• nombre_de_archivo_browser.ext
• nombre_de_archivo_browser_major.ext
• nombre_de_archivo_browser_major_minor.ext

Esto puede permitir incluir archivos específicos de internet explorer 6, por ejemplo. Por tener un search.js para uso general con una search_msie_6.js para un archivo adicional con las correcciones de internet explorer 6.

Del mismo modo como con JHtml::script, si $detect_debug es verdadero y pasas una hoja de estilo minimizada ejemplo.min.css, cuando el modo de depuración está activado, la hoja no minimizada, si es que existe, será usada en su lugar.

Agregar opciones a tu código JavaScript

Joomla! 

≥ 3.7

Solo disponible en Joomla! 3.7 y superior

Beside adding inline scripts, Joomla! provide mechanism to store the options in the "optionsStorage". This is allowed to nicely manage an existing options on the server side and on the client side. And allow to place all JavaScript logic to the JavaScript file, that will be cached by browser.

Joomla! use special mechanism for "lazy loading" the options on the client side. It do not use inline JavaScript, that is good for page rendering speed, and make your site more friendly for the Speed Tester (eg Google).

Thus use "optionsStorage" preferred, than use inline JavaScript to add the script options.

"'Ejemplo de uso"'

Agregar las opciones del script a tu módulo:

$document = JFactory::getDocument();
$document->addScriptOptions('mod_example',
    '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 in the browser console your options
console.log(myOptions.sliderOptions);

Override the options on server side (possible until the head rendering):

$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);

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.

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', array(), true);
$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);