Manifest files/es

This Article Needs Your Help

Joomla! 

3.x

Joomla! 

2.5

Dentro de Joomla! hay archivos de manifiesto para todas las extensiones. Estos archivos incluyen la información general de instalación, así como los parámetros para la configuración de la extensión. Desde Joomla! 2.5, hay muy pocas diferencias de formato entre los archivos de manifiesto para los diferentes tipos de extensiones, lo que permite a cada tipo acceder con todo el poder de al instalador de Joomla!.

Convenciones de nomenclatura

El archivo debe ser nombrado manifest.xml o <nombre_de_la_extensión>.xml y deber ser ubicado en el directorio raíz del paquete de la instalación.

Sintaxis

Elemento raíz

La etiqueta principal del archivo de instalación es:

<extension></extension>

Estas etiquetas, de apertura y cierre, ahora son válidos para todas las extensiones. La nueva etiqueta <extension> sustituye a la antigua <install></install> a partir de Joomla . Se permiten los siguientes atributos dentro de la etiqueta:

Atributo	Valores	Aplicable a	Descripción
type	component file language library module package plugin template element	Todas las extensiones	Este atributo describe el tipo de la extensión para el instalador. Basado en este tipo, se aplican los requisitos adicionales de las sub-etiquetas.
version	2.5 3.0	Todas las extensiones	Cadena que identifica la versión de Joomla! para la cual la extensión se desarrolla.
method	install upgrade	Todas las extensiones	El valor predeterminado install, también se utilizará si el atributo método no se utiliza. El valor install significa que el instalador va a detenerse correctamente si se encuentra cualquier archivo/carpeta existente de la nueva extensión.
client	site administrator	Módulos	El atributo cliente permite especificar para qué cliente de la aplicación está disponible el nuevo módulo.
group	string	Plugins	El nombre del grupo especifica para qué grupo de plugins el nuevo plug-in está disponible. Los grupos existentes son los nombres de las carpetas dentro del directorio /plugins. El instalador creará los nuevos nombres de carpetas de nombres de grupos que todavía no existen.

Metadatos

Los siguientes elementos pueden ser utilizados para insertar metadatos. Ninguno de estos elementos son necesarios; si están presentes, deben ser un hijo del elemento raíz.

<name> – raw component name (e.g. com_banners). 
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2005 - 2011 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. NU General Public License version 2 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. admin@joomla.org)
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)
<element> – the internal name of the component. If omitted, name will be cleaned and used

Nota: Las etiquetas <name> y <description> también son campos traducibles, de modo que el nombre y la descripción de la extensión puede ser mostrado el usuario en su idioma nativo.

Archivos Lado Cliente

	<files folder="from-folder">
		<filename>example.php</filename>
		<folder>examples</folder>
	</files>

Los archivos a copiarse en el directorio del Lado Cliente se deben colocar en el directorio <files>. Puedes utilizar el atributo opcional folder, para especificar un directorio en el paquete ZIP para copiar desde. Cada archivo a copiar debe estar representado por un <filename>. Si deseas copiar una carpeta entera a la vez, se puede definir como un <folder>.

Para plugins, el nombre simple del plugin debe ser colocado en el atributo plugin del elemento <filename> que apunta al archivo que contiene la clase del plugin. Por ejemplo, en el caso de un plugin del sistema "ejemplo" (nombre completo plg_system_ejemplo), usar <filename plugin="ejemplo">ejemplo.php</filename>.

Archivos multimedia

	<media folder="media" destination="com_example">
		<filename>com_example_logo.png</filename>
		<folder>css</folder>
		<folder>js</folder>
	</media>

En este ejemplo se va a copiar el(los) archivo(s) (/media/com_example_logo.png) y carpetas ( /media/css/ y /media/js/ ) enumerados, a /media/com_example/, creara la carpeta com_example, si es necesario. Puedes utilizar el atributo opcional folder para especificar un directorio en el paquete ZIP para copiar desde (en este caso, media).

Las extensiones deben almacenar accesorios que necesitan para ser accesibles desde la web (JS, CSS, imágenes, etc) en media. Entre otras cosas, esta característica se agregó como paso en la progresión del apoyo multi-sitio y el eventual traslado de los archivos de código (PHP) de la web de las áreas de acceso al servidor.
Nota: la sección media no se analiza si el 'paquete' es del tipo extensiones.

Ref:

• Google Groups - joomla-dev-cms thread
• Google Groups - joomla-dev-cms thread

Sección de administración

	<administration>
		<!-- various elements -->
	</administration>

La sección de administración se define en el elemento <administration>. Ya que sólo se aplica para componentes, tanto para el Sitio como el administrador, sólo en componentes el manifiesto puede incluir este elemento.

Archivos del Lado Servidor

Archivos a copiar al directorio del Lado Servidor debe ser colocado en el elemento <files> dentro de <administration>. Puedes utilizar el atributo opcional folder para especificar un directorio en el paquete ZIP para copiar desde. Consulta Archivos lado Cliente(más arriba) para otras reglas.

Enlaces de menú y submenús

Nota de la versión: Antes de Joomla! 3.4, no tener una etiqueta <menu> en el archivo de manifiesto XML conducía a un elemento del menú que se está creado. Este error fue corregido en Joomla! 3.4, por lo que si no hay etiqueta <menu> en el archivo de manifiesto, entonces no hay elemento de menú del administrador creado para el componente.

	<menu>COM_EXAMPLE</menu>
	<submenu>
		<!--
			Note that all & must be escaped to &amp; for the file to be valid
			XML and be parsed by the installer
		-->
		<menu link="anoption=avalue&amp;anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
		<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
	</submenu>

El texto para el elemento del menú principal del componente es definido en el elemento <menu>, un hijo de <administration>. Un elemento <submenu> también pueden estar presente (también un hijo de <administration>), que puede contener más elementos de menú definidos por <menu>.

Además, cada uno de los elementos <menu> pueden definir los siguientes atributos:

Atributo	Descripción
link	Un enlace para enviar al usuario cuando se hace clic en el elemento de menú
img	La ruta de acceso (relativa) a una imagen (16x16 píxeles) que aparece junto al elemento del menú. Debe ser una url compatible como un archivo (por ejemplo, sin espacios) !
alt
string	Un parámetro de URL para añadir el enlace. Por ejemplo, <menu view="cpanel">COM_EXAMPLE</menu> en el manifiesto de com_example haría que la dirección URL del elemento de menú sea índex.php?option=com_example&view=cpanel.

El valor dentro de la etiqueta es la etiqueta del menú. A diferencia de Joomla! 1.5, no puedes usar el lenguaje natural en una cadena. Por ejemplo, si quieres entrar "Componente de Ejemplo" en lugar de COM_EXAMPLE, que se traduciría en el nombre de tu componente que aparecería como componente-de-ejemplo en el menú y que sería incapaz de proporcionar una traducción. Con el fin de proporcionar una traducción, necesitas crear un archivo llamado en-GB.com_example.sys.ini en administrador/languages/en-GB (se puede utilizar la etiqueta <language> del manifiesto para hacer la copia durante la instalación) o en administrator/components/com_example/language/en-GB. En el último caso, no debes incluir el archivo de traducción en la etiqueta <language>. Mientras tengas colocado el directorio del idioma en tu etiqueta <files>, será copiado igualmente cuando el componente sea instalado.

El contenido de ese archivo debe ser:

COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"

Por favor, ten en cuenta que las cadenas de idioma deben estar entre comillas dobles, como por se indica en las normas de traducción de Joomla!. Nota importante: Joomla! 1.6 y posteriores ordena los elementos del menú Componentes basado en la traducción de la clave que se le proporciona en tu manifiesto XML. Esto significa que el orden es correcto, no importa como llames a tu clave de traducción y no importa el idioma en que el sitio se muestra. Esencialmente, Joomla! 1.6 soluciona la incorrecta clasificación de los Componentes en el menú que se experimenta bajo Joomla! 1.5 para la mayoría de los usuarios de Joomla! (que no hablan inglés!).

Configuración

Warning!

El elemento <config>, un hijo del raíz, describe las opciones de configuración de la extensión. Si procede, las opciones se mostrarán en Gestor apropiado (Gestor de plugins, Módulos o Plantillas). Opciones de configuración también se pueden definir en un archivo independiente denominado config.xml. Su elemento raíz debe ser <config>.

Cada conjunto de campos debe contener uno o más elementos <field>, cada uno representando a un solo campo de formulario con una etiqueta. Mira Tipos estándar de campos de formulario para una lista de los tipos de campo de formulario permitidos y un ejemplo de definiciones XML, de campos de formulario.

SQL

    <install>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.install.sql</file>
        </sql>
    </install>
    <uninstall>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
        </sql>
    </uninstall>

En el ejemplo de arriba, ponemos los archivos de SQL en la carpeta admin/sql del paquete de instalación. Tienes que incluir la carpeta sql en los archivos de administración (como se describe en Archivos del Lado Servidor).

Puede ejecutar SQL durante la instalación y/o desinstalación mediante los elementos <install> y <uninstall>, respectivamente. Un elemento <sql> debe aparecer como un hijo de estos elementos. <sql> puede contener cualquier número de elementos <file>, cada uno de define un único archivo SQL a ejecutar. Tu tipo de controlador de base de datos se debe describir en el atributo driver, tus conjuntos de caracteres con el atributo charset.

Esquema de actualización SQL

Desde 1.6, también hay una etiqueta <update>, que te permite ofrecer una serie de archivos SQL para actualizar el esquema actual.

	<update>
		<schemas>
			<schemapath type="mysql">sql/updates/mysql</schemapath>
			<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
		</schemas>
	</update>

Por ejemplo, con el fin de pasar de la versión 1.0.0 a la versión 1.0.1 en una base de datos MySQL, un archivo 1.0.1.sql debe ser creado dentro de la carpeta sql/updates/mysql y la etiqueta <version> del manifiesto debe ser actualizada a este valor

<version>1.0.1</version>

La estructura final de la carpeta sql se parecerá a esto (suponiendo una base de datos MySQL)

sql
 |-->example.install.sql
 |-->example.uninstall.sql
 |-->updates
     |-->mysql
        |-->1.0.1.sql

Archivos similares deben ser creados para versiones posteriores.

Archivos de idioma

En Joomla! 1.5, los desarrolladores de extensiones tenían que poner los archivos de idioma de la extensión en la carpeta principal de idioma de Joomla!, utilizando la etiqueta

como se muestra a continuación. Este método puede utilizarse en Joomla! .

<!-- Joomla! 1.5 language tag -->
<languages folder="langfiles">
	<language tag="en-GB">en-GB.com_example.ini</language>
</languages>

Desde Joomla! 1.6 se ha alentado a colocar los archivos de idioma de la extensión en la carpeta de la extensión. Joomla! entonces automáticamente carga los archivos de idioma de la carpeta de la extensión.

Mediante el almacenamiento de los archivos de idioma de la extensión en la carpeta de la extensión, se tiene la ventaja de aislar y proteger los archivos de idioma de tu extensión. Por ejemplo, un administrador elimina un idioma de su instalación Joomla!. La los archivos de idioma de la extensión no serán eliminados. Se mantendrán en su lugar y estará disponibles si el idioma se instala de nuevo.

La estructura de la carpeta de idioma para el Lado Cliente y el Lado Servidor es la misma. Se pone la etiqueta de idioma (por ejemplo, es-ES ) de cada idioma en la carpeta de su idioma es decir, language/es-ES/. Tienes que especificar las carpetas en lso archivos del Lado Cliente y Lado Servidor.

En el manifiesto, sólo tienes que incluir la carpeta language en la sección <files>, se copiaran al sub-directorio de cada idioma automáticamente. Dentro del grupo <files> simplemente agrega un elemento <folder> junto con los elementos en grupo '<files>, como se muestra en este ejemplo:

<files>
	<filename plugin="alpha">alpha.php</filename>
	<folder>sql</folder>
	<folder>language</folder>
</files>

También es notable el hecho de que ambas formas pueden trabajar juntos. Aquí es un ejemplo con el núcleo:

<files>
	<filename plugin="languagecode">languagecode.php</filename>
	<filename>index.html</filename>
	<folder>language</folder>
</files>
<languages>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>

Las ventajas de esta solución son las siguientes:

Todos ini archivos presentes en la carpeta del núcleo tienen precedencia sobre los archivos en la carpeta language/ de la extensión. Por ejemplo, un archivo sys.ini siempre estará cargado de las carpetas del núcleo en el Lado Servidor, si es que existe, excepto cuando se instala una extensión que contiene un archivo sys.ini en la carpeta de idioma. En ese caso y sólo en ese caso, el archivo sys.ini en la carpeta de la extensión mostrará su contenido traducido en el momento de la instalación. Esto es muy útil ya que un desarrollador puede tener 2 archivos sys.ini con diferentes contenidos. Una descripción de la correcta instalación, así como un tutorial en el Lado Servidor, por ejemplo.

También, es mucho más fácil para un usuario que necesita un archivo ini para una extensión que no se ofrece en el idioma deseado, agregarlo en las carpetas principales. No hay riesgo que sea eliminado en caso de desinstalar la extensión por error o por cualquier otra razón.

Mira también:

• paquetes de idioma que no son del núcleo
• Creación de paquetes de idioma para las extensiones en Joomla 2.5

Durante el desarrollo se puede habilitar la depuración den idioma en la configuración global de Joomla!. Así que puedes investigar si surge un problema. Como desde 3.2, esto es necesario para ayudar a depurar en-GB, siempre carga la primera vez, cuando no está en modo de depuración para evitar mostrar Constantes.

Archivo script

    <scriptfile>example.script.php</scriptfile>

Un archivo script opcional (código PHP que se ejecuta antes, durante y/o después de la instalación, desinstalación y actualización) se puede definir mediante un elemento <scriptfile>. Este archivo debe contener una clase denominada "<element_name>InstallerScript" donde <element_name> es el nombre de la extensión (por ejemplo, com_componentname, mod_modulename, etc.). Los plugins requieren declarar el grupo (por ejemplo, plgsystempluginname). Los paquetes de biblioteca no son compatibles scriptfiles. La estructura de la clase es la siguiente:

class com_componentnameInstallerScript
{
	/**
	 * Constructor
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 */
	public function __construct(JAdapterInstance $adapter);
	
	/**
	 * Called before any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function preflight($route, JAdapterInstance $adapter);
	
	/**
	 * Called after any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function postflight($route, JAdapterInstance $adapter);
	
	/**
	 * Called on installation
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function install(JAdapterInstance $adapter);
	
	/**
	 * Called on update
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function update(JAdapterInstance $adapter);
	
	/**
	 * Called on uninstallation
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 */
	public function uninstall(JAdapterInstance $adapter);
}

Servidores de actualización

    <updateservers>
        <server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
        <server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
    </updateservers>

Los servidores de actualización pueden ser definidos en el elemento <updateservers>, un hijo del raíz. Este elemento puede contener uno o más elementos <server>, cada uno describiendo una ubicación para obtener las actualizaciones. Cada elemento <server> puede definir los siguientes atributos:

Atributo	Valores	Descripción
type	extension collection	El tipo de servidor de actualización
priority	integer	La prioridad del servidor de actualización
name	string	El nombre del servidor de actualización

Más información:

• Construir una extensión Joomla! 2.5 - Agregar un servidor de actualización
• Gestión de Actualizaciones de Componentes en Joomla! 2.5

Ejemplos

Para un ejemplo de la vida real, ver el manifiesto del componente Anuncios de la última versión de Joomla! 3.6.4.

El proceso de prueba de Joomla! usa varias extensiones para probar si el instalador funciona correctamente. Las últimas versiones de los manifiestos de estas extensiones son:

• com_weblinks manifest
• mod_weblinks manifest
• plg_search_weblinks manifest
• tpl_protostar manifest (3.6.4)
• en-GB manifest (3.6.4)