Difference between revisions of "Package"
From Joomla! Documentation
m (Added category) |
(Yet another typo) |
||
| (9 intermediate revisions by 7 users not shown) | |||
| Line 1: | Line 1: | ||
| − | == | + | <noinclude><languages /></noinclude> |
| + | <translate> | ||
| + | == Note on component dependant modules== <!--T:1--> | ||
| − | + | <!--T:2--> | |
| + | Sometimes modules (or plugins etc.) use a component's models and helpers and such. In these occasions it would be nice to be able to package your module in this way that it gets uninstalled when the component itself gets uninstalled. This is called dependency management which has been desired in joomla but hasn't been done yet. | ||
| + | It is suggested to follow the standards and just using a package as is described below. | ||
| + | </translate> | ||
| − | == | + | <translate> |
| + | == What is a package? == <!--T:3--> | ||
| − | A package extension is created by zipping all zip files of the extensions together with a xml manifest file. | + | <!--T:4--> |
| + | A package is a extension that is used to install multiple extensions in one go. This is used if you have for example a component and a module that are depending on each other. Combining them in a package will let the user install and uninstall both extensions in one go. Package extensions can be used with Joomla {{JVer|2.5}} and higher. | ||
| + | </translate> | ||
| + | |||
| + | <translate> | ||
| + | == How do I create a package? == <!--T:5--> | ||
| + | |||
| + | <!--T:6--> | ||
| + | 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 by: | ||
| + | </translate> | ||
| + | |||
| + | <translate> | ||
| + | <!--T:7--> | ||
| + | * '''component''' helloworld | ||
| + | * '''module''' helloworld | ||
| + | * '''library''' helloworld | ||
| + | * '''system plugin''' helloworld | ||
| + | * '''template''' helloworld | ||
| + | |||
| + | <!--T:8--> | ||
| + | The package should have the following tree in your zipfile: | ||
| + | </translate> | ||
-- pkg_helloworld.xml | -- pkg_helloworld.xml | ||
| Line 11: | Line 38: | ||
|-- com_helloworld.zip | |-- com_helloworld.zip | ||
|-- mod_helloworld.zip | |-- mod_helloworld.zip | ||
| + | |-- lib_helloworld.zip | ||
| + | |-- plg_sys_helloworld.zip | ||
| + | |-- tpl_helloworld.zip | ||
| + | <translate> | ||
| + | <!--T:9--> | ||
The pkg_helloworld.xml could have the following contents: | The pkg_helloworld.xml could have the following contents: | ||
| + | </translate> | ||
<source lang="xml"> | <source lang="xml"> | ||
| Line 18: | Line 51: | ||
<extension type="package" version="1.6"> | <extension type="package" version="1.6"> | ||
<name>Hello World Package</name> | <name>Hello World Package</name> | ||
| + | <author>Hello World Package Team</author> | ||
| + | <creationDate>May 2012</creationDate> | ||
<packagename>helloworld</packagename> | <packagename>helloworld</packagename> | ||
<version>1.0.0</version> | <version>1.0.0</version> | ||
| Line 26: | Line 61: | ||
<update>http://www.updateurl.com/update</update> | <update>http://www.updateurl.com/update</update> | ||
<files folder="packages"> | <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> | </files> | ||
</extension> | </extension> | ||
</source> | </source> | ||
| + | <translate> | ||
| + | <!--T:10--> | ||
When you zip this and try to install it, you will see that every extension will be installed. Also the package will be visible in the extension list to uninstall all the extension of this package. | When you zip this and try to install it, you will see that every extension will be installed. Also the package will be visible in the extension list to uninstall all the extension of this package. | ||
| + | </translate> | ||
| + | |||
| + | <translate> | ||
| + | <!--T:11--> | ||
| + | Remember to use the package uninstaller instead of individual subpackage uninstallers to avoid orphan extension entries in the extension manager. | ||
| + | </translate> | ||
| + | |||
| + | <translate> | ||
| + | === Id= <file id="not_arbitrary"> === <!--T:12--> | ||
| + | The id element in <file ..> tag are 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 uninstalling of the package the children ( <file> ) will NOT be found and uninstalled. | ||
| + | </translate> | ||
| + | |||
| + | <translate> | ||
| + | === Manifest filename and packagename === <!--T:13--> | ||
| + | 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 .xml extension ) is to be used as <packagename>. Or, the other way around, a package you want to identify as "blurpblurp_J3" get 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. | ||
| + | </translate> | ||
| − | [[Category:Extensions | + | <translate> |
| + | <!--T:14--> | ||
| + | [[Category:Extensions]] | ||
| + | </translate> | ||
Revision as of 14:32, 18 December 2014
Note on component dependant modules[edit]
Sometimes modules (or plugins etc.) use a component's models and helpers and such. In these occasions it would be nice to be able to package your module in this way that it gets uninstalled when the component itself gets uninstalled. This is called dependency management which has been desired in joomla but hasn't been done yet. It is suggested to follow the standards and just using a package as is described below.
What is a package?[edit]
A package is a extension that is used to install multiple extensions in one go. This is used if you have for example a component and a module that are depending on each other. Combining them in a package will let the user install and uninstall both extensions in one go. Package extensions can be used with Joomla 
and higher.
How do I create a package?[edit]
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 by:
- component helloworld
- module helloworld
- library helloworld
- system plugin helloworld
- template helloworld
The package should have the following tree in your zipfile:
-- pkg_helloworld.xml
-- packages <dir>
|-- com_helloworld.zip
|-- mod_helloworld.zip
|-- lib_helloworld.zip
|-- plg_sys_helloworld.zip
|-- tpl_helloworld.zip
The pkg_helloworld.xml could have the following contents:
<?xml version="1.0" encoding="UTF-8" ?>
<extension type="package" version="1.6">
<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>
<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 try to install it, you will see that every extension will be installed. Also the package will be visible in the extension list to uninstall all the extension of this 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">[edit]
The id element in <file ..> tag are 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 uninstalling of the package the children ( <file> ) will NOT be found and uninstalled.
Manifest filename and packagename[edit]
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 .xml extension ) is to be used as <packagename>. Or, the other way around, a package you want to identify as "blurpblurp_J3" get 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.