Difference between revisions of "Manifest files"
From Joomla! Documentation
m (translation tags moved – template title added) |
|||
(110 intermediate revisions by 37 users not shown) | |||
Line 1: | Line 1: | ||
− | {{ | + | <noinclude><languages /></noinclude> |
− | {{ | + | <noinclude> |
− | + | {{Joomla version|version=4.x}} {{Joomla version|version=3.x}} {{Joomla version|version=2.5|status=eos}} | |
− | 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! | + | </noinclude> |
+ | <translate><!--T:1--> | ||
+ | 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 [[S:MyLanguage/extension|extension]] itself. Since Joomla! 2.5, there are very few differences between the manifest file formats for the different [[S:MyLanguage/Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.</translate> | ||
− | ==Naming conventions== | + | <translate> |
− | The file must be named <tt>manifest.xml</tt> or <tt><extension_name>.xml</tt> and located in the root directory of the installation package. | + | ==Naming conventions== <!--T:87--> |
+ | </translate> | ||
+ | <translate><!--T:88--> | ||
+ | The file must be named <tt>manifest.xml</tt> (only Joomla versions 2.5 and 3!) or <tt><extension_name>.xml</tt> (Joomla versions 2.5, 3 and 4) and located in the root directory of the installation package.</translate> | ||
− | + | <translate><!--T:100--> Joomla 4.x: Automatic namespace mapping will fail if a manifest file named <tt>manifest.xml</tt> is used. See: https://github.com/joomla/joomla-cms/issues/37750</translate> | |
− | === Root element === | + | <translate> |
− | The primary tag of the installation file is: | + | |
+ | ==Syntax== <!--T:3--> | ||
+ | </translate> | ||
+ | |||
+ | <translate> | ||
+ | === Root element === <!--T:89--> | ||
+ | </translate> | ||
+ | <translate><!--T:101--> | ||
+ | {{notice|title=General Information|The new tag <code><extension></code> replaces the old <code><install></install></code> from Joomla {{JVer|1.5}}</translate>}} | ||
+ | |||
+ | <translate><!--T:90--> | ||
+ | The primary tag of the installation file is:</translate> | ||
<source lang=xml><extension></extension></source> | <source lang=xml><extension></extension></source> | ||
− | This starting and closing | + | <translate><!--T:5--> |
+ | This starting and closing tag is the same for all extensions. The following attributes are allowed within the tag:</translate> | ||
{|class="wikitable" | {|class="wikitable" | ||
|- | |- | ||
− | ! style="width: 150px" | Attribute || style="width: 150px" | Values || Applicable to || Description | + | ! style="width: 150px" | <translate><!--T:6--> |
+ | Attribute</translate> || style="width: 150px" | <translate><!--T:7--> | ||
+ | Values</translate> || <translate><!--T:8--> | ||
+ | Applicable to</translate> || <translate><!--T:9--> | ||
+ | Description</translate> | ||
|- | |- | ||
− | | type || <code>component</code><br /><code>file</code><br /><code>language</code><br /><code>library</code><br /><code>module</code><br /><code>package</code><br /><code>plugin</code><br /><code>template</code> || All extensions | + | | type || <code>component</code><br /><code>file</code><br /><code>language</code><br /><code>library</code><br /><code>module</code><br /><code>package</code><br /><code>plugin</code><br /><code>template</code><br/><code>element</code> || <translate><!--T:10--> |
− | | This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply. | + | All extensions</translate> |
+ | | <translate><!--T:11--> | ||
+ | This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.</translate> | ||
|- | |- | ||
| version | | version | ||
− | | <code> | + | | <code>2.5</code><br /><code>3.0</code> || <translate><!--T:12--> |
− | | String that identifies the version of Joomla for which this extension is developed. | + | All extensions</translate> |
+ | | <translate><!--T:13--> | ||
+ | String that identifies the version of Joomla for which this extension is developed. This is not used in {{JVer|3.x}} and has been removed from {{JVer|4.0}} and higher.</translate> | ||
|- | |- | ||
| method | | method | ||
− | | <code> | + | | <code>install</code><br /><code>upgrade</code> || <translate><!--T:14--> |
− | | The default value install will be also used if the method attribute is not used. | + | All extensions</translate> |
+ | | <translate><!--T:15--> | ||
+ | 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.</translate> | ||
|- | |- | ||
| client | | client | ||
− | | <code>site</code><br /><code>administrator</code> || Modules | + | | <code>site</code><br /><code>administrator</code> || <translate><!--T:16--> |
− | | The client allows to specify for which application client the new module is available. | + | Modules</translate> |
+ | | <translate><!--T:17--> | ||
+ | The client attribute allows you to specify for which application client the new module is available.</translate> | ||
|- | |- | ||
| group | | group | ||
− | | ''string'' || Plugins | + | | ''string'' || <translate><!--T:18--> |
− | | 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. | + | Plugins</translate> |
+ | | <translate><!--T:19--> | ||
+ | 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.</translate> | ||
|} | |} | ||
− | === Metadata === | + | <translate> |
+ | === Metadata === <!--T:20--> | ||
+ | </translate> | ||
− | 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. | + | <translate><!--T:21--> |
+ | 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.</translate> | ||
− | + | <pre> | |
− | + | <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) | ||
+ | <element> – the internal name of the component. If omitted, name will be cleaned and used | ||
+ | </pre> | ||
− | === Front-end files === | + | <translate><!--T:22--> |
+ | 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.</translate> | ||
+ | |||
+ | <translate>=== Front-end files === <!--T:23--></translate> | ||
<source lang="xml"> | <source lang="xml"> | ||
− | + | <files folder="from-folder"> | |
− | + | <filename>example.php</filename> | |
− | + | <folder>examples</folder> | |
− | + | </files> | |
</source> | </source> | ||
− | Files to copy to the front-end directory should be placed in the <code><files></code> element. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. Each file to copy must be represented by a <code><filename></code> element. If you want to copy an entire folder at once, you can define it as a <code><folder></code>. | + | <translate><!--T:24--> |
+ | Files to copy to the front-end directory should be placed in the <code><files></code> element. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. Each file to copy must be represented by a <code><filename></code> element. If you want to copy an entire folder at once, you can define it as a <code><folder></code>.</translate> | ||
+ | |||
+ | <translate> | ||
+ | <!--T:80--> | ||
+ | For '''plugins''', the raw name of the plugin should be placed in the <code>plugin</code> attribute on the <code><filename></code> element that points to the file containing the plugin's class. For example, in the case of a system plugin called "example" (full name <code>plg_system_example</code>), use <code><filename plugin="example">example.php</filename></code>.</translate> | ||
+ | |||
+ | <translate>=== Media files === <!--T:25--></translate> | ||
− | |||
<source lang="xml> | <source lang="xml> | ||
− | + | <media folder="media" destination="com_example"> | |
− | + | <filename>com_example_logo.png</filename> | |
− | + | <folder>css</folder> | |
− | + | <folder>js</folder> | |
− | + | </media> | |
</source> | </source> | ||
− | This example will copy the file(s) (com_example_logo.png) and folders ( /css/ and /js/ ) listed to < | + | <translate><!--T:26--> |
+ | 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>).</translate> | ||
− | 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. | + | <translate><!--T:27--> |
+ | 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.<br /> | ||
+ | Note: the media section is not parsed for 'package' type extensions.</translate> | ||
Ref: | Ref: | ||
Line 81: | Line 130: | ||
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/uNmhX98sKbE/p8p68Jke680J Google Groups - joomla-dev-cms thread] | * [https://groups.google.com/forum/#!msg/joomla-dev-cms/uNmhX98sKbE/p8p68Jke680J Google Groups - joomla-dev-cms thread] | ||
− | === Administration section === | + | <translate> |
+ | === Administration section === <!--T:28--> | ||
+ | </translate> | ||
<source lang="xml"> | <source lang="xml"> | ||
− | + | <administration> | |
+ | <!-- various elements --> | ||
+ | </administration> | ||
</source> | </source> | ||
− | The administration section is defined in the <code><administration></code> element. Since only [[Component|components]] apply to both the [[Site (Application)|site]] and the [[Administrator (Application)|administrator]], '''only component manifests can include this element'''. | + | <translate><!--T:29--> |
+ | The administration section is defined in the <code><administration></code> element. Since only [[S:MyLanguage/Component|components]] apply to both the [[S:MyLanguage/Site (Application)|site]] and the [[S:MyLanguage/Administrator (Application)|administrator]], '''only component manifests can include this element'''.</translate> | ||
− | ==== Back-end | + | <translate> |
+ | ==== Back-end Files ==== <!--T:30--> | ||
+ | </translate> | ||
− | Files to copy to the back-end directory should be placed in the <code><files></code> element under the <code><administration></code>. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. See ''Front-end files'' for further rules. | + | <translate><!--T:31--> |
+ | Files to copy to the back-end directory should be placed in the <code><files></code> element under the <code><administration></code>. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. See ''Front-end files'' for further rules.</translate> | ||
− | ==== Menu | + | <translate> |
+ | ==== Menu Links and Submenus ==== <!--T:32--> | ||
+ | </translate> | ||
+ | {{dablink|<translate><!--T:33--> | ||
+ | '''Version Note:''' Prior to Joomla 3.4, not having a <code><nowiki><menu></nowiki></code> tag in your manifest XML file still led to a menu item being created. This bug was fixed in Joomla 3.4, so if there is no <code><nowiki><menu></nowiki></code> tag in your manifest file, then no admin menu item is created for the component.</translate>}} | ||
<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> | + | <!-- |
+ | Note that all & must be escaped to & for the file to be valid | ||
+ | XML and be parsed by the installer | ||
+ | --> | ||
+ | <menu link="anoption=avalue&anoption1=avalue1">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>. | + | <translate><!--T:34--> |
+ | 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>.</translate> | ||
− | Additionally, each <code><menu></code> item can define the following attributes: | + | <translate><!--T:35--> |
+ | Additionally, each <code><menu></code> item can define the following attributes:</translate> | ||
{| class="wikitable" | {| class="wikitable" | ||
− | ! style="width: 150px" | Attribute || Description | + | ! style="width: 150px" | <translate><!--T:36--> |
+ | Attribute</translate> || <translate><!--T:37--> | ||
+ | Description</translate> | ||
|- | |- | ||
− | | link || A link to send the user to when the menu item is clicked | + | | link || <translate><!--T:38--> |
+ | A link to send the user to when the menu item is clicked. You can use "view" instead.</translate> | ||
|- | |- | ||
− | | img || The (relative) path to an image (16x16 pixels) to appear beside the menu item | + | | img || <translate><!--T:39--> |
+ | The (relative) path to an image (16x16 pixels) to appear beside the menu item. | ||
+ | <u>Must be an url compatible as a file too (e.g. no spaces) !</u></translate> | ||
|- | |- | ||
| alt || | | alt || | ||
|- | |- | ||
− | | | + | | view || <translate><!--T:40--> |
+ | An URL parameter to add to the link. For example, <code><menu view="cpanel">COM_EXAMPLE</menu></code> in com_example's XML manifest would cause the URL of the menu item to be <tt>index.php?option=com_example&view=cpanel</tt>. You can use "link" instead.</translate> | ||
|- | |- | ||
|} | |} | ||
− | 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 <code> | + | <translate><!--T:41--> |
+ | 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 <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.</translate> | ||
− | The contents of that file should be: | + | <translate><!--T:42--> |
− | <source> | + | The contents of that file should be:</translate> |
+ | |||
+ | <source lang="ini"> | ||
COM_EXAMPLE="Example Component" | COM_EXAMPLE="Example Component" | ||
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option" | COM_EXAMPLE_SUBMENU_ANOPTION="Another Option" | ||
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View" | COM_EXAMPLE_SUBMENU_VIEWNAME="Another View" | ||
+ | </source> | ||
+ | <translate><!--T:102--> Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards.</translate> | ||
+ | |||
+ | {{note|<translate><!--T:103--> 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.</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | === Dashboards === <!--T:104--> </translate> | ||
+ | <translate><!--T:105--> | ||
+ | {{notice|title=General Information|This code only works in {{JVer|4.0}} and later</translate>}} | ||
+ | |||
+ | <translate><!--T:106--> Specifies the details for displaying a dashboard for the component in the Administrator area for the site.</translate> | ||
+ | <translate> | ||
+ | <!--T:107--> | ||
+ | * It will make a dashboard icon appear next to the administrator menu item for the component | ||
+ | * The dashboard icon will click through to display modules assigned to the cpanel-example administrator module position | ||
+ | * The title and icon defined in the XML file will be used as the header and icon at the top of the component's dashboard page.</translate> | ||
+ | |||
+ | <source lang="xml"> | ||
+ | <dashboards> | ||
+ | <dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="icon-lock">example</dashboard> | ||
+ | </dashboards> | ||
</source> | </source> | ||
− | + | <translate> | |
+ | === Configuration === <!--T:44--> | ||
+ | </translate> | ||
+ | <translate><!--T:45--> | ||
+ | {{warning|title=Warning!|Components '''do not support''' configuration definitions '''in the manifest'''. This was a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using the config.xml file. For how to add this to your component read the [[S:MyLanguage/J3.x:Developing_an_MVC_Component/Adding_configuration|Developing an MVC Component tutorial]].</translate>}} | ||
+ | <translate><!--T:46--> | ||
+ | The <code><config></code> element, a child of the root, describes the configuration options for the extension. If applicable, the options will be shown by the appropriate Manager (Plugin Manager, Module Manager or Template Manager). '''Configuration options for Components are defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>, plugins and modules use the <code><config></code> section in the extension manifest file.'''</translate> | ||
− | + | <translate><!--T:47--> | |
+ | Each fieldset must contain one or more <code><field></code> elements, each representing a single [[S:MyLanguage/form field|form field]] with a label. See [[S:MyLanguage/Standard form field types|Standard form field types]] for a list of allowed form field types and example XML form field definitions.</translate> | ||
− | === | + | <translate> |
− | + | === Namespace === <!--T:108--> </translate> | |
− | + | <translate><!--T:109--> | |
+ | {{notice|title=General Information|This code only works in {{JVer|4.0}} and later</translate>}} | ||
− | + | <translate><!--T:110--> Specify the namespace to be used for autoloading the plugin. The given namespace will autoload to the root directory of your extension by default however you can optionally add a "path" attribute to the namespace element to specify a subpath within your extensions root directory.</translate> | |
− | === SQL === | + | <translate> |
+ | === SQL === <!--T:48--> | ||
+ | </translate> | ||
<source lang="xml"> | <source lang="xml"> | ||
− | <install | + | <install> |
<sql> | <sql> | ||
<file driver="mysql" charset="utf8">sql/example.install.sql</file> | <file driver="mysql" charset="utf8">sql/example.install.sql</file> | ||
</sql> | </sql> | ||
</install> | </install> | ||
− | <uninstall | + | <uninstall> |
<sql> | <sql> | ||
<file driver="mysql" charset="utf8">sql/example.uninstall.sql</file> | <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file> | ||
Line 155: | Line 262: | ||
</source> | </source> | ||
− | In above example, we put | + | <translate><!--T:49--> |
+ | In the above example, we put the SQL files in the <tt>admin/sql</tt> folder of the installation package. You have to include the <tt>sql</tt> folder in the administration files (as described in ''Back-end files'').</translate> | ||
− | You can execute SQL during installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. | + | <translate><!--T:50--> |
+ | 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.</translate> | ||
− | === | + | <translate> |
− | + | ==== Update of the SQL Schema ==== <!--T:51--> | |
+ | </translate> | ||
+ | |||
+ | <translate><!--T:52--> | ||
+ | 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.</translate> | ||
<source lang="xml"> | <source lang="xml"> | ||
− | <!-- Joomla! 1.5 language tag | + | <update> |
+ | <schemas> | ||
+ | <schemapath type="mysql">sql/updates/mysql</schemapath> | ||
+ | <schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath> | ||
+ | </schemas> | ||
+ | </update> | ||
+ | </source> | ||
+ | |||
+ | <translate><!--T:81--> | ||
+ | For example, in order to go from version <code>1.0.0</code> to version <code>1.0.1</code> in a '''MySQL''' database, a <code>1.0.1.sql</code> file must be created inside the <code>sql/updates/mysql</code> folder and the <code><version></code> tag of the manifest must be updated to</translate> | ||
+ | <source lang="xml"> | ||
+ | <version>1.0.1</version></source> | ||
+ | |||
+ | |||
+ | <translate><!--T:82--> | ||
+ | The final structure of the sql folder will look like this (assuming a '''MySQL''' database)</translate> | ||
+ | <source lang="xml"> | ||
+ | sql | ||
+ | |-->example.install.sql | ||
+ | |-->example.uninstall.sql | ||
+ | |-->updates | ||
+ | |-->mysql | ||
+ | |-->1.0.1.sql</source> | ||
+ | |||
+ | <translate><!--T:83--> | ||
+ | Similar files must be created for subsequent versions.</translate> | ||
+ | |||
+ | <translate> | ||
+ | === Language Files === <!--T:53--> | ||
+ | </translate> | ||
+ | <translate><!--T:54--> | ||
+ | Since Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language folder using the <languages>...</languages> tag as shown below. '''This method can still be used all Joomla! versions'''.</translate> | ||
+ | |||
+ | <source lang="xml"> | ||
+ | <!-- Joomla! language tag --> | ||
<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 169: | Line 316: | ||
</source> | </source> | ||
− | + | <translate><!--T:55--> | |
+ | However since Joomla! 1.6 it is recommended that you place your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.</translate> | ||
+ | |||
+ | <translate><!--T:56--> | ||
+ | By storing extension language files in the extension folder, you benefit by isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed again.</translate> | ||
+ | |||
+ | <translate><!--T:57--> | ||
+ | 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.</translate> | ||
− | + | <translate><!--T:58--> | |
+ | In your manifest, simply include the ''''language'''' folder in your files section. The sub-directories for each language will automatically be copied. Inside the <files> group, add a <folder> element alongside the items in the '''<files>''' group as shown in this example:</translate> | ||
− | + | <source lang="xml"> | |
+ | <files> | ||
+ | <filename plugin="alpha">alpha.php</filename> | ||
+ | <folder>sql</folder> | ||
+ | <folder>language</folder> | ||
+ | </files> | ||
+ | </source> | ||
− | === Script file === | + | <translate><!--T:59--> |
+ | Note that both ways can work together. Here is an example from core:</translate> | ||
+ | |||
+ | <source lang="xml"> | ||
+ | <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> | ||
+ | </source> | ||
+ | |||
+ | <translate><!--T:60--> | ||
+ | The advantages of this solution are the following:</translate> | ||
+ | |||
+ | <translate><!--T:61--> | ||
+ | All ''.ini'' files present in the core folder have precedence over the files in the extension ''language/'' folder. | ||
+ | For example, a ''.sys.ini'' file will always be loaded from core folders in the back-end if it exists, except when installing an extension which contains a ''.sys.ini'' file in a language folder. In that case and only that case, the ''.sys.ini'' file in the extension folder will display its translated content at install time. This is very handy. As a developer can have two ''.sys.ini'' files with different contents.</translate> | ||
+ | |||
+ | <translate><!--T:62--> | ||
+ | Also, it is much easier for a user needing an ''.ini'' file for an extension that does not provide it in the language desired to add it in the main folders. There is no risk that it will be deleted in case of uninstalling the extension by mistake or any other reason.</translate> | ||
+ | |||
+ | <translate><!--T:63--> | ||
+ | See also: | ||
+ | *[[S:MyLanguage/J2.5:Making non-core language packs|Making non-core language packs]] | ||
+ | *[[S:MyLanguage/Creating language packs for extensions in Joomla 2.5|Creating language packs for extensions in Joomla 2.5]]</translate> | ||
+ | |||
+ | <translate><!--T:64--> | ||
+ | During development you can turn on language debugging in the Joomla! global configuration. You can investigate if a problem arises. As of 3.2, this is necessary to help debug as en-GB is '''always''' loaded first when not in debug mode to prevent displaying Constants.</translate> | ||
+ | |||
+ | <translate> | ||
+ | === Script file === <!--T:65--> | ||
+ | </translate> | ||
<source lang="xml"> | <source lang="xml"> | ||
Line 181: | Line 377: | ||
</source> | </source> | ||
− | 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> | + | <translate><!--T:66--> |
+ | 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.</translate> | ||
+ | |||
+ | <translate><!--T:98--> | ||
+ | This file should contain a class named "<element_name>InstallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins must state the group (e.g. plgsystempluginname).</translate> | ||
+ | |||
+ | <translate><!--T:99--> | ||
+ | In {{JVer|4.0}} and later the structure of the class is as follows:</translate> | ||
<source lang="php"> | <source lang="php"> | ||
+ | |||
+ | <?php | ||
+ | |||
+ | use Joomla\CMS\Installer\InstallerAdapter; | ||
class com_componentnameInstallerScript | class com_componentnameInstallerScript | ||
Line 190: | Line 397: | ||
* Constructor | * Constructor | ||
* | * | ||
− | * @param | + | * @param InstallerAdapter $adapter The object responsible for running this script |
*/ | */ | ||
− | public function | + | public function __construct(InstallerAdapter $adapter) |
+ | { | ||
+ | } | ||
/** | /** | ||
* Called before any type of action | * Called before any type of action | ||
* | * | ||
− | * @param string $route Which action is happening (install|uninstall|discover_install) | + | * @param string $route Which action is happening (install|uninstall|discover_install|update) |
− | * @param | + | * @param InstallerAdapter $adapter The object responsible for running this script |
* | * | ||
* @return boolean True on success | * @return boolean True on success | ||
*/ | */ | ||
− | public function preflight($route, | + | public function preflight($route, InstallerAdapter $adapter) |
+ | { | ||
+ | return true; | ||
+ | } | ||
/** | /** | ||
* Called after any type of action | * Called after any type of action | ||
* | * | ||
− | * @param string $route Which action is happening (install|uninstall|discover_install) | + | * @param string $route Which action is happening (install|uninstall|discover_install|update) |
− | * @param | + | * @param InstallerAdapter $adapter The object responsible for running this script |
* | * | ||
* @return boolean True on success | * @return boolean True on success | ||
*/ | */ | ||
− | public function postflight($route, | + | public function postflight($route, $adapter) |
+ | { | ||
+ | return true; | ||
+ | } | ||
/** | /** | ||
* Called on installation | * Called on installation | ||
* | * | ||
− | * @param | + | * @param InstallerAdapter $adapter The object responsible for running this script |
* | * | ||
* @return boolean True on success | * @return boolean True on success | ||
*/ | */ | ||
− | public function install( | + | public function install(InstallerAdapter $adapter) |
+ | { | ||
+ | return true; | ||
+ | } | ||
/** | /** | ||
* Called on update | * Called on update | ||
* | * | ||
− | * @param | + | * @param InstallerAdapter $adapter The object responsible for running this script |
* | * | ||
* @return boolean True on success | * @return boolean True on success | ||
*/ | */ | ||
− | public function update( | + | public function update(InstallerAdapter $adapter) |
+ | { | ||
+ | return true; | ||
+ | } | ||
/** | /** | ||
* Called on uninstallation | * Called on uninstallation | ||
* | * | ||
− | * @param | + | * @param InstallerAdapter $adapter The object responsible for running this script |
*/ | */ | ||
− | public function uninstall( | + | public function uninstall(InstallerAdapter $adapter) |
+ | { | ||
+ | return true; | ||
+ | } | ||
} | } | ||
+ | ?> | ||
+ | </source> | ||
+ | |||
+ | <translate><!--T:111--> Note that since Joomla 3.6 Joomla has shipped a basic script that you can use instead of shipping your own from scratch '''JInstallerScript''' which contains various helper methods commonly used through the community.</translate> | ||
+ | |||
+ | <translate> | ||
+ | === Library Manifests === <!--T:112--> </translate> | ||
+ | <translate><!--T:113--> | ||
+ | {{notice|title=General Information|The section is based on {{JVer|4.0}} and later</translate>}} | ||
+ | |||
+ | <translate><!--T:114--> A simple library manifest might look like this:</translate> | ||
+ | <source lang="xml"> | ||
+ | <?xml version="1.0" encoding="utf-8"?> | ||
+ | <extension type="library" method="upgrade" version="4.0"> | ||
+ | <name>My Test library.</name> | ||
+ | <libraryname>mytest</libraryname> | ||
+ | <files> | ||
+ | <folder>Classes</folder> | ||
+ | <folder>language</folder> | ||
+ | <filename>mytest.php</filename> | ||
+ | </files> | ||
+ | </extension></source> | ||
+ | |||
+ | <translate><!--T:115--> This will install the library into the <tt>JPATH_SITE/libraries/mytest</tt> folder.</translate> | ||
+ | |||
+ | <translate><!--T:116--> What if your company has several libraries and you want to group them together under folder <tt>JPATH_SITE/libraries/mycompany</tt>?</translate> | ||
+ | |||
+ | <translate><!--T:117--> Simple - include your company name in the <tt>libraryname</tt> property of each library like this:</translate> | ||
+ | |||
+ | <source lang="xml"> | ||
+ | <libraryname>mycompany/mylibrary1</libraryname> | ||
+ | </source> | ||
+ | |||
+ | <source lang="xml"> | ||
+ | <libraryname>mycompany/mylibrary2</libraryname> | ||
+ | </source> | ||
+ | |||
+ | <translate><!--T:118--> These libraries will then be installed in the <tt>JPATH_SITE/libraries/mycompany/mylibrary1</tt> and <tt>JPATH_SITE/libraries/mycompany/mylibrary2</tt> folders.</translate> | ||
+ | |||
+ | <translate><!--T:119--> Uninstalling <tt>mylibrary1</tt> will still leave <tt>mylibrary2</tt> installed on your site.</translate> | ||
+ | |||
+ | <translate><!--T:120--> When using <tt>script files</tt> with such company libraries the installer class name should look like this:</translate> | ||
+ | <source lang="php"> | ||
+ | class mycompanymylibrary1InstallerScript | ||
+ | </source> | ||
+ | <source lang="php"> | ||
+ | class mycompanymylibrary2InstallerScript | ||
</source> | </source> | ||
− | === Update | + | <translate> |
+ | === Update Servers === <!--T:67--> | ||
+ | </translate> | ||
<source lang="xml"> | <source lang="xml"> | ||
Line 251: | Line 524: | ||
</source> | </source> | ||
− | Update servers can be defined in the <code><updateservers></code> element, a child of the root. This element may contain one or more <code><server></code> element, each describing | + | <translate><!--T:68--> |
+ | Update servers can be defined in the <code><updateservers></code> element, a child of the root. This element may contain one or more <code><server></code> element, each describing the location from which to download updates. Each <code><server></code> item can define the following attributes:</translate> | ||
{| class="wikitable" | {| class="wikitable" | ||
− | ! style="width: 150px" | Attribute || style="width: 150px" | Values || Description | + | ! style="width: 150px" | <translate><!--T:69--> |
+ | Attribute</translate> || style="width: 150px" | <translate><!--T:70--> | ||
+ | Values</translate> || <translate><!--T:71--> | ||
+ | Description</translate> | ||
|- | |- | ||
− | | type || <code>extension</code><br /><code>collection</code> || The update server type | + | | type || <code>extension</code><br /><code>collection</code> || <translate><!--T:72--> |
+ | The update server type</translate> | ||
|- | |- | ||
− | | priority || ''integer'' || The priority of the update server | + | | priority || ''integer'' || <translate><!--T:73--> |
+ | The priority of the update server</translate> | ||
|- | |- | ||
− | | name || ''string'' || The name of the update server | + | | name || ''string'' || <translate><!--T:74--> |
+ | The name of the update server</translate> | ||
|} | |} | ||
− | == | + | <translate><!--T:75--> |
− | + | More info: | |
+ | * [[S:MyLanguage/J3.x:Developing_an_MVC_Component/Adding_an_update_server|Building a Joomla! Extension - Adding an update server]] | ||
+ | * [[S:MyLanguage/J2.5:Managing Component Updates|Managing Component Updates in Joomla 2.5]]</translate> | ||
+ | |||
+ | <translate>=== Supporting Download Keys === <!--T:91--></translate> | ||
+ | |||
+ | <translate><!--T:92--> As of Joomla 4.0.0 users can enter their download keys in the Update Sites list. This gives them a single place to manage the download keys. When a user is going to update an extension, Joomla will check if there is a download key. If there is a download key, Joomla will add the download key to the update URL.</translate> | ||
+ | |||
+ | <translate><!--T:93--> To support download keys you must include the <tt>dlid</tt> tag in the manifest file. The <tt>dlid</tt> tag takes 2 arguments:</translate> | ||
+ | <translate> | ||
+ | <!--T:94--> | ||
+ | * prefix | ||
+ | * suffix | ||
+ | </translate> | ||
+ | |||
+ | <translate><!--T:95--> The <tt>dlid</tt> tag will look like this in your manifest file:</translate> | ||
+ | <source lang="xml"> | ||
+ | <dlid prefix="dlid=" suffix="&dummy=my.zip"/> | ||
+ | </source> | ||
+ | |||
+ | <translate><!--T:96--> The prefix will be added before the download key and the suffix after the download key. Using the example above the full query added to the download link will be:</translate> | ||
+ | <source lang="php"> | ||
+ | dlid=KEY&dummy=my.zip | ||
+ | </source> | ||
− | The | + | <translate><!--T:97--> The key is added before the <tt>onInstallerBeforePackageDownload</tt> event is triggered, so the full URL will be passed to the event.</translate> |
− | + | <translate> | |
− | + | == Examples == <!--T:84--> | |
− | + | </translate> | |
− | + | <translate><!--T:85--> | |
− | + | For a real-life example, see [https://github.com/joomla/joomla-cms/blob/3.9.16/administrator/components/com_banners/banners.xml the manifest of the Banner component in the latest version of Joomla! 3.9.16].</translate> | |
− | + | <translate><!--T:77--> | |
− | + | Some more examples can be found in the standalone weblinks repo:</translate> | |
− | |||
− | |||
− | |||
− | |||
+ | <translate><!--T:86--> | ||
+ | * [https://github.com/joomla-extensions/weblinks/blob/master/src/administrator/components/com_weblinks/weblinks.xml com_weblinks manifest] | ||
+ | * [https://github.com/joomla-extensions/weblinks/blob/master/src/modules/mod_weblinks/mod_weblinks.xml mod_weblinks manifest] | ||
+ | * [https://github.com/joomla-extensions/weblinks/blob/master/src/plugins/search/weblinks/weblinks.xml plg_search_weblinks manifest] | ||
+ | * [https://github.com/joomla/joomla-cms/blob/3.9.16/templates/protostar/templateDetails.xml tpl_protostar manifest (3.9.16)] | ||
+ | * [https://github.com/joomla/joomla-cms/blob/3.9.16/administrator/language/en-GB/en-GB.xml en-GB manifest (3.9.16)]</translate> | ||
− | [[Category:Extension development]] | + | <noinclude> |
− | [[Category:Specifications]] | + | [[Category:Development{{#translation:}}]] |
+ | [[Category:Extension development{{#translation:}}]] | ||
+ | [[Category:Specifications{{#translation:}}]] | ||
+ | </noinclude> |
Latest revision as of 05:27, 17 August 2022
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[edit]
The file must be named manifest.xml (only Joomla versions 2.5 and 3!) or <extension_name>.xml (Joomla versions 2.5, 3 and 4) and located in the root directory of the installation package.
Joomla 4.x: Automatic namespace mapping will fail if a manifest file named manifest.xml is used. See: https://github.com/joomla/joomla-cms/issues/37750
Syntax[edit]
Root element[edit]
The primary tag of the installation file is:
<extension></extension>
This starting and closing tag is the same for all extensions. The following attributes are allowed within the tag:
Metadata[edit]
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.
<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) <element> – the internal name of the component. If omitted, name will be cleaned and used
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[edit]
<files folder="from-folder">
<filename>example.php</filename>
<folder>examples</folder>
</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>
.
For plugins, the raw name of the plugin should be placed in the plugin
attribute on the <filename>
element that points to the file containing the plugin's class. For example, in the case of a system plugin called "example" (full name plg_system_example
), use <filename plugin="example">example.php</filename>
.
Media files[edit]
<media folder="media" destination="com_example">
<filename>com_example_logo.png</filename>
<folder>css</folder>
<folder>js</folder>
</media>
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.
Note: the media section is not parsed for 'package' type extensions.
Ref:
Administration section[edit]
<administration>
<!-- various elements -->
</administration>
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[edit]
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.
[edit]
<menu>
tag in your manifest XML file still led to a menu item being created. This bug was fixed in Joomla 3.4, so if there is no <menu>
tag in your manifest file, then no admin menu item is created for the component. <menu>COM_EXAMPLE</menu>
<submenu>
<!--
Note that all & must be escaped to & for the file to be valid
XML and be parsed by the installer
-->
<menu link="anoption=avalue&anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
</submenu>
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. You can use "view" instead. |
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 | |
view | 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. You can use "link" instead.
|
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 <languages>
tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <languages>
tag. As long as you have placed the language directory in your <files>
tag, it will be copied along when the component is being installed.
The contents of that file should be:
COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"
Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards.
Dashboards[edit]
Specifies the details for displaying a dashboard for the component in the Administrator area for the site.
- It will make a dashboard icon appear next to the administrator menu item for the component
- The dashboard icon will click through to display modules assigned to the cpanel-example administrator module position
- The title and icon defined in the XML file will be used as the header and icon at the top of the component's dashboard page.
<dashboards>
<dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="icon-lock">example</dashboard>
</dashboards>
Configuration[edit]
Components do not support configuration definitions in the manifest. This was a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using the config.xml file. For how to add this to your component read the Developing an MVC Component tutorial.
The <config>
element, a child of the root, describes the configuration options for the extension. If applicable, the options will be shown by the appropriate Manager (Plugin Manager, Module Manager or Template Manager). Configuration options for Components are defined in a separate file named config.xml
. Its root element should be <config>
, plugins and modules use the <config>
section in the extension manifest file.
Each fieldset must contain one or more <field>
elements, each representing a single form field with a label. See Standard form field types for a list of allowed form field types and example XML form field definitions.
Namespace[edit]
Specify the namespace to be used for autoloading the plugin. The given namespace will autoload to the root directory of your extension by default however you can optionally add a "path" attribute to the namespace element to specify a subpath within your extensions root directory.
SQL[edit]
<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>
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 (as described in Back-end files).
You can execute SQL during the installation and/or uninstallation using the <install>
and <uninstall>
elements, respectively. A <sql>
element should appear as a child of these elements. <sql>
can contain any number of <file>
elements, each defining a single SQL file to execute. Their database driver types are described by the driver
attribute, their character sets by the charset
attribute.
Update of the SQL Schema[edit]
Since 1.6, there is also an <update>
tag, which allows you to provide a series of SQL files to update the current schema.
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
</schemas>
</update>
For example, in order to go from version 1.0.0
to version 1.0.1
in a MySQL database, a 1.0.1.sql
file must be created inside the sql/updates/mysql
folder and the <version>
tag of the manifest must be updated to
<version>1.0.1</version>
The final structure of the sql folder will look like this (assuming a MySQL database)
sql
|-->example.install.sql
|-->example.uninstall.sql
|-->updates
|-->mysql
|-->1.0.1.sql
Similar files must be created for subsequent versions.
Language Files[edit]
Since Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language folder using the <languages>...</languages> tag as shown below. This method can still be used all Joomla! versions.
<!-- Joomla! language tag -->
<languages folder="langfiles">
<language tag="en-GB">en-GB.com_example.ini</language>
</languages>
However since Joomla! 1.6 it is recommended that you place your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.
By storing extension language files in the extension folder, you benefit by isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed 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, simply include the 'language' folder in your files section. The sub-directories for each language will automatically be copied. Inside the <files> group, add a <folder> element alongside the items in the <files> group as shown in this example:
<files>
<filename plugin="alpha">alpha.php</filename>
<folder>sql</folder>
<folder>language</folder>
</files>
Note that both ways can work together. Here is an example from core:
<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>
The advantages of this solution are the following:
All .ini files present in the core folder have precedence over the files in the extension language/ folder. For example, a .sys.ini file will always be loaded from core folders in the back-end if it exists, except when installing an extension which contains a .sys.ini file in a language folder. In that case and only that case, the .sys.ini file in the extension folder will display its translated content at install time. This is very handy. As a developer can have two .sys.ini files with different contents.
Also, it is much easier for a user needing an .ini file for an extension that does not provide it in the language desired to add it in the main folders. There is no risk that it will be deleted in case of uninstalling the extension by mistake or any other reason.
See also:
During development you can turn on language debugging in the Joomla! global configuration. You can investigate if a problem arises. As of 3.2, this is necessary to help debug as en-GB is always loaded first when not in debug mode to prevent displaying Constants.
Script file[edit]
<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>InstallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins must state the group (e.g. plgsystempluginname).
In and later the structure of the class is as follows:
<?php
use Joomla\CMS\Installer\InstallerAdapter;
class com_componentnameInstallerScript
{
/**
* Constructor
*
* @param InstallerAdapter $adapter The object responsible for running this script
*/
public function __construct(InstallerAdapter $adapter)
{
}
/**
* Called before any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function preflight($route, InstallerAdapter $adapter)
{
return true;
}
/**
* Called after any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function postflight($route, $adapter)
{
return true;
}
/**
* Called on installation
*
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function install(InstallerAdapter $adapter)
{
return true;
}
/**
* Called on update
*
* @param InstallerAdapter $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function update(InstallerAdapter $adapter)
{
return true;
}
/**
* Called on uninstallation
*
* @param InstallerAdapter $adapter The object responsible for running this script
*/
public function uninstall(InstallerAdapter $adapter)
{
return true;
}
}
?>
Note that since Joomla 3.6 Joomla has shipped a basic script that you can use instead of shipping your own from scratch JInstallerScript which contains various helper methods commonly used through the community.
Library Manifests[edit]
A simple library manifest might look like this:
<?xml version="1.0" encoding="utf-8"?>
<extension type="library" method="upgrade" version="4.0">
<name>My Test library.</name>
<libraryname>mytest</libraryname>
<files>
<folder>Classes</folder>
<folder>language</folder>
<filename>mytest.php</filename>
</files>
</extension>
This will install the library into the JPATH_SITE/libraries/mytest folder.
What if your company has several libraries and you want to group them together under folder JPATH_SITE/libraries/mycompany?
Simple - include your company name in the libraryname property of each library like this:
<libraryname>mycompany/mylibrary1</libraryname>
<libraryname>mycompany/mylibrary2</libraryname>
These libraries will then be installed in the JPATH_SITE/libraries/mycompany/mylibrary1 and JPATH_SITE/libraries/mycompany/mylibrary2 folders.
Uninstalling mylibrary1 will still leave mylibrary2 installed on your site.
When using script files with such company libraries the installer class name should look like this:
class mycompanymylibrary1InstallerScript
class mycompanymylibrary2InstallerScript
Update Servers[edit]
<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 the location from which to download updates. Each <server>
item can define the following attributes:
Attribute | Values | Description |
---|---|---|
type | extension collection |
The update server type |
priority | integer | The priority of the update server |
name | string | The name of the update server |
More info:
Supporting Download Keys[edit]
As of Joomla 4.0.0 users can enter their download keys in the Update Sites list. This gives them a single place to manage the download keys. When a user is going to update an extension, Joomla will check if there is a download key. If there is a download key, Joomla will add the download key to the update URL.
To support download keys you must include the dlid tag in the manifest file. The dlid tag takes 2 arguments:
- prefix
- suffix
The dlid tag will look like this in your manifest file:
<dlid prefix="dlid=" suffix="&dummy=my.zip"/>
The prefix will be added before the download key and the suffix after the download key. Using the example above the full query added to the download link will be:
dlid=KEY&dummy=my.zip
The key is added before the onInstallerBeforePackageDownload event is triggered, so the full URL will be passed to the event.
Examples[edit]
For a real-life example, see the manifest of the Banner component in the latest version of Joomla! 3.9.16.
Some more examples can be found in the standalone weblinks repo: