¿Cuál es el propósito del archivo templateDetails.xml?
From Joomla! Documentation
El archivo templateDetails.xml es necesario para las plantillas de Joomla! y se puede encontrar en el directorio raíz de la plantilla de cualquier plantilla dentro del directorio de plantillas de Joomla!. Este archivo XML contiene los meta datos básicos que Joomla! necesita con el fin de mostrar y ofrecer como opción la plantilla en el lado servidor. También contiene una variedad de otros meta datos que se utilizan para proporcionar información acerca de la plantilla, el/los autor/es de la misma y definir los archivos y carpetas que son utilizados por la plantilla. También define los archivos de idioma de la plantilla, así como los parámetros y la configuración que la plantilla ofrece en el lado servidor.
El archivo templateDetails.xml utiliza de una manera bastante básica el formato y la estructura XML. Los datos XML en este archivo se dividen en secciones y específicamente con unformato para representar los distintos elementos y parámetros. Los datos XML se leen y analizan por medio de potentes herramientas en el núcleo de Joomla!, entonces prestados para registrar la plantilla y crear la pantalla que se ve en el Gestor de Plantillas. Esta plantilla proporciona a los desarrolladores un método relativamente sencillo para la creación de tareas, configuración y los parámetros para su uso en la plantilla.
La aplicación de templateDetails.xml va a variar de una plantilla a otra, puede ser simple o complejo dependiendo de las características que ofrece la plantilla. El valor predeterminado de la plantilla Protostar para Joomla! 3 sirve como un excelente ejemplo para demostrar cómo se utiliza este archivo. Se explican a continuación las diversas secciones de este archivo.
Formato XML
Las dos primeras líneas de cada archivo templateDetails.xml son necesarias para iniciar la definición de los formatos XML y doctype.
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">La siguiente línea es también necesaria, pues le dice a Joomla! que los datos de este archivo son para ser utilizado en una extensión, en este caso una plantilla. Todos los datos de la plantilla están contenidos dentro de esta etiqueta <extension> y el archivo concluye con el cierre de esta etiqueta </extension>.
<extension version="3.1" type="template" client="site">Detalles Básicos
La primera sección es generalmente donde los desarrolladores de plantillas incluyen información acerca de la misma. Información tal como nombres, fechas, información de contacto, derechos de autor, número de versión y una descripción básica son comunes. Estos datos se utilizan en el Gestor de plantillas, se muestran en la lista de plantillas disponibles y se pueden mostrar, también, en la pantalla de edición de plantillas.
Plantilla: Detalles Básicos, como se ven en el Gestor de plantillas > Plantillas
Protostar, detalles básicos del código XML:"'
<extension version="3.1" type="template" client="site">
<name>protostar</name>
<version>1.0</version>
<creationDate>4/30/2012</creationDate>
<author>Kyle Ledbetter</author>
<authorEmail>admin@joomla.org</authorEmail>
<copyright>Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.</copyright>
<description>TPL_PROTOSTAR_XML_DESCRIPTION</description>Puedes notar que la última línea de este código, <description>, contiene una cadena del idioma y no la descripción. Esta cadena hace referencia a un archivo de idioma de la plantilla donde la descripción real está definida y escrita. Este es el método preferido en Joomla! para las extensiones que se distribuyen de uso público para adecuar el soporte de idioma internacional, sin embargo, uno podría simplemente escribir la descripción si la traducción no es una preocupación. Los archivos de idioma se definen en el archivo templateDetails.xml, en la sección de <language>, que se describe con más detalle más adelante en este artículo.
Descripción de la Plantilla visto en el Editor de Protostar
Estructura de Carpetas
Todas las Carpetas relacionadas con la instalación de la plantilla se mencionan aquí. Todos los archivos y carpetas en la raíz del directorio de la plantilla durante la instalación deben ser listados aquí. Los archivos contenidos dentro de una carpeta que está en la lista se incluyen automáticamente. Cada carpeta contiene la información de la ruta completa partiendo de la raíz de la plantilla. El Gestor del Instalaciones utiliza esta información para el almacenamiento de los archivos durante la instalación.
Abajo está la estructura de archivos y carpetas predeterminada de la plantilla Protostar. Esto es una estructura de archivos bastante estándar de una plantilla básica para Joomla!.
<files>
<filename>component.php</filename>
<filename>error.php</filename>
<filename>favicon.ico</filename>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_preview.png</filename>
<filename>template_thumbnail.png</filename>
<folder>css</folder>
<folder>html</folder>
<folder>images</folder>
<folder>img</folder>
<folder>js</folder>
<folder>language</folder>
<folder>less</folder>
</files>Vista del directorio de Protostar J3
Posiciones de los Módulos
Las Posición de los Módulos disponibles, que pueden ser utilizados por la plantilla se definen en esta área.
Estas son las posiciones predeterminadas de los módulos definidos en la plantilla Protostar:
<positions>
<position>banner</position>
<position>debug</position>
<position>position-0</position>
<position>position-1</position>
<position>position-2</position>
<position>position-3</position>
<position>position-4</position>
<position>position-5</position>
<position>position-6</position>
<position>position-7</position>
<position>position-8</position>
<position>position-9</position>
<position>position-10</position>
<position>position-11</position>
<position>position-12</position>
<position>position-13</position>
<position>position-14</position>
<position>footer</position>
</positions>La lista de posiciones están contenidas dentro de la etiqueta <positions>. Cada etiqueta <position> crea una posición de módulo que está disponible desde la lista de posiciones en la en el gestoror de módulos y en otras áreas de Joomla! donde las posiciones de los módulos puede ser seleccionadas.
El formato simple de la lista de posicines significa que puede ser fácilmente personalizado. Por ejemplo, para agregar una nueva posición de un módulo a la lista, simplemente se añade una nueva etiqueta <position> en el interior de la etiqueta <positions> con un nombre único utilizando todas las letras en minúsculas, sin espacios. Ten en cuenta, esto sólo se suma la posición para el lado servidor y se requiere desarrollo adicional en otros archivos de la plantilla para representar la nueva posición del lado cliente.
Idiomas
Algunas plantillas pueden incluir archivos de idioma para permitir la traducción de texto estático en la plantilla. Observa que la carpeta de idioma se define y los dos archivos de idioma en el interior también están incluidos. Aunque el idioma de la carpeta se define anteriormente, estos archivos tienen sus propias definiciones. Este método le indica Joomla! donde residen los archivos de idioma que contienen cadenas de caracteres utilizados por la plantilla.
El primer archivo contiene el archivo de idioma para el texto que va a ser visto por el Usuario. El segundo archivo, con la extensión .sys, o system, es para el texto que se visualiza en el área del Administrador.
Este es la estructura predeterminada de carpetas y archivos de idioma de la plantilla Protostar:
<languages folder="language">
<language tag="en-GB">en-GB/en-GB.tpl_protostar.ini</language>
<language tag="en-GB">en-GB/en-GB.tpl_protostar.sys.ini</language>
</languages>Las cadenas de idioma se utilizan en las plantillas y a lo largo de Joomla! con el propósito de la utilización de la características de amplia compatibilidad de idioma internacional de Joomla!. Este método proporciona a los desarrolladores y a los usuarios una forma relativamente simple para traducir cualquier texto que se utiliza en las plantillas y las pantallas de la extensión. Joomla! comprobará los archivos de idioma para las cadenas de cualquier idioma que se utiliza y cargar el texto correspondiente al idioma escogido por el usuario en lugar de la cadena original. En este caso, sólo hay archivos para inglés (en-GB), el texto de las traducciones en otros idiomas deben ser aportados por los Usuarios o Desarrolladores antes de que pueda ser utilizado por Joomla!.
Más información acerca de los Archivos de Idioma:
Parámetros
Una plantilla puede ofrecer opciones de visualización y otros parámetros que pueden ser seleccionados por el Administrador en el Gestor de plantillas. Por ejemplo, la plantilla predeterminada Protostar permite al Administrador cambiar varios colores,, tipografías y agregar un logotipo, estos parámetros se encuentran en la pestaña Advanzado, que es también definida y creada por los parámetros XML.
Los parámetros de la plantilla están contenidas dentro de una etiqueta <config>, que contiene una <fields>etiqueta con un nombre de atributo de "parámetros". Dentro de la etiqueta <fields> es donde los parámetro en grupo e individualmente son definidos. La etiqueta <fieldset> se utiliza para crear grupos de parámetros. Cada uno de los parámetros se definen con la etiqueta <field>.
Cada <fieldset>, y cada parámetro <field> dentro de un <fieldset>, requieren un nombre único definido por el atributo name . Este nombre define el parámetro en sí mismo y se utiliza para pasar los ajustes a los archivos del lado cliente. Cada parámetro también debe contener una atributo label y un atributo description . El texto de la etiqueta aparece con el parámetro en la pantalla de configuración para identificar lo que utiliza el ajuste y para información más detallada se puede incluir en la descripción.
Un parámetro de campo puede ser prácticamente cualquier tipo de entrada de formulario con las opciones correspondientes, este es seleccionado por el atributo type . Cualquiera de las opciones que sean necesarias, tales como el botón de radio o seleccionar opciones, se definen en las etiquetas <option>. Nombres de clase de CSS puede ser definidas de acuerdo con el atributo class y parámetros de configuración predeterminados pueden ser definidos mediante el uso de la atributo default .
A continuación están las definiciones de parámetros predeterminadas de la Plantilla Protostar. En este ejemplo, todas las Etiquetas, Descripciones y Opciones utilizan las cadenas de definición de idioma de los archivos de Idioma definidos en el apartado anterior, así como algunos del núcleo de Joomla!, por lo que puede ser traducido a tantos idiomas como sea necesario.
<config>
<fields name="params">
<fieldset name="advanced">
<field name="templateColor" class="" type="color" default="#08C"
label="TPL_PROTOSTAR_COLOR_LABEL"
description="TPL_PROTOSTAR_COLOR_DESC" />
<field name="templateBackgroundColor" class="" type="color" default="#F4F6F7"
label="TPL_PROTOSTAR_BACKGROUND_COLOR_LABEL"
description="TPL_PROTOSTAR_BACKGROUND_COLOR_DESC" />
<field name="logoFile" class="" type="media" default=""
label="TPL_PROTOSTAR_LOGO_LABEL"
description="TPL_PROTOSTAR_LOGO_DESC" />
<field name="sitetitle" type="text" default=""
label="JGLOBAL_TITLE"
description="JFIELD_ALT_PAGE_TITLE_LABEL"
filter="string" />
<field name="sitedescription" type="text" default=""
label="JGLOBAL_DESCRIPTION"
description="JGLOBAL_SUBHEADING_DESC"
filter="string" />
<field name="googleFont"
type="radio"
class="btn-group btn-group-yesno"
default="1"
label="TPL_PROTOSTAR_FONT_LABEL"
description="TPL_PROTOSTAR_FONT_DESC"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
<field name="googleFontName" class="" type="text" default="Open+Sans"
label="TPL_PROTOSTAR_FONT_NAME_LABEL"
description="TPL_PROTOSTAR_FONT_NAME_DESC" />
<field name="fluidContainer"
type="radio"
class="btn-group btn-group-yesno"
default="0"
label="TPL_PROTOSTAR_FLUID_LABEL"
description="TPL_PROTOSTAR_FLUID_DESC"
>
<option value="1">TPL_PROTOSTAR_FLUID</option>
<option value="0">TPL_PROTOSTAR_STATIC</option>
</field>
</fieldset>
</fields>
</config>La plantilla Protostar ilustra un par de maneras diferentes en que XML puede ser utilizado en la interfaz de una plantilla, pero hay muchas más posibilidades. En este ejemplo, la etiqueta <fieldset name="advanced"> incluye todos los parámetros y se utiliza el atributo name para crear la pestaña "Avanzado" en la interface. Todo lo necesario para crear otra pestaña en la interface es agregar otra etiqueta <fieldset> con un atributo nombre diferente. Con esto en mente, es relativamente sencillo crear tantas pestañas adicionales y parámetros según sea necesario en una plantilla.