Archivos de manifiesto
From Joomla! Documentation
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.
Joomla 4.x: Automatic namespace mapping will fail if a manifest file named manifest.xml is used. See: https://github.com/joomla/joomla-cms/issues/37750
Sintaxis
Elemento raíz
The new tag <extension> replaces the old <install></install> from Joomla 
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 | componentfilelanguagelibrarymodulepackageplugintemplateelement |
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.53.0 |
Todas las extensiones | Cadena que identifica la versión de Joomla! para la cual la extensión se desarrolla. |
| method | installupgrade |
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 | siteadministrator |
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:
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
<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 & for the file to be valid
XML and be parsed by the installer
-->
<menu link="anoption=avalue&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 | |
| view | Un parámetro de URL para añadir el enlace. Por ejemplo, |
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"Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards.
Dashboards
This code only works in 
and later
Specifies the details for displaying a dashboard for the component in the Administrator area for the site.
- It will make a dashboard icon appear next to the administrator menu item for the component
- The dashboard icon will click through to display modules assigned to the cpanel-example administrator module position
- The title and icon defined in the XML file will be used as the header and icon at the top of the component's dashboard page.
<dashboards>
<dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="icon-lock">example</dashboard>
</dashboards>Configuración
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.
Namespace
This code only works in and later
Specify the namespace to be used for autoloading the plugin. The given namespace will autoload to the root directory of your extension by default however you can optionally add a "path" attribute to the namespace element to specify a subpath within your extensions root directory.
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.sqlArchivos similares deben ser creados para versiones posteriores.
Archivos de idioma
.
<!-- Joomla! 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:
This file should contain a class named "<element_name>InstallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins must state the group (e.g. plgsystempluginname).
In and later the structure of the class is as follows:
<?php
use Joomla\CMS\Installer\InstallerAdapter;
class com_componentnameInstallerScript
{
/**
* Constructor
*
* @param InstallerAdapter $adapter The object responsible for running this script
*/
public function __construct(InstallerAdapter $adapter)
{
}
/**
* Called before any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function preflight($route, InstallerAdapter $adapter)
{
return true;
}
/**
* Called after any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function postflight($route, $adapter)
{
return true;
}
/**
* Called on installation
*
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function install(InstallerAdapter $adapter)
{
return true;
}
/**
* Called on update
*
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function update(InstallerAdapter $adapter)
{
return true;
}
/**
* Called on uninstallation
*
* @param InstallerAdapter $adapter The object responsible for running this script
*/
public function uninstall(InstallerAdapter $adapter)
{
return true;
}
}
?>Note that since Joomla 3.6 Joomla has shipped a basic script that you can use instead of shipping your own from scratch JInstallerScript which contains various helper methods commonly used through the community.
Library Manifests
The section is based on and later
A simple library manifest might look like this:
<?xml version="1.0" encoding="utf-8"?>
<extension type="library" method="upgrade" version="4.0">
<name>My Test library.</name>
<libraryname>mytest</libraryname>
<files>
<folder>Classes</folder>
<folder>language</folder>
<filename>mytest.php</filename>
</files>
</extension>This will install the library into the JPATH_SITE/libraries/mytest folder.
What if your company has several libraries and you want to group them together under folder JPATH_SITE/libraries/mycompany?
Simple - include your company name in the libraryname property of each library like this:
<libraryname>mycompany/mylibrary1</libraryname> <libraryname>mycompany/mylibrary2</libraryname>These libraries will then be installed in the JPATH_SITE/libraries/mycompany/mylibrary1 and JPATH_SITE/libraries/mycompany/mylibrary2 folders.
Uninstalling mylibrary1 will still leave mylibrary2 installed on your site.
When using script files with such company libraries the installer class name should look like this:
class mycompanymylibrary1InstallerScriptclass mycompanymylibrary2InstallerScriptServidores 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 | extensioncollection |
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:
Supporting Download Keys
As of Joomla 4.0.0 users can enter their download keys in the Update Sites list. This gives them a single place to manage the download keys. When a user is going to update an extension, Joomla will check if there is a download key. If there is a download key, Joomla will add the download key to the update URL.
To support download keys you must include the dlid tag in the manifest file. The dlid tag takes 2 arguments:
- prefix
- suffix
The dlid tag will look like this in your manifest file:
<dlid prefix="dlid=" suffix="&dummy=my.zip"/>The prefix will be added before the download key and the suffix after the download key. Using the example above the full query added to the download link will be:
dlid=KEY&dummy=my.zipThe key is added before the onInstallerBeforePackageDownload event is triggered, so the full URL will be passed to the event.
Ejemplos
Para un ejemplo de la vida real, ver el manifiesto del componente Anuncios de la última versión de Joomla! 3.6.4.
Se pueden encontrar más ejemplos en el repositorio de enlaces web independientes: