Manifest files/fr

Joomla! 

3.x

Joomla! 

≥ 2.5

Avec Joomla, toutes les extensions proposent des fichiers manifestes. Ces fichiers recouvrent les informations générales concernant l'installation, ainsi que des paramètres pour la configuration de l'extension elle-même. Depuis Joomla! 2.5, il existe très peu de différences entre les différents formats de fichiers manifestes en fonction des différents types d'extensions permettant ainsi à chaque type de bénéficier de la puissance de l'installateur Joomla.

Les conventions de nommage

Le fichier doit être nommé manifest.xml ou <extension_name>.xml et situé dans le répertoire racine de l'installation du package.

Syntaxe

L'élément racine

La balise principale du fichier d'installation est :

<extension></extension>

Ces balises ouvrantes et fermantes sont maintenant valables pour toutes les extensions. La nouvelle balise <extension> remplace les anciennes <install></install> depuis Joomla! 1.5. Les attributs suivants sont autorisés à l'intérieur de la balise :

Attribut	Valeurs	Applicable à	Description
type	component file language library module package plugin template	Toutes les extensions	Cet attribut décrit à l'installateur le type de l'extension. En fonction de ce type, d'autres d'exigences supplémentaires s'appliqueront aux sous-balises.
version	2.5 3.0	Toutes les extensions	Chaîne de caractères qui identifie la version de Joomla! pour laquelle cette extension est développée.
method	install upgrade	Toutes les extensions	La valeur par défaut install sera également utilisée si l'attribut method n'est pas utilisé. La valeur install signifie que l'installateur va s'arrêter s'il trouve un fichier/dossier de la nouvelle extension.
client	site administrator	Modules	L'attribut client permet de préciser pour quel type de client d'application le nouveau module est disponible.
group	string	Plugins	Le nom du groupe indique pour quels groupes de plugins le nouveau plugin est disponible. Les groupes existants sont les noms de dossier du répertoire /plugins. Le programme d'installation va créer de nouveaux noms de dossier pour les noms de groupe qui n'existent pas encore.

Métadonnées

Les éléments suivants peuvent être utilisés pour insérer des métadonnées. Aucun de ces éléments n'est obligatoire et s'ils sont présents, ils doivent être un enfant de l'élément racine.

<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)

Remarque : les balises <name> et <description> sont des champs traduisibles de sorte que le nom et la description de l'extension pourront être présents dans la langue maternelle de l'utilisateur.

Fichiers de frontend

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

Les fichiers à copier dans le répertoire de frontend doivent être placés dans les balises <files>. Vous pouvez utiliser l'attribut folder en option pour spécifier un répertoire du package ZIP. Chaque fichier à copier doit être nommé par l'élément <filename>. Si vous souhaitez copier un dossier entier à la fois, vous pouvez le définir comme un <folder>.

Fichiers multimédias

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

Cet exemple permet de copier le fichier (/media/com_example_logo.png) et les dossiers ( /media/css/ et /media/js/ ) listés vers /media/com_example/, ainsi que la création du dossier com_example si nécessaire. Vous pouvez utiliser en option l'attribut folder pour spécifier un répertoire dans le package ZIP à partir duquel réaliser la (dans ce cas, media).

Les extensions doivent stocker les éléments, dont elles ont besoin pour être accessible sur le web (JS, CSS, images, etc), dans media. Cette fonctionnalité a été ajoutée dans le cadre du projet de développement d'une interface multi-site et du placement éventuel de fichiers de code (PHP) en dehors des espaces web serveurs accessibles.

Ref:

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

Section de l'administration

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

La section d'administration est définie par l'élément <administration>. Puisque seuls les composants concernent à la fois l'espace site et celui d'administration, seuls les manifests pour composants doivent intégrer ces éléments.

Fichiers de backend

Les fichiers à copier dans le répertoire de backend doivent être placés dans l'élément <files> sous <administration>. Vous pouvez utiliser l'attribut optionnel folder pour spécifier un répertoire à copier depuis le pack ZIP. Voir les fichiers frontend pour plus d'informations.

Liens de Menu et sous-menus

Note de version : avant Joomla! 3.4 il n'était pas nécessaire d'avoir une balise de menu dans votre fichier XML pour que le menu soit créé. Ce bug a été corrigé dans Joomla! 3.4 et ainsi, si aucun élément de menu a été créé, alors aucun élément du menu d'administration ne sera créé pour le composant.

	<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>

Le texte pour l'élément du menu principal pour le composant est défini dans la balise <menu>, enfant de de la balise <administration>. Une balise <submenu> peut être présente (également comme enfant de <administration>), qui pourra contenir d'autres éléments de menu définis par <menu>.

En outre, chaque élément <menu> permet de définir les attributs suivants :

Attribut	Description
link	Un lien vers lequel renvoyer l'utilisateur lorsque l'élément de menu est cliqué.
img	Le chemin (relatif) à une image (16x16 pixels) qui apparait à côté de l'élément de menu. Doit être url compatible (par exemple sans espaces).
alt
string	Un paramètre URL à ajouter au lien. Par exemple, <menu view="cpanel">COM_EXAMPLE</menu> dans le manifest XML com_example générerait l'URL de l'élément de menu index.php?option=com_example&view=cpanel.

La valeur à l'intérieur de la balise est le nom du menu. À La différence de ce qui se faisait pour Joomla! 1.5, vous ne pouvez pas utiliser une chaîne de caractère dans votre langue naturelle. Par exemple, si vous renseignez "Composant d'exemple" au lieu de COM_EXAMPLE, votre nom de composant qui s'afficherait en titre serait "composant-d-exemple" et vous seriez dans l'impossibilité de le traduire. Pour réaliser une traduction, vous devez créer un fichier nommé fr-FR.com_example.sys.ini (NDT : avant de pouvoir créer le fichier fr-FR, il convient de créer le fichier d'origine en-GB) dans administrator/languages/fr-FR (vous pouvez utiliser la balise manifest <languages> pour qu'il soit copié lors de l'installation) ou dans administrator/components/com_example/language/fr-FR. Dans ce dernier cas, vous ne devez pas inclure le fichier de traduction dans la balise <languages> balise. Tant que vous aurez placé le répertoire de langue dans vos balises <files>, il sera copié lors de l'installation du composant.

Le contenu de ce fichier devrait être :

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

Veuillez noter que la chaîne de langue doit être placée entre des guillemets doubles, comme c'est le standard pour les traductions Joomla. Remarque : depuis Joomla! 1.6, le classement des éléments de menu des composants est basé sur la traduction de la clé présente dans le manifest XML. Cela signifie que l'ordre de tri sera correct, quelque soit le nom donné à votre clé de traduction et quelque soit la langue dans laquelle le site est affiché. Joomla! 1.6 a permis de corriger les erreurs dans l'agencement des menus de composants sous Joomla! 1.5.

Configuration

Warning!

La balise <config>, enfant de la racine, décrit les options de configuration de l'extension. En cas de besoin, les options seront affichées par le gestionnaire concerné (gestionnaire de plugins, gestionnaire de modules ou gestionnaire de templates). Les options de configuration peuvent également être définies dans un fichier séparé nommé config.xml. Son élément racine doit être <config>.

Chaque groupe de champs <fieldset> peut contenir un ou plusieurs éléments <field> (champ), chacun représentant un seul champ de formulaire avec une étiquette. Consultez les types de champs pour formulaires standards pour une liste des types de champs autorisés et un exemple de définitions de champs de formulaire XML.

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>

Dans l'exemple ci-dessus, nous avons placé les fichiers SQL dans le répertoire admin/sql du paquet d'installation. Vous devez inclure le dossier sql dans les fichiers d'administration (tel que décrit dans "les fichiers backend").

Vous pouvez exécuter SQL lors de l'installation et/ou la désinstallation à l'aide des éléments <install> et <uninstall>. Une balise <sql> doit apparaître comme un enfant de ces éléments. <sql> peut contenir n'importe quel nombre d'éléments <file>, chacun devant définir un seul fichier SQL à exécuter. Leurs types de pilote de base de données sont décrits par l'attribut driver, leurs jeux de caractères par l'attribut charset.

Mise à jour du schéma SQL

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

Depuis la version 1.6, une balise <update> est disponible et vous permet de fournir une série de fichiers SQL pour mettre à jour le schéma actuel.

Fichiers langue

Dans Joomla! 1.5, les développeurs d'extensions devaient placer les fichiers de langue dans le fichier général de s langues de Joomla! à l'aide des balises <langues>...</langues> comme indiqué ci-dessous. Cette méthode peut toujours être utilisée avec .

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

Since Joomla! 1.6 it has been encouraged placing your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.

By storing extension language files in the extension folder, you gain the benefit of isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed again.

The structure of the language folder for frontend and backend is the same. You put them in the language tag (e.g. en-GB ) of each language in your language folder i.e. language/en-GB/. You have to specify those folders in the front-end and back-end files too.

In your manifest you simply include the 'language' folder in your files section, the sub-directories for each language automatically be copied. Inside the <files> group you simply add a <folder> element alongside the items in the <files> group as shown in this example:

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

Il convient également de noter que les deux techniques peuvent fonctionner ensemble. Voici un exemple du noyau :

<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>

Les avantages pour cette solution sont les suivants :

All ini files present in the core folder have precedence over the files in the extension language/ folder. For example a sys.ini file will always be loaded from core folders in back-end if it exists, except when installing an extension which contains a sys.ini file in a language folder. In that case and only that case, the sys.ini file in the extension folder will display its translated content at install time. This is very handy as a developer can have 2 sys.ini files with different contents. A description of the successful install as well as a tutorial in back-end for example.

Also, it is much easier for a user needing an ini file for an extension that does not provide it in the language desired, to add it in the main folders. No risk for it to be deleted in case of uninstalling the extension by mistake or any other reason.

Veuillez consulter également :

• Créer un pack langue hors du noyau
• Créer un pack langue pour une extension Joomla! 2.5

During development you can turn on language debugging in the Joomla! global configuration. So you can investigate if a problems arises. As of 3.2, this is necessary to help debug as en-GB is always loaded first when not in debug mode to prevent displaying Constants.

Fichier de script

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

An optional script file (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <scriptfile> element. 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 requires to state the group (e.g. plgsystempluginname). Library packages do not support scriptfiles. The structure of the class is as follows:

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);
}

Serveurs de mise à jour

    <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>

Update servers can be defined in the <updateservers> element, a child of the root. This element may contain one or more <server> element, each describing a location to fetch updates from. Each <server> item can define the following attributes:

Attribut	Valeurs	Description
type	extension collection	Le type de serveur de mise à jour.
priority	integer	La priorité du serveur de mise à jour.
name	string	Le nom du serveur de mise à jour.

Pour plus d'informations :

• Création d'une extension Joomla! - Ajout d'un serveur de mise à jour
• Gestion des mises à jour de composants pour Joomla! 2.5

Exemples

Pour un exemple, veuillez consulter le manifest pour le composant bannière de la version Joomla! 2.5.

The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:

• com_alpha manifest
• mod_alpha manifest
• plg_system_alpha manifest
• tpl_simple manifest
• lng_xx-XX manifest

Contributeurs

• Alex Kempkens
• Daniel Peraza
• Nicholas K. Dionysopoulos
• Prasit Gebsaap
• Craig Phillips