Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the [[extension]] itself. Since Joomla! 1.6 {{JVer|1.6}}, there are very few differences between the manifest file formats for the different [[Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.

+

Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the [[extension]] itself. Since Joomla! 2.5 {{JVer|2.5}}, there are very few differences between the manifest file formats for the different [[Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.

==Naming conventions==

==Naming conventions==

Line 13:

Line 12:

<source lang=xml><extension></extension></source>

<source lang=xml><extension></extension></source>

−

This starting and closing tags are now valid for all extensions. The new tag <extension> replaces the old <install></install> from Joomla {{JVer|1.5}}. The following attributes are allowed within the tag:

+

This starting and closing tags are now valid for all extensions. The new tag <code><extension></code> replaces the old <code><install></install></code> from Joomla {{JVer|1.5}}. The following attributes are allowed within the tag:

| This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.

| This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.

|-

|-

| version

| version

−

| <code>1.6</code> || All extensions

+

| <code>2.5</code><br /><code>3.0</code> || All extensions

−

| String that identifies the version of Joomla for which this extension is developed. For Joomla 1.6 a version higher than 1.5 is required.

+

| String that identifies the version of Joomla for which this extension is developed.

|-

|-

| method

| method

−

| <code>new</code><br /><code>upgrade</code> || All extensions

+

| <code>install</code><br /><code>upgrade</code> || All extensions

−

| The default value install will be also used if the method attribute is not used. In these cases the installer will gracefully stop if he finds any existing file/folder of the new extension

+

| The default value <code>install</code> will be also used if the method attribute is not used. The <code>install</code> value means the installer will gracefully stop if it finds any existing file/folder of the new extension.

|-

|-

| client

| client

| <code>site</code><br /><code>administrator</code> || Modules

| <code>site</code><br /><code>administrator</code> || Modules

−

| The client allows to specify for which application client the new module is available.

+

| The client attribute allows you to specify for which application client the new module is available.

|-

|-

| group

| group

Line 38:

Line 37:

| The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory <tt>/plugins</tt>. The installer will create new folder names for group names that do not exist yet.

| The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory <tt>/plugins</tt>. The installer will create new folder names for group names that do not exist yet.

|}

|}

+

=== Metadata ===

=== Metadata ===

Line 43:

Line 43:

The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.

The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.

* <code><version><code> &ndash; the version number of the extension (e.g. <code>1.6.0</code>)

+

<authorUrl> &ndash; URL to the author's website (e.g. www.joomla.org)

−

* <code><description></code> &ndash; the description of the component. This is a translatable field. (e.g. <code>COM_BANNERS_XML_DESCRIPTION</code>)

+

<version> &ndash; the version number of the extension (e.g. 1.6.0)

+

<description> &ndash; the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)

+

</pre>

+

+

Note: The <name> and <description> tags are also translatable fields so that the name and description of the extension can be shown to the user in their native language.

=== Front-end files ===

=== Front-end files ===

<source lang="xml">

<source lang="xml">

−

<files folder="from-folder">

+

<files folder="from-folder">

−

<filename>example.php</filename>

+

<filename>example.php</filename>

−

<folder>examples</folder>

+

<folder>examples</folder>

−

</files>

+

</files>

</source>

</source>

Line 65:

Line 69:

=== Media files ===

=== Media files ===

+

<source lang="xml>

<source lang="xml>

−

<media destination="com_example">

+

<media folder="media" destination="com_example">

−

<filename>com_example_logo.png</filename>

+

<filename>com_example_logo.png</filename>

−

<folder>css</folder>

+

<folder>css</folder>

−

<folder>js</folder

+

<folder>js</folder>

−

</media>

+

</media>

</source>

</source>

−

This example will copy the file(s) (com_example_logo.png) and folders ( /css/ and /js/ ) listed to <code>/media/com_example/</code>. Creating the <code>com_example</code> folder if required.

+

This example will copy the file(s) (<tt>/media/com_example_logo.png</tt>) and folders ( <tt>/media/css/</tt> and <tt>/media/js/</tt> ) listed to <tt>/media/com_example/</tt>, creating the <tt>com_example</tt> folder if required. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from''' (in this case, <tt>media</tt>).

Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in <code>media</code>. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.

Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in <code>media</code>. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.

Line 84:

Line 89:

<source lang="xml">

<source lang="xml">

−

<administration>

+

<administration>

+

<!-- various elements -->

+

</administration>

</source>

</source>

Line 96:

Line 103:

<source lang="xml">

<source lang="xml">

−

<menu>COM_EXAMPLE</menu>

+

<menu>COM_EXAMPLE</menu>

−

<submenu>

+

<submenu>

−

<menu link="anoption=avalue">COM_EXAMPLE_SUBMENU_ANOPTION</menu>

+

<menu link="anoption=avalue">COM_EXAMPLE_SUBMENU_ANOPTION</menu>

−

<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>

+

<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>

−

</submenu>

+

</submenu>

</source>

</source>

−

The text for the main menu item for the component is defined in the <code><menu><code> item, a child of <code><administration></code>. A <code><submenu></code> element may also be present (also a child of <code><administration></code>), which may contain more menu items defined by <code><menu></code>.

+

The text for the main menu item for the component is defined in the <code><menu></code> item, a child of <code><administration></code>. A <code><submenu></code> element may also be present (also a child of <code><administration></code>), which may contain more menu items defined by <code><menu></code>.

Additionally, each <code><menu></code> item can define the following attributes:

Additionally, each <code><menu></code> item can define the following attributes:

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards. Important note: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu for the majority (non-English speaking!) of Joomla! users experienced under Joomla! 1.5.

+

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards. Important note: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu experienced under Joomla! 1.5 for the majority (non-English speaking!) of Joomla! users.

You can execute SQL during installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. An <code><sql></code> element should appear as a child of these elements. <code><sql></code> can contain any number of <code><file></code> elements, each defining a single SQL file to execute. Their database driver types are described by the <code>driver</code> attribute, their character sets by the <code>charset</code> attribute.

+

In the above example, we put the SQL files in the "admin/sql" folder of the installation package. You have to include the "sql" folder in the administration files.

+

+

You can execute SQL during the installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. A <code><sql></code> element should appear as a child of these elements. <code><sql></code> can contain any number of <code><file></code> elements, each defining a single SQL file to execute. Their database driver types are described by the <code>driver</code> attribute, their character sets by the <code>charset</code> attribute.

+

+

==== Update of the SQL schema ====

+

+

<source lang="xml">

+

<update>

+

<schemas>

+

<schemapath type="mysql">sql/updates/mysql</schemapath>

+

<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>

+

</schemas>

+

</update>

+

</source>

+

+

Since 1.6, there is also an <code><update></code> tag, which allows you to provide a series of SQL files to update the current schema.

=== Language files ===

=== Language files ===

−

Including the language INI files in your extension installation package is not sufficient. You have to tell Joomla! where to find them so that it can install them. This is done by means of up to two <languages> tags. In the case of a component, you need a <languages> tag both under the root tag (<manifest> or <install>) of the XML file (for the front-end translation files) and one inside the

+

In Joomla! 1.5, we put extension language files in the Joomla! main language file, using the <languages>..</languages> tag as shown below. '''This tag is considered to be deprecated since Joomla! 1.6.''' We encourage you to put extension 's language files in the extension folder and Joomla! is responsible for the loading of required language files.

−

<administration> tag (for the back-end translation files). In both cases, the syntax looks like that:

+

<source lang="xml">

<source lang="xml">

+

<!-- Joomla! 1.5 language tag, deprecated since Joomla! 1.6 -->

<languages folder="langfiles">

<languages folder="langfiles">

<language tag="en-GB">en-GB.com_example.ini</language>

<language tag="en-GB">en-GB.com_example.ini</language>

Line 167:

Line 189:

</source>

</source>

−

The content of the folder attribute of this tag is the relative path of the directory holding the translation files. The path is relative to the your installation package, not the site's root. Each <language> tag '''must''' specify the ISO-code of the language in the tag attribute.

+

By storing extension language files in the extension folder, you gain benefits when removing a language from the Joomla! installation: As your language files will not be removed, when reinstall the language again you can use those files without installing them again.

−

You should not that, by default, the language files are not loaded during installation time unless you use a special convention.

+

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.

−

For components, you must place a directory named language inside your component's backend directory and make sure it's being installed, i.e. you have referenced it in your <administration> tag's <files> tag. For other extension types, create a directory named language inside your installation archive's root. In all cases, create one subdirectory per language and put your .sys.ini translation file in there. For example, if you have plg_content_example, create the file language/en-GB/en-GB.plg_content_example.sys.ini and put all installation-time messages' translations in there. This file will be loaded automatically by Joomla! right after all files have been copied and before running your script file and/or displaying the post-installation message (e.g. the extension's description).

+

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:

+

+

<source lang="xml">

+

<files>

+

<filename plugin="alpha">alpha.php</filename>

+

<folder>sql</folder>

+

<folder>language</folder>

+

</files>

+

</source>

+

+

+

During development you can turn on language debugging in the Joomla! global configuration. So you can investigate if the problems arise.

=== Script file ===

=== Script file ===

Line 179:

Line 212:

</source>

</source>

−

A '''script file''' (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <code><scriptfile></code> element.

+

An optional '''script file''' (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <code><scriptfile></code> element. This file should contain a class named "<element_name>IntallerScript" 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). The structure of the class is as follows:

For a real-life example, see [http://joomlacode.org/gf/project/joomla/scmsvn/?action=browse&path=%2Fdevelopment%2Ftags%2F1.6.x%2F1.6.5%2Fadministrator%2Fcomponents%2Fcom_banners%2Fbanners.xml&view=markup the manifest of the Banner component in version 1.6.5].

+

For a real-life example, see [https://github.com/joomla/joomla-cms/blob/2.5.x/administrator/components/com_banners/banners.xml the manifest of the Banner component in the latest version of 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:

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

Introduction

Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the extension itself. Since Joomla! 2.5 , there are very few differences between the manifest file formats for the different types of extensions, allowing each type to access the full power of the Joomla! installer.

Naming conventions

The file must be named manifest.xml or <extension_name>.xml and located in the root directory of the installation package.

Syntax

Root element

The primary tag of the installation file is:

<extension></extension>

This starting and closing tags are now valid for all extensions. The new tag <extension> replaces the old <install></install> from Joomla . The following attributes are allowed within the tag:

Attribute

Values

Applicable to

Description

type

componentfilelanguagelibrarymodulepackageplugintemplate

All extensions

This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.

version

2.53.0

All extensions

String that identifies the version of Joomla for which this extension is developed.

method

installupgrade

All extensions

The default value install will be also used if the method attribute is not used. The install value means the installer will gracefully stop if it finds any existing file/folder of the new extension.

client

siteadministrator

Modules

The client attribute allows you to specify for which application client the new module is available.

group

string

Plugins

The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory /plugins. The installer will create new folder names for group names that do not exist yet.

Metadata

The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.

Front-end files

Files to copy to the front-end directory should be placed in the <files> element. You can use the optional folder attribute to specify a directory in the ZIP package to copy from. Each file to copy must be represented by a <filename> element. If you want to copy an entire folder at once, you can define it as a <folder>.

Media files

This example will copy the file(s) (/media/com_example_logo.png) and folders ( /media/css/ and /media/js/ ) listed to /media/com_example/, creating the com_example folder if required. You can use the optional folder attribute to specify a directory in the ZIP package to copy from (in this case, media).

Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in media. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.

Administration section

The administration section is defined in the <administration> element. Since only components apply to both the site and the administrator, only component manifests can include this element.

Back-end files

Files to copy to the back-end directory should be placed in the <files> element under the <administration>. You can use the optional folder attribute to specify a directory in the ZIP package to copy from. See Front-end files for further rules.

Menu links and submenus

The text for the main menu item for the component is defined in the <menu> item, a child of <administration>. A <submenu> element may also be present (also a child of <administration>), which may contain more menu items defined by <menu>.

Additionally, each <menu> item can define the following attributes:

Attribute

Description

link

A link to send the user to when the menu item is clicked

img

The (relative) path to an image (16x16 pixels) to appear beside the menu item.

Must be an url compatible as a file too (e.g. no spaces) !

alt

string

An URL parameter to add to the link. For example, <menu view="cpanel">COM_EXAMPLE</menu> in com_example's XML manifest would cause the URL of the menu item to be index.php?option=com_example&view=cpanel.

The value inside the tag is the menu's label. Unlike Joomla! 1.5, you can not use a natural language string. For example, if you would enter "Example Component" instead of COM_EXAMPLE, it would result in your component name appearing as example-component in the menu and you would be unable to provide a translation. In order to provide a translation you need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's tag as shown below. This tag is considered to be deprecated since Joomla! 1.6. We encourage you to put extension 's language files in the extension folder and Joomla! is responsible for the loading of required language files.

By storing extension language files in the extension folder, you gain benefits when removing a language from the Joomla! installation: As your language files will not be removed, when reinstall the language again you can use those files without installing them 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:

During development you can turn on language debugging in the Joomla! global configuration. So you can investigate if the problems arise.

Script file

<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>IntallerScript" 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). The structure of the class is as follows:

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: