Joomla! Documentation™

Nota sui moduli dipendenti dai componenti

A volte i moduli (o i plugin e così via) utilizzano i modelli e gli helper di un componente e così via. In queste occasioni sarebbe bello poter confezionare il modulo in modo che venga disinstallato quando il componente stesso viene disinstallato. Questo si chiama gestione delle dipendenze che è stata voluta in Joomla ma non è ancora stata fatta. Si consiglia di seguire gli standard e di utilizzare un pacchetto come descritto di seguito.

Che cos'è un pacchetto?

Un pacchetto è un'estensione che viene utilizzata per installare più estensioni in una sola volta. Utilizzate un pacchetto se avete, per esempio, un componente e un modulo che dipendono l'uno dall'altro. La loro combinazione in un pacchetto permetterà all'utente di installare e disinstallare entrambe le estensioni in un'unica operazione. Le estensioni dei pacchetti possono essere utilizzate con Joomla e superiori.

Come creare un pacchetto?

A package extension is created by zipping all .zip files of the extensions together with a .xml manifest file. For example, if you have a package composed of:

• component helloworld
• module helloworld
• library helloworld
• system plugin helloworld
• template helloworld

The package should have the following tree in your zip file:

 -- pkg_helloworld.xml
 -- packages <dir>
     |-- com_helloworld.zip
     |-- mod_helloworld.zip
     |-- lib_helloworld.zip
     |-- plg_sys_helloworld.zip
     |-- tpl_helloworld.zip
 -- pkg_script.php

The pkg_helloworld.xml could have the following contents:

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

When you zip this and install it, you will see that all extensions will be installed. The package will be visible in the extension list so that a user might uninstall all extensions contained in the package.

Remember to use the package uninstaller instead of individual subpackage uninstallers to avoid orphan extension entries in the extension manager.

Id = <file id="not_arbitrary">

The id element in <file ..> tag is not arbitrary! The id= should be set to the value of the element column in the #__extensions table. If they are not set correctly, upon uninstallation of the package, the child file will not be found and uninstalled.

Plugin "group" attribute

The group attribute is required for the package installer to locate the plugin for uninstall. Group refers to the <folder> name specified in the plugin manifest file.

Manifest Filename and Packagename

The naming of the manifest file and the ability to uninstall the package file itself are closely related. The manifest file must have a pkg_ prefix. The remainder of the manifest name (without the .xml extension) is to be used as <packagename>. Or, the other way around, a package you want to identify as blurpblurp_J3 gets that as its <packagename> and should be in a manifest file named pkg_blurpblurp_J3.xml. Failure to do so will make it impossible to uninstall the package itself.

An optional <pkg_script.php> which contains a class pkg_<packagename>InstallerScript with public function postflight can be used. (This works in Joomla! 3.6 and later).

Extension Tag

As of Joomla! 3.4, you should include method="upgrade" in the <extension> tag if you want your package to succeed in updating itself on subsequent installations.

The version attribute of the <extension> tag should be set to the minimum supported version of Joomla for this package. For example, if your package only supports Joomla! 3.2 and above, set this to 3.2.

Note: This version attribute is purely optional. It has no influence on Joomla's installation routine. As of Joomla 4, the version attribute has therefore been removed from all core extensions. See pull request 29960 on github.com

Extension Uninstall Dependency

As of Joomla! 3.7.0, a package extension can declare that its child elements cannot be uninstalled independently with a <blockChildUninstall>true</blockChildUninstall> element in the package manifest. If your package needs all its extensions to operate effectively, set this to true or 1.