Actions

Difference between revisions of "Manifest files"

From Joomla! Documentation

(Update servers)
(Needs to be updated specially the "Examples" section)
 
(32 intermediate revisions by 13 users not shown)
Line 1: Line 1:
{{RightTOC}}
+
<noinclude><languages /></noinclude>
==Introduction==
+
<noinclude>{{page|needs updating|}}</noinclude>
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.
+
<noinclude>
 +
{{Joomla version|version=3.x}} {{Joomla version|version=2.5|time=and after|status=eos}}
 +
</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>==Naming conventions== <!--T:2-->
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.
+
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.</translate>
  
==Syntax==
+
<translate>==Syntax== <!--T:3--></translate>
  
=== Root element ===
+
<translate>=== Root element === <!--T:4-->
The primary tag of the installation file is:  
+
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 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:
+
<translate><!--T:5-->
 +
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:</translate>
  
 
{|class="wikitable"
 
{|class="wikitable"
 
|-
 
|-
! style="width: 150px" | Attribute || style="width: 150px" | Values || Applicable&nbsp;to || Description
+
! style="width: 150px" | <translate><!--T:6-->
 +
Attribute</translate> || style="width: 150px" | <translate><!--T:7-->
 +
Values</translate> || <translate><!--T:8-->
 +
Applicable&nbsp;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> || <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>2.5</code><br /><code>3.0</code> || All extensions
+
| <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.</translate>
 
|-
 
|-
 
| method
 
| method
| <code>install</code><br /><code>upgrade</code> || All extensions
+
| <code>install</code><br /><code>upgrade</code> || <translate><!--T:14-->
| 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.
+
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 attribute allows you 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>
 
<pre>
<name> &ndash; raw component name (e.g. com_banners)
+
<name> &ndash; raw component name (e.g. com_banners).
 
<author> &ndash; author's name (e.g. Joomla! Project)
 
<author> &ndash; author's name (e.g. Joomla! Project)
 
<creationDate> &ndash; date of creation or release (e.g. April 2006)
 
<creationDate> &ndash; date of creation or release (e.g. April 2006)
Line 55: Line 75:
 
</pre>
 
</pre>
  
 +
<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>
=== Front-end files ===
+
  
 
<source lang="xml">
 
<source lang="xml">
Line 66: Line 87:
 
</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>
  
=== Media files ===
+
<translate>=== Media files === <!--T:25--></translate>
  
 
<source lang="xml>
 
<source lang="xml>
Line 78: Line 100:
 
</source>
 
</source>
  
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><!--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.</translate>
  
 
Ref:
 
Ref:
Line 86: Line 110:
 
* [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">
Line 94: Line 118:
 
</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 files ====
+
<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 links and submenus ====
+
<translate>==== Menu links and submenus ==== <!--T:32--></translate>
 +
{{dablink|<translate><!--T:33-->
 +
'''Version Note:''' Prior to Joomla 3.4 not having a menu tag in your XML file still led to a menu item being created. This bug was fixed in Joomla 3.4 so if no menu item was created 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 &amp; for the file to be valid
 +
XML and be parsed by the installer
 +
-->
 +
<menu link="anoption=avalue&amp;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</translate>
 +
|-
 +
| 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>
 
|-
 
|-
| img || 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>
 
 
| alt ||
 
| alt ||
 
|-
 
|-
| ''string'' || 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>.
+
| ''string'' || <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>.</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><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><!--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>&lt;languages&gt;</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>&lt;languages&gt;</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>
 +
 
 +
<translate><!--T:42-->
 +
The contents of that file should be:</translate>
  
The contents of that file should be:
 
 
<source>
 
<source>
 
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>
 
</source>
  
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.
+
<translate><!--T:43-->
 
+
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.</translate>
{{Needsinfo|In Platform 11.1 no alt attribute processed and if link provide in menu tag other provided attributes were ignore. The other tags are task, view, controller, act, layout, sub. Please confirm this, please.}}
+
  
=== Configuration ===
+
<translate>=== Configuration === <!--T:44--></translate>
{{warning|Components '''do not support''' configuration definitions '''in the manifest'''. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using [[Component configuration metadata]].}}
+
{{warning|<translate><!--T:45-->
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 can also be defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>.'''
+
Components '''do not support''' configuration definitions '''in the manifest'''. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using [[S:MyLanguage/Component configuration metadata|Component configuration metadata]].</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 can also be defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>.'''</translate>
  
{{:XML JForm form definitions}}
+
<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>
  
=== SQL ===
+
<translate>=== SQL === <!--T:48--></translate>
  
 
<source lang="xml">
 
<source lang="xml">
     <install folder="admin">
+
     <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 folder="admin">
+
     <uninstall>
 
         <sql>
 
         <sql>
 
             <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
 
             <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
Line 162: Line 206:
 
</source>
 
</source>
  
In above example, we put sql files in "admin/sql" folder of installation package. You have to include "sql" folder in administration files.
+
<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. 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.
+
<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>
  
==== Update of the SQL schema ====
+
<translate>==== Update of the SQL schema ==== <!--T:51--></translate>
  
 
<source lang="xml">
 
<source lang="xml">
Line 177: Line 223:
 
</source>
 
</source>
  
Since 1.6, there is also an <code><update></code> tag, which allows to provide a series of SQL files to update the current schema.
+
<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>
  
=== Language files ===
+
<translate>=== Language files === <!--T:53--></translate>
In Joomla! 1.5, we put extension language files in Joomla! main language file, using <languages>..</languages> tag as shown below. '''This tag considered to be deprecated since Joomla! 1.6.''' We encourage you to put extension 's language files in extension folder and Joomla! is responsible for loading of required language files.
+
<translate><!--T:54-->
 +
In Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language file, using the &lt;languages&gt;...&lt;/languages&gt; tag as shown below. '''This method can still be used in Joomla!''' {{JVer|3.x}}.</translate>
  
 
<source lang="xml">
 
<source lang="xml">
<!-- Joomla! 1.5 language tag, deprecated since Joomla! 1.6 -->
+
<!-- Joomla! 1.5 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 189: Line 237:
 
</source>
 
</source>
  
Storing extension language files in extension folder, you gain benefit when removing some language from Joomla! installation. As your language files were not removed, when reinstall the language again you can use that files without install them again.
+
<translate><!--T:55-->
 +
Since Joomla! 1.6 it has been encouraged placing your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.</translate>
  
The structure of language folder for frontend and backend is the same. You put them in <language> tag of your folder e.g. language/en-GB/. You have to specify these folders in front-end and back-end files too.
+
<translate><!--T:56-->
 +
By storing extension language files in the extension folder, you gain the benefit of 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>
  
During development you can turn on language debuggin in Joomla! global configuration. So you can investigate if the problems exists.
+
<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>
  
=== Script file ===
+
<translate><!--T:58-->
 +
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:</translate>
 +
 
 +
<source lang="xml">
 +
<files>
 +
<filename plugin="alpha">alpha.php</filename>
 +
<folder>sql</folder>
 +
<folder>language</folder>
 +
</files>
 +
</source>
 +
 
 +
<translate><!--T:59-->
 +
It is also notable 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 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 2 sys.ini files with different contents. A description of the successful install as well as a tutorial in back-end for example.</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. No risk for it to 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. So you can investigate if a problems 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 201: Line 296:
 
</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>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:
+
<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. 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 requires to state the group (e.g. plgsystempluginname). Library packages do not support scriptfiles. The structure of the class is as follows:</translate>
  
 
<source lang="php">
 
<source lang="php">
Line 212: Line 308:
 
* @param  JAdapterInstance  $adapter  The object responsible for running this script
 
* @param  JAdapterInstance  $adapter  The object responsible for running this script
 
*/
 
*/
public function __constructor(JAdapterInstance $adapter);
+
public function __construct(JAdapterInstance $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  JAdapterInstance  $adapter  The object responsible for running this script
 
* @param  JAdapterInstance  $adapter  The object responsible for running this script
 
*
 
*
Line 227: Line 323:
 
* 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  JAdapterInstance  $adapter  The object responsible for running this script
 
* @param  JAdapterInstance  $adapter  The object responsible for running this script
 
*
 
*
Line 262: Line 358:
 
</source>
 
</source>
  
=== Update servers ===
+
<translate>=== Update servers === <!--T:67--></translate>
  
 
<source lang="xml">
 
<source lang="xml">
Line 271: Line 367:
 
</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 a location to fetch updates from. Each <code><server></code> item can define the following attributes:
+
<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 a location to fetch updates from. 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:
 
More info:
* [[Developing_a_Model-View-Controller_Component/2.5/Adding_an_update_server|Building a Joomla! Extension - Adding an update server]]
+
* [[S:MyLanguage/J2.5:Developing a MVC Component/Adding an update server|Building a Joomla! Extension - Adding an update server]]
* [[Managing Component Updates with Joomla!2.5 - Part 1|Managing Component Updates in Joomla 2.5]]
+
* [[S:MyLanguage/J2.5:Managing Component Updates|Managing Component Updates in Joomla 2.5]]</translate>
  
== Examples ==
+
<translate>== Examples == <!--T:76-->
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].
+
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].</translate>
  
The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:
+
<translate><!--T:77-->
 +
The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:</translate>
  
 
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/com_alpha/alpha.xml com_alpha manifest]
 
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/com_alpha/alpha.xml com_alpha manifest]
Line 298: Line 403:
 
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/lng_xx-XX/xx-XX.xml lng_xx-XX manifest]
 
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/lng_xx-XX/xx-XX.xml lng_xx-XX manifest]
  
== Contributors ==
+
<translate>== Contributors == <!--T:78--></translate>
 
*[[User:akede|Alex Kempkens]]
 
*[[User:akede|Alex Kempkens]]
 
*[[User:dperaza|Daniel Peraza]]
 
*[[User:dperaza|Daniel Peraza]]
Line 305: Line 410:
 
*[[User:cppl|Craig Phillips]]
 
*[[User:cppl|Craig Phillips]]
  
 
+
<noinclude>
 +
<translate>
 +
<!--T:79-->
 +
[[Category:Development]]
 
[[Category:Extension development]]
 
[[Category:Extension development]]
 
[[Category:Specifications]]
 
[[Category:Specifications]]
 +
</translate>
 +
</noinclude>

Latest revision as of 10:35, 22 July 2015

Other languages:
English • ‎français • ‎Nederlands
Copyedit.png
This Article Needs Your Help

This article is tagged because it NEEDS UPDATING. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


Joomla! 
3.x
Joomla! 
≥ 2.5

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 Joomla 1.5. The following attributes are allowed within the tag:

Attribute Values Applicable to Description
type component
file
language
library
module
package
plugin
template
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.5
3.0
All extensions String that identifies the version of Joomla for which this extension is developed.
method install
upgrade
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 site
administrator
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.

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

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

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

Media files

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

Ref:

Administration section

	<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

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

	<menu>COM_EXAMPLE</menu>
	<submenu>
		<!--
			Note that all & must be escaped to &amp; for the file to be valid
			XML and be parsed by the installer
		-->
		<menu link="anoption=avalue&amp;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
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 <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. 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.

Configuration

Stop hand nuvola.svg.png
Warning!

Components do not support configuration definitions in the manifest. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using Component configuration metadata.

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 can also be defined in a separate file named config.xml. Its root element should be <config>.

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.

SQL

    <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

	<update>
		<schemas>
			<schemapath type="mysql">sql/updates/mysql</schemapath>
			<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
		</schemas>
	</update>

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

Language files

In Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language file, using the <languages>...</languages> tag as shown below. This method can still be used in Joomla! Joomla 3.x.

<!-- Joomla! 1.5 language tag -->
<languages folder="langfiles">
	<language tag="en-GB">en-GB.com_example.ini</language>
</languages>

Since Joomla! 1.6 it has been encouraged placing 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 gain the benefit of 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 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:

<files>
	<filename plugin="alpha">alpha.php</filename>
	<folder>sql</folder>
	<folder>language</folder>
</files>

It is also notable 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 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 2 sys.ini files with different contents. A description of the successful install as well as a tutorial in back-end for example.

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. No risk for it to 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. So you can investigate if a problems 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

    <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 requires to state the group (e.g. plgsystempluginname). Library packages do not support scriptfiles. The structure of the class is as follows:

class com_componentnameInstallerScript
{
	/**
	 * Constructor
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 */
	public function __construct(JAdapterInstance $adapter);
 
	/**
	 * Called before any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function preflight($route, JAdapterInstance $adapter);
 
	/**
	 * Called after any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function postflight($route, JAdapterInstance $adapter);
 
	/**
	 * Called on installation
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function install(JAdapterInstance $adapter);
 
	/**
	 * Called on update
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function update(JAdapterInstance $adapter);
 
	/**
	 * Called on uninstallation
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 */
	public function uninstall(JAdapterInstance $adapter);
}

Update servers

    <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 a location to fetch updates from. 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:

Examples

For a real-life example, see 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:

Contributors