Fichiers manifest

From Joomla! Documentation

Revision as of 09:19, 22 July 2015 by MATsxm (talk | contribs) (Created page with "Un '''fichier de script''' (code PHP qui est exécuté avant, pendant et/ou après l'installation, la désinstallation ou la mise à jour) peut, en option, être défini à l'...")
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎italiano • ‎中文（台灣）‎
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:

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

Stop hand nuvola.svg.png
Warning!

Les composants ne prennent pas en charge les définitions de configuration dans le manifeste. Ceci avait été mis en œuvre dans Joomla! 1.5. Ils est possible de définir les options de configuration pour différents niveaux à l'aide des métadonnées de configuration de composant.

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 la version Joomla 3.x. 

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

Depuis Joomla! 1.6, il est conseillé de placer les fichiers langue de votre extension dans le dossier même de votre extension. Joomla! chargera alors automatiquement les fichiers langue depuis votre extension.

En plaçant les fichiers langue dans le dossier de l'extension, vous permettez ainsi de les isoler et donc de les protéger. Par exemple, dans le cas ou un administrateur supprimerait une langue de son installation Joomla. Dans ce cas, les fichiers langue de l'extension ne seront pas supprimés. Ils resteront alors en place et ne seront accessibles que si la langue est installée à nouveau.

La structure du dossier de langue pour le frontend et le backend est identique. Il convient de les placer dans la balise <languages> (par exemple en-GB) pour chaque langue et dans le dossier comme suit : language/en-GB/. Vous devez spécifier ces dossiers pour le frontend et le backend.

Dans votre manifest, il suffit simplement d'inclure votre dossier <language> dans la section fichiers, les sous-répertoires pour chaque langue seront alors automatiquement copiés. À l'intérieur des groupes <files>, il vous suffit d'ajouter une balise <folder> à côté des éléments dans le groupe <files>, comme indiqué dans cet exemple : 

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

Tous les fichiers .ini présent dans le dossier du noyau ont la priorité sur les fichiers dans les dossiers langue des extensions. Par exemple, si il existe, un fichier sys.ini d'un dossier du noyau sera toujours chargé en backend, sauf lors de l'installation d'une extension qui contient son propre fichier sys.ini dans un dossier de langue. Dans ce cas et uniquement ce cas, le fichier sys.ini dans le dossier de l'extension affichera son contenu traduit au moment de l'installation. C'est très pratique car un développeur peut avoirdeux fichiers sys.ini avec un contenu différent. Une description lors de la réussite de l'installation ainsi, ainsi qu'un tutoriel en backend par exemple.

Il est également beaucoup plus facile pour un utilisateur ayant besoin de trouver le fichier .ini d'une extension qui n'est pas disponible dans sa langue de l'ajouter dans le dossier principal. Aucun risque alors qu'il ne soit supprimé en cas de désinstallation par erreur de l'extension.

Veuillez consulter également :

Au cours du développement, vous pouvez vous activer le système de débogage de langue dans la configuration globale Joomla. Ainsi, vous pourrez découvrir si des problèmes se posent. Depuis Joomla 3.2, cela est nécessaire afin d'aider à déboguer le en-GB qui est toujours chargé en premier lorsque l'on est pas en mode de débogage et ainsi empêcher l'affichage des constantes.

Fichier de script

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

Un fichier de script (code PHP qui est exécuté avant, pendant et/ou après l'installation, la désinstallation ou la mise à jour) peut, en option, être défini à l'aide d'une balise <scriptfile>. Ce fichier doit contenir une classe nommée '<element_name>InstallerScript où <element_name> est le nom de votre extension (par exemple : com_nomducomposant, mod_nomdumodule, etc.). Pour les plugins, il convient de nommer également le groupe (par exemple : plgsystemnomduplugin). Les packages de bibliothèque ne prennent pas en charge les fichiers scripts. La structure de la classe sera comme suit : 

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 :

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:

Contributeurs

Retrieved from "https://docs.joomla.org/index.php?title=Manifest_files/fr&oldid=207122"