Temas avanzados

From Joomla! Documentation

This page is a translated version of the page Advanced topics and the translation is 100% complete.

Other languages:
български • ‎বাংলা • ‎Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎हिन्दी • ‎Nederlands
Joomla! 
2.5 & 3.x
series

¿Cómo se ejecutan las plantillas?

Las plantillas son ejecutadas en un proceso de 2 fases, que hace un uso completo del intérprete de PHP, para proporcionar un grado considerable de flexibilidad y rendimiento para el diseñador de la plantilla. Las plantillas se ejecutan en el contexto del objeto documento, por lo que el objeto $this es siempre la creación de instanciaa de la clase JDocument.

Antes que la plantilla comience la ejecución, el componente se ha ejecutado y su salida esta en el búfer para su uso posterior.

Ejecución de una plantilla se realiza de la siguiente manera:

  • se cargan los parámetros de la plantilla (si existe).
  • se carga el idioma de la plantilla (si alguno).
  • si el modo legacy está a continuación de las variables de configuración se copian como globales.
  • el archivo de plantilla (index.php) es cargado y ejecutado (por PHP). La salida se almacena en el búfer. Esta es la fase 1 de las 2 fases del proceso. Todo lo que este entre las etiquetas <?php y ?> es ejecutado como código PHP. Todo lo que esté fuera de estas etiquetas es la salida, pero de lo contrario se omite. Como el resultado se almacena en búfer, nada se envía al explorador web del cliente en esta etapa.
  • un archivo favicon.ico se busca, primero en el directorio raíz de Joomla!, a continuación, en el directorio raíz de la plantilla. El último reemplazará al anterior si se encuentra.
  • los resultados que se han almacenado en la fase 1 ahora son analizado por los elementos <jdoc:include>. Esta es la fase 2 del proceso. Para cada elemento jdoc que se encuentra, el procesador adecuado de la clase se carga y se llama su método render. La salida desde el método render sustituye a la <jdoc:include> del mismo elemento en el buffer de salida. En el caso de clases de procesador del módulo esto desencadena la ejecución de los módulos y el almacenamiento en el búfer de su salida.
  • Ciertos encabezados HTTP específicos de la plantilla se agregan a la lista de encabezados de la salida.
  • El control se pasa, entonces, al objeto JApplication, el cual se encargará del resto del proceso de obtención de la ahora renderizada página web de espaldas al navegador web.


Páginas de error del sistema

Página de error de plantillas

Joomla!, por defecto, utiliza plantillas especiales cuando se van a plantear una respuesta de error. Estos se encuentran en el directorio templates/system. Para los códigos de estado de nivel de servidor, son nombrados según el código de estado que se produzca. Las páginas de error del sistema por defecto son:

  • templates/system/403.php (Status code: 403 Forbidden)
  • templates/system/404.php (Status code: 404 Not Found)
  • templates/system/500.php (Status code: 500 Internal Server Error)

Además, también están disponibles estas páginas de error del sistema:

  • templates/system/component.php (no estoy seguro si se utiliza)
  • templates/system/offline.php se utiliza para representar el mensaje de "el sitio está fuera de línea".

Tenga en cuenta que los elementos jdoc:include no se analizan en estas páginas de error.

Los códigos de estado son definidos como parte del protocolo HTTP en RFC2616. Para más información sobre códigos de estado de HTTP, consulte: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Estilo de las Páginas de Error

A estas páginas se les pueden dar estilos con las siguientes clases de CSS::

  • errorboxheader
  • errorboxbody
  • techinfo


Páginas de error personalizadas

Joomla! utiliza el archivo templates/system/error.php para manejar varios Estados de error HTTP, incluyendo los errores errores "403 Forbidden", "404 not Found", y "500 Internal Server". Puedes personalizar el estilo de los resultados de error, si lo deseas.

Es importante entender que error.php es un archivo independiente del CMS de Joomla!, pero depende de la Plataforma Joomla!. Los Plugins no se ejecutan en el archivo. No puedes incluir módulos o usar declaraciones <jdoc:include>.

Reemplazar el Sistema de los Resultados de Error

Para reemplazar el sistema de error de los resultados, copia el archivo templates/system/error.php a tu directorio templates/<nombre-plantilla>.

Si encuentra una, Joomla! hará uso del archivo error.php de la plantilla en uso, en lugar de la que hay en la carpeta templates/system.

Puedes dar formato a la página, como lo desees, para que coincida con tu plantilla.

Reemplazar el Estilo del Sistema

Si deseas cambiar el estilo, copia el archivo templates/system/css/error.css a tu directorio templates/<nombre-plantilla>/css. Luego, actualiza tu archivo templates/<nombre-plantilla>/error.php para hacer referencia a la nueva ubicación de la hoja de estilos cambiando esta línea, como corresponda:

<link rel="stylesheet" href="<?php echo $this->baseurl; ?>/templates/system/css/error.css" type="text/css" />

Ahora, simplemente, modifica el archivo error.css, como lo desees, por los requisitos de tu estilo.

Personalizar los Mensajes de Error

Puedes agregar lógica condicional para variar el mensaje devuelto, dependiendo del código de error específico.

Aquí hay un ejemplo de cómo atrapar un error 404 y proporcionar un mensaje personalizado.

<?php  if ($this->error->getCode() == '404') { ?>
	<div id="errorboxheader">Page not found</div>
		<div id="errorboxbody"><p>Sorry! That page cannot be found.</p>
		</div>
	</div>
<?php } ?>

Código de Estado HTTP

Cuando se realiza una solicitud para una página en tu sitio, el servidor devuelve un código de estado HTTP en respuesta a la solicitud. Joomla! devuelve un '200 - the server successfully returned the page' para las páginas de error. Esto es problemático para aquellos que trabajan con Google Webmaster Services y tratan de conseguir un sitemap resuelto.

Si desea que Joomla! devuelva un código de estado para el error, puedes hacerlo mediante la adición de lógica antes de la declaración de la línea DOCTYPE, de la siguiente manera:

<?php 
if ($this->error->getCode() == '404') {
	header("HTTP/1.0 404 Not Found");
} ?>

Más Información sobre Código de Estado HTTP

Usar Tema de Encabezado y Pie de página en Página de Error Estándar

Joomla 1.5 Si quieres ver la página de error con el diseño del tema y no como unaa página de error de URL redirigida o una duplicación de código HTML en la página de error de la plantilla, aquí hay una forma de aplicar el tema de la plantilla a la página de error.

En primer lugar, coloca el siguiente código en templates/<nombre-plantilla>/error.php:

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

include dirname(__FILE__) . "/index.php";
?>

A continuación, has las siguientes modificaciones a templates/<nombre-plantilla>/index.php:

1. Encuentra el siguiente código en index.php

<jdoc:include type="head" />

y reemplázalo con lo siguiente

<?php if (!$this->error->getCode()) : ?>
<jdoc:include type="head" />
<?php else : ?> 
<title><?php echo $this->error->getCode() ?> - <?php echo $this->title; ?></title>
<?php endif; ?>

2. Encuentra el siguiente código en index.php

<jdoc:include type="component" />

y reemplázalo con lo siguiente

<?php if ($this->error->getCode()) : /* check if we are on error page, if yes - display error message */ ?>
  <p><strong><?php echo $this->error->getCode() ?> - <?php echo $this->error->message ?></strong></p>
  <p><strong><?php echo JText::_('JERROR_LAYOUT_NOT_ABLE_TO_VISIT'); ?></strong></p>
  <ol>
    <li><?php echo JText::_('JERROR_LAYOUT_AN_OUT_OF_DATE_BOOKMARK_FAVOURITE'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_SEARCH_ENGINE_OUT_OF_DATE_LISTING'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_MIS_TYPED_ADDRESS'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_YOU_HAVE_NO_ACCESS_TO_THIS_PAGE'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_REQUESTED_RESOURCE_WAS_NOT_FOUND'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_ERROR_HAS_OCCURRED_WHILE_PROCESSING_YOUR_REQUEST'); ?></li>
  </ol>
  <p><strong><?php echo JText::_('JERROR_LAYOUT_PLEASE_TRY_ONE_OF_THE_FOLLOWING_PAGES'); ?></strong></p>

  <ul>
  <li><a href="<?php echo $this->baseurl; ?>/index.php" title="<?php echo JText::_('JERROR_LAYOUT_GO_TO_THE_HOME_PAGE'); ?>"><?php echo JText::_('JERROR_LAYOUT_HOME_PAGE'); ?></a></li>
  </ul>

  <p><?php echo JText::_('JERROR_LAYOUT_PLEASE_CONTACT_THE_SYSTEM_ADMINISTRATOR'); ?>.</p>
<?php else : ?>
  <jdoc:include type="component" />
<?php endif; ?>

Ahora el tema de la plantilla, también, se aplica a las páginas de error.

Nota: El módulo incluido en la plantilla no funcionará en caso de error en la página creada por este método (pero funciona en otras páginas).

El uso de módulos en las páginas de error

Los módulos no pueden ser incluidos en páginas de error de la misma manera que la plantilla index.php, porque no se pueden utilizar las declaraciones <jdoc:include>. Existe una forma alternativa para utilizar JModuleHelper.

Para incluir un módulo único por título, puedes utilizar:

if (JModuleHelper::getModule('menu')) { 
    echo $doc->getBuffer('module', 'menu');
}

Para incluir múltiples módulos por posición, puedes utilizar:

$modules = JModuleHelper::getModules( 'footer_3' );
$attribs['style'] = 'xhtml';
foreach ($modules AS $module ) {
    echo JModuleHelper::renderModule( $module, $attribs );
}


Agregar JavaScript

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

Joomla 2.5 https://api.joomla.org/cms-2.5/classes/JHtmlBehavior.html#method_framework

Joomla 3.x https://api.joomla.org/cms-3/classes/JHtmlBehavior.html#method_framework

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/


¿Cómo determinar las características del navegador?

Diferentes navegadores web, en ocasiones, muestran diferencias en la forma en que se procesa una página. Por esta razón, puedes desear averiguar qué navegador usa un visitante, con el fin de utilizar algunos parámetros CSS específicos del navegador.

El siguiente JavaScript define un objeto de detección simple del navegador, que determina el nombre del navegador y la versión por la decodificación de la cadena navigator.userAgent.

function browserDetect()
{
  var browserNames=new Array("Opera", "MSIE","Netscape","Firefox");
  this.name="NK";
  this.mainVersion="NK";
  this.minorVersion="NK";
  
  for (var i=0; i< browserNames.length; i++)
  {
   var pattern='('+browserNames[i]+')'+'.([0-9]+)\.([0-9]+)';    
   var myRegExp=new RegExp(pattern);
   if (myRegExp.test(navigator.userAgent))
    {
      var results=myRegExp.exec(navigator.userAgent);
      this.name=results[1];
      this.mainVersion=results[2];
      this.minorVersion=results[3];
      break;
    }
  }
}

Con el fin de utilizar esto en un script, debes crear una instancia de este objeto:

var browser = new browserDetect();

La propiedad browser.name te dará el nombre del navegador (MSIE, Opera, Netscape o Firefox), browser.mainVersion te dará el número de versión principal y browser.minorVersion te dará el número de versión menor.

Sin embargo, debes ser consciente de que esto no es infalible y es generalmente mejor (en opinión de este escritor) evitar tener que escribir el código en función de un navegador específico en medida de lo posible.


Agregar hojas de estilo para otros dispositivos de salida

El uso de hojas de estilo CSS, posiblilta utilizar un conjunto de directivas (estilos) dependiendo del dispositivo que se utiliza para navegar por las páginas web.

Tipos de Medios

Los tipos de medios reconocidos son:

  • all - Adecuado para todos los dispositivos.
  • aural - Para sintetizadores de voz.
  • braille - diseñado para dispositivos braille.
  • embossed - Diseñado para páginas de impresoras braille.
  • handheld - Diseñado para dispositivos portátiles.
  • print - Utilizado para dar formato a las páginas impresas.
  • projection - Diseñado para las presentaciones proyectadas, por ejemplo, proyectores o impresión de transparencias.
  • screen - Diseñado principalmente para las pantallas a color de computadoras.
  • tty - Diseñado para los medios de comunicación que utilizan una cuadrícula de caracteres de paso fijo, como teletipos, terminales o dispositivos portátiles con capacidades de visualización limitados. Los autores no deben utilizar unidades de píxel con el tipo de medio "tty".
  • tv - Diseñado tipo de dispositivos de televisión (de baja resolución, color, posibilidades limitadas de desplazamiento de las pantallas, sonido disponible).

Ejemplos

Puedes asignar un tipo de medio a una declaración CSS con la siguiente sintaxis

@media print {
  body { 
    font-size: 12pt;
    font-color: #000000; 
  }
}

Para asignar más de una declaración de estilo para más de un tipo de medios:

@media print, handheld{
  body { 
    font-size: 12pt;
    font-color: #000000;
  }
  img {
    max-width: 100%;
    height: auto;
  }
}

Las directivas pueden ser utilizados en los archivos CSS principales o en una hoja de estilos aparte para un determinado tipo de medio. No se debe incluir el archivo CSS en la sección <head> de las plantillas (el siguiente, ejemplo, es tomado de la Plantilla Beez de Joomla!):

<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/beez/css/print.css" type="text/css" media="Print" />

La forma recomendada para incluir una hoja de estilo es:

<?php
$document = JFactory::getDocument();
 $tpath = $this->baseurl . '/templates/' . $this->template;
$document->addStyleSheet( $tpath . '/css/print.css', 'text/css', 'print'); // arguments: $path, $type, $media
?>

De esta forma, te aseguras que la hoja de estilo será añadida al documento y estará accesible para los plugins (ej. para combinar y comprimir hojas de estilo).