Migrar una Plantilla de Joomla! 1.5 a 3.x

From Joomla! Documentation

This page is a translated version of the page Migrating a Template from Joomla 1.5 to 3.x and the translation is 100% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎Nederlands

Al considerar una actualización manual a su plantilla 1.5 hay algunas consideraciones que necesitas pensar acerca del tema.

En primer lugar, ¿qué habilidades se necesitan? Para hacer cambios en la plantilla, mínimas, necesitas estar familiarizado con los conceptos básicos de PHP, HTML, XML, CSS y posiblemente algo de Javascript. Si no tienes un conocimiento básico de estas habilidades mucho de lo que estarás buscando se vera extraño, por lo que estará bien repasar las habilidades o contratar a un profesional.

Segundo, la medida en que la plantilla necesita un cambio debe ser medido en términos de las mejoras o cambios de diseño que se han desarrollado en la planificación de su migración. ¿El cambio que va a tomar ventaja del nuevo framework Bootstrap en un estilo que está disponible en Joomla 3? O es un movimiento estricto que refleja el sitio actual. Mientras que algunos de los cambios que son nuevos para Joomla 3 son obligatorias ( en el sentido de que su plantilla no carga ), otros son mejoras y su plantilla se carga, pero puede que no se vea de la forma que usted desea.

A los efectos de este documento, estaremos asumiendo el ejemplo más sencillo y sugerimos una imagen espejo de la actual plantilla 1.5. Para plantillas más complejas o mejoras más importantes que necesites debes hacer alguna investigación o contratar a alguien que tenga más experiencia con las plantillas.

Revisión de los conceptos Básicos de Plantillas

Algunas cosas no han cambiado. Aún necesitas estar familiarizado con los conceptos básicos de una Plantilla Joomla!: La estructura del directorio de carpetas es una de esas cosas. Mínimamente a nivel de la raíz se necesitan 2 archivos: "index.php" y "templateDetails.xml" (observe el la mayúscula!). La mayoría de las plantillas incluyen al menos 2 carpetas: una carpeta de imágenes para contener todos los gráficos que usa tu plantilla y una carpeta para archivos css. Plantillas más avanzadas pueden contener carpetas con nombres como estos por ejemplo: "html" para la personalización de componentes y módulos, una carpeta "lenguage" para la personalización del idioma, "javascript" para mantener las rutinas de javascript personalizadas.

Sólo asegúrate de que si la carpeta aparece en el archivo XML que exista en la plantilla a subir a Joomla!. Si se declara un archivo en XML, a continuación, debe existir o tu plantilla no se cargará.

Un ejemplo de una mejora en las versiones superiores a 1.5, es la eliminación de la exigencia de que todos los nombres de los archivos de la subcarpeta en la lista. Para las plantillas en Joomla 3, basta con indicar el nombre de la carpeta.

Para obtener más información sobre los aspectos básicos de una plantilla de ver en este enlace: Crear una plantilla básica de Joomla!

Cambios en el Archivo XML

Lo que debe cambiar en el archivo templateDetails.xml ( Archivo de Manifiesto de la Plantilla )

El archivo de manifiesto de la plantilla proporciona la información que Joomla! necesita para instalar tu plantilla. El archivo de manifiesto XML ha sido casi totalmente modificado desde 1.5, así que asegúrate de estudiar y están familiarizados con los conceptos básicos y las modificaciones. Tu plantilla no se cargará si este archivo no es exactamente correcto.

Etiqueta de Referencia al Tipo de Documento y las etiqueta Instalación/Extensión

La etiqueta install de XML ahora es una etiqueta "extension". Además, cualquier referencia en la Etiqueta DOCTYPE o números de versión ahora necesitan referirse a 3.0.

Las antiguas líneas son algo como esto:

<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://dev.joomla.org/xml/1.5/template-install.dtd">
<install version="1.5" type="template">

Ahora, se debe parecerse a esto:

<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">
<extension version="3.1" type="template" client="site">

Etiquetas de Carpeta y Archivo

Esta regla siempre ha sido así y sigue siendo: Si listas el nombre de archivo o carpeta en el XML debe existir en la plantilla subida. Esto no ha cambiado en Joomla 3. Lo que cambió es el requisito de 1.5 que se enumeren todos los nombres de archivos en una carpeta. Ahora puedes hacer referencia sólo al nombre de la carpeta. Por ejemplo, anteriormente en 1.5 los nombres de archivo xml se enumeran por separado de la siguiente manera:

<images>
	<filename>images/arrow.png</filename>
	<filename>images/arrow2.png</filename>
	<filename>images/arrow3.png</filename>
	<filename>images/author.gif</filename>
</images>

Para una plantilla Joomla! 3 esta declaración es suficiente:

<folder>images</folder>

Etiquetas de Módulos

Para 1.5, las posiciones de los módulos son definidos en la plantilla. Esto no ha cambiado. Ellos todavía tienen que ser mencionados.

Parámetros

Los parámetros son una característica opcional de las plantillas que permiten al autor de la plantilla ofrecer opciones de los estilos de la plantilla en el Administrador de Joomla!. En plantillas Joomla 1.5 los parámetros se enumeran en un archivo "parameters.ini" en el nivel raíz. Este archivo ha sido eliminado y los parámetros son ahora las etiquetas en el archivo XML.

Aquí está un ejemplo del contenido de un archivo parameters.ini:

colorVariation=blue
backgroundVariation=blue

Para definir los parámetros en Joomla 3 hay que añadir estas líneas al archivo XML:

      <config>
		<fields name="params">
		     <fieldset name="advanced">
				<field name="colorVariation" class="" type="color" default="#08C"
					label="TPL PROTOSTAR COLOR LABEL"
					description="TPL PROTOSTAR COLOR DESC" />
				<field name="backgroundVariation" class="" type="color" default="#F4F6F7"
					label="TPL PROTOSTAR BACKGROUND COLOR LABEL"
					description="TPL PROTOSTAR BACKGROUND COLOR DESC" />
		    </fieldset>
		</fields>
     </config>

Para etiquetas XML de parámetros más complejos tienes que referirse a documentación más amplia. También ten en cuenta que el index.php que referencia las variables del parámetro también tendrá que ser cambiado.

Consulte los siguientes enlaces para obtener más información acerca de:

Archivo index.php

¿Que debo cambiar en el archivo index.php?

Los archivos Index.php son tan variados como hay diseñadores y programadores que escriben. El index.php en una plantilla para Joomla 3 es la compilación de las muchas versiones que vinieron antes, incluyendo 1.5, 1.6, 1.7, 2.5, etc. Este archivo de plantilla es el "torrente sanguíneo", que provee vida a la piel de la plantilla y tiene acceso a cada pieza de disponible del framework de Joomla! y se puede utilizar cada una de estas piezas para manipular lo que tu sitio va a mostrar a tus usuarios. Esto siempre ha sido así y todavía lo es. Diseñadores y programadores de plantillas han tomado ventaja de este hecho en versiones anteriores y continuará, por lo que este archivo necesita la investigación y planificación más cuidadosa.

Los cambios que se realizaron en el framework de Joomla! 3 pueden causar problemas para algunas plantillas anteriores y cuando se representan podrían producir errores. Otras plantillas puede no tener referencia a la misma pieza de framework y todo funcionan bien casi sin cambios. Por ejemplo, una plantilla 1.5 que tiene acceso al valor de la variable "frontpage" para determinar si está en la página de inicio o no. Esto no funciona en Joomla! 3 (Ver la tabla abajo para código). Si una plantilla hace referencia a una pieza modificada o no, será el factor determinante sobre muchos de los problemas que se tienen cuando se trata de implementar una plantilla actualizada.

Estar preparado para hacer algunos cambios basados en las "mejores prácticas". A pesar de que tu index.php puede funcionar, tiene que ser seguro y ejecutarse de manera eficiente. Considera la posibilidad de que cada página que se sirve a tu audiencia utiliza el archivo index.php, así que asegúrate de estár familiarizado con los métodos recomendados para el framework de Joomla1 y bloques de construcción para una plantilla. Un estudio exhaustivo del archivo index.php en al Plantilla Protostar y la Beez Plantilla que se incluye con el paquete de instalación de Joomla! 3 puede proporcionar ejemplos y mejores prácticas para las plantillas más complejas.

Directrices

Aquí hay algunas pautas para tu archivo index.php de Joomla! 3 plantilla:

1. De nuevo, algunas cosas no han cambiado: todos los index.php de las plantillas deben comenzar con esta declaración:

<?php defined( '_JEXEC' ) or die;?>

Cierto para Joomla! 1.5 y siendo cierto para Joomla! 3.

2. Para Joomla! 3 el DCOTYPE recomendado (Declaración de Tipo de Documento) debe ser HTML5 ya que este se utiliza en todo Joomla! 3. He aquí un ejemplo:

<!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">

3. Para hacer uso de las aplicaciones del framework de Joomla! 3:

En 1.5 el acceso al framework se realiza a través de la variable $mainframe. Puedes ver algo como esto:

<?php require_once (‘includes/../framework.php' );
$mainframe =& JFactory::getApplication('site'); ?>
reemplázalo con esto:
<?php $app = Jfactory::getApplication();?>

4. Para recuperar el código del Heading utiliza esta instrucción directamente debajo de la etiqueta de encabezado y sigue con tus hojas de estilo. Esto no ha cambiado con Joomla! 3, pero siempre vale la pena repetirlo:

<jdoc:include type="head" />

5. Para recuperar el sitename en 1.5 se puede ver esto:

<?php echo $mainframe->getCfg('sitename');?>

Para Joomla! 3 utilizar este código:

<?php  $app->getCfg('sitename');?>

6. Códigos y Mensajes de Error:

Una mejor metodología para la recuperación de los códigos de error se emplea en Joomla! 3. Puedes ver esto en tu plantilla 1.5:

<?php $this->error->code; ?>
reemplaza con esto de Joomla! 3 en la convención:
<?php $this->error->getCode(); ?>

Para los mensajes de error, este es una declaración típica de 1.5:

<?php $this->error->message; ?>
Reemplaza con esta declaración para Joomla! 3
<?php $this->error->getMessage(); ?>

7. El acceso a los parámetros de la plantilla para reemplazar en el código se parece a esto:

<?php $color = $this->params->get('colorVariation'); ?>
con esta metodología recomendada:
<?php $app = Jfactory::getApplication();
$template = $app->getTemplate(true);
$params = $template->params;
$color = $params->get('colorVariation'); ?>

Esto va a funcionar igual de bien como en el ejemplo:

<?php $app = Jfactory::getApplication();
$params = $app->getParams();
$color = $params->get('colorVariation'); ?>

8. EL acceso a las clases del Objeto Global Document en el archivo index.php de la plantilla se suelen codificar de esta manera:

<?php $doc = Jfactory::getDocument(); ?>

Esta declaración es la mismo en Joomla! 3. Sin embargo, es válido señalar que esta declaración no necesita acceder a las clases de página, por lo que podría estar allí o puede que no, dependiendo del programador original. Por ejemplo: dado el código:

<?php $doc =& JFactory::getDocument();
echo 'Current title is: ' . $doc->getTitle(); ?>

es equivalente a este código:

<?php echo 'Current title is: ' . $this->getTitle(); ?>


En Resumen

La siguiente tabla es una referencia rápida de las diferencias de código del archivo index.php de una plantilla entre Joomla! 1.5 y Joomla! 3.x.

Descripción En una Plantilla (index.php) 1.5 se puede ver Código recomendado de la Plantilla J3.x (index.php)
Primera Línea <?php defined( '_JEXEC' ) or die( 'Restricted access' );?> Sin cambios
DOCTYPE
<?php echo '<?xml version="1.0" encoding="utf-8"?'.'>'; ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>" >
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"  xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>">
Acceder al Framework de Joomla!
$app = JFactory::getApplication(); OR 
require_once (‘includes/../framework.php' );
$mainframe =& JFactory::getApplication('site');
Sin cambios, pero debe tener este aspecto:
$app = JFactory::getApplication();
Recuperar las cabeceras HTML desde Joomla!
<jdoc:include type="head" />
Sin cambios
Recuperar el Nombre del Sitio
$mainframe->getCfg('sitename');
$app->get('sitename');
Recuperar Códigos de Error
$this->error->code
$this->error->getCode();
Recuperar Mensajes de Error
$this->error->message
$this->error->getMessage();
Recuperar Mensajes del Sistema
$this->getBuffer('message')
<jdoc:include type="message" />
Idioma Activo
$this->language;
$doc->language;
Vista
JRequest::getVar( 'view' )
$app->input->getCmd('view');
Tarea
JRequest::getVar( 'task' )
$app->input->getCmd('task');
Diseño
JRequest::getVar( 'layout' )
$app->input->getString('layout', 'default');
ID
JRequest::getVar( 'id' )
Con alias:
$app->input->getString('id');
Sólo ID:
$app->input->getInt('id');
Detección de la página principal
<?php if(JRequest::getVar( 'view' ) == 'frontpage') ?>
<?php $menu = $app->getMenu();
if($menu->getActive() == $menu->getDefault()) ?>
Contenido Principal
<jdoc:include type="component" />
Sin cambios
Módulos y Posiciones
<jdoc:include type="modules" name="right" style="xhtml" />
Sin cambios
Recuperar la dirección URL Base
$url = clone(JURI::getInstance());
echo $this->baseurl; 
JURI::root()*; 
JURI::base();
$this->baseurl;
Acceder a las Clases Documentos de Página
$doc = JFactory::getDocument();
Sin cambios

Sin embargo, el uso de "$this->" es equivalente.

Acceder a los Parámetros de la Plantilla
echo $this->params->get('colorVariation');
Sin cambios


Estilo Bootstrap y Joomla! 3

Para incorporar el nuevo Estilo Bootstrap ( 2.3.2 ) en tu plantilla actualizada, usa estas tres líneas en la parte superior de tu index.php', en sustitución de la línea de bloque php.

<?php defined( '_JEXEC' ) or die;
JHtml::_('bootstrap.framework');
JHtml::_('bootstrap.loadCss', true, $this->direction); ?>

Después de estas declaraciones, puedes agregar clases Bootstrap (2.3.2 ) dondequiera que las necesites y aprovechar el framework Bootstrap que se ofrece en Joomla! 3.


Hay que repetirlo...

Hay muchas variaciones en las prácticas de codificación y el éxito con la traducción de una plantilla 1.5 para que se ajuste a una plantilla para Joomla! 3 depende de la complejidad del diseño viejo y del nuevo, y de la codificación original. La plantilla podría haber sido previamente convertidas de Joomla! 1.0! La mejor estrategia es investigar la documentación disponible y familiarizarse con las plantillas Protostar y Beez de Joomla! 3. Técnicas para la codificación y estructuración en estas 2 plantillas han sido sometidas al escrutinio de la comunidad y desarrolladores voluntarios de Joomla! – los verdaderos expertos sobre cómo hacer tu mejor plantilla segura y que funcione de manera fiable.

Referencias