Package (Paquet)
From Joomla! Documentation
Note concernant les modules liés à un composant
Il arrive que des modules (ou des plugins, etc.) utilisent les modèles et les aides d'un composant. Dans ces cas-là, il serait intéressant de pouvoir empaqueter votre module de manière à ce qu'il soit désinstallé lorsque le composant lui-même est désinstallé. C'est ce qu'on appelle la gestion des dépendances, qui a été souhaitée dans Joomla mais qui n'a pas encore été réalisée. Il est suggéré de suivre les standards et d'utiliser un paquetage tel que décrit ci-dessous.
Qu'est ce qu'un package ?
Un package est une extension qui est utilisée pour l'installation de différentes extensions en une fois. C'est le cas notamment lorsque vous avez un composant et un module qui sont en interaction. En les combinant dans un package, l'utilisateur pourra très simplement et d'un seul coup les installer et désinstaller. Les extensions Package peuvent être utilisées avec Joomla! et supérieur.
Comment puis-je créer un package ?
Un package d'extension se créer par la compression en un fichier zip de l'ensemble des fichiers d'une extension avec un fichier manifeste xml. Par exemple et si vous avez un package composé de :
- component helloworld
- module helloworld
- library helloworld
- system plugin helloworld
- template helloworld
Le package doit proposer l’arborescence suivante pour votre fichier .zip :
-- pkg_helloworld.xml -- packages <dir> |-- com_helloworld.zip |-- mod_helloworld.zip |-- lib_helloworld.zip |-- plg_sys_helloworld.zip |-- tpl_helloworld.zip -- pkg_script.php
Le contenu du fichier pkg_helloworld.xml pourrait être le suivant :
<?xml version="1.0" encoding="UTF-8" ?>
<extension type="package" version="1.6" method="upgrade">
<name>Hello World Package</name>
<author>Hello World Package Team</author>
<creationDate>May 2012</creationDate>
<packagename>helloworld</packagename>
<version>1.0.0</version>
<url>http://www.yoururl.com/</url>
<packager>Hello World Package Team</packager>
<packagerurl>http://www.yoururl.com/</packagerurl>
<description>Example package to combine multiple extensions</description>
<update>http://www.updateurl.com/update</update>
<scriptfile>pkg_script.php</scriptfile>
<files folder="packages">
<file type="component" id="com_helloworld" >com_helloworld.zip</file>
<file type="module" id="helloworld" client="site">mod_helloworld.zip</file>
<file type="library" id="helloworld">lib_helloworld.zip</file>
<file type="plugin" id="helloworld" group="system">plg_sys_helloworld.zip</file>
<file type="template" id="helloworld" client="site">tpl_helloworld.zip</file>
</files>
</extension>
Lorsque vous zippez ceci et tentez de l'installer, vous verrez que chaque extension sera installée. De plus, le package sera visible dans la liste des extensions pouvant être désinstallées.
N'oubliez pas d'utiliser la désinstallation du package entier au lieu des programmes de désinstallation de chacun des sous-paquets pour éviter que des extensions orphelines ne restent présentes dans le gestionnaire des extensions.
Id= file id="not_arbitrary">
L'id de l'élément dans la balise <file ..> n'est absolument PAS arbitraire ! La valeur de id= doit être paramétrée sur celle de la colonne element de la table #__extensions. Si elles ne sont pas définies correctement et lors de la désinstallation du package, les enfants file ne seront pas trouvés et désinstallés.
Attribut "group" du Plugin "group"
L'attribut group est nécessaire pour que le programme d'installation du package puisse localiser le plugin à désinstaller. Le groupe fait référence au nom <folder> spécifié dans le fichier manifeste du plugin.
Nom du fichier manifeste et nom du package
Les nommage du fichier manifeste et la capacité du package à se désinstaller par lui-même sont étroitement liés. Le manifeste de fichier doit utiliser le préfixe "pkg_", puis le reste du nom du manifeste (sans l'extension .xml ) est utilisé comme <nomdupackage>. Ou, à l'inverse, un package que vous souhaitez identifier comme "blurpblurp_J3" sera alors nommé "pkg_blurpblurp_J3.xml". À défaut d'agir de la sorte, il sera impossible de désinstaller le package lui-même.
Le fichier facultatif <pkg_script.php> contient une classe pkg_<packagename>InstallerScript avec une fonction publique postflight qui peut être utilisée (fonctionne à partir de Joomla! 3.6).
Tag d'extension
Concernant Joomla! 3.4, vous devez intégrer method="upgrade" dans la balise <extension> si vous souhaitez que votre paquet réussisse sa propre mise à jour pour les installations ultérieures.
L'attribut de version pour la balise <extension> doit être celle de la version Joomla! minimale prise en charge pour ce paquet. Par exemple, si votre paquet supporte uniquement Joomla! 3.2 et au-delà, il faudra préciser : 3.2.
Note : Cet attribut version est purement facultatif. Il n'a aucune influence sur la routine d'installation de Joomla. À partir de Joomla 4, l'attribut version a donc été supprimé de toutes les extensions de base. Voir la pull-request 29960 sur github.com
Dépendance de désinstallation de l'extension
Depuis Joomla! 3.7.0, un paquet d'extension peut déclarer que ses éléments enfant ne puissent pas être désinstallés indépendamment au travers de l'élément <blockChildUninstall>true</blockChildUninstall> dans le manifest du paquet. Si votre paquet a besoin de toutes ses extensions pour fonctionner efficacement, mettez cette valeur à true ou 1.