Actions

Difference between revisions of "Manifest files"

From Joomla! Documentation

m (Adjusted categories)
(Improved the menu item creation with further information)
Line 80: Line 80:
  
 
<source lang="xml">
 
<source lang="xml">
         <menu>Example Menu Item Text</menu>
+
         <menu>COM_EXAMPLE</menu>
 
         <submenu>
 
         <submenu>
             <menu link="anoption=avalue">Example Submenu Item Text</menu>
+
             <menu link="anoption=avalue">COM_EXAMPLE_ANOPTION</menu>
 
         </submenu>
 
         </submenu>
 
</source>
 
</source>
Line 95: Line 95:
 
| link || A link to send the user to when the menu item is clicked
 
| link || A link to send the user to when the menu item is clicked
 
|-
 
|-
| view ||
+
| view || (optional) The name of the view to load. E.g. <code><menu view="cpanel">COM_EXAMPLE</menu></code> in com_example's XML manifest would cause the URL of the menu item to be index.php?option=com_example&view=cpanel
 
|-
 
|-
 
| img || The (relative) path to an image (16x16 pixels) to appear beside the menu item
 
| img || The (relative) path to an image (16x16 pixels) to appear beside the menu item
Line 102: Line 102:
 
|}
 
|}
  
{{Needsinfo|what do the other attributes do?}}
+
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.
 +
 
 +
The contents of that file should be:
 +
<source>
 +
COM_EXAMPLE="Example Component"
 +
COM_EXAMPLE_ANOPTION="Another Option"
 +
</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.
 +
 
 +
{{Needsinfo|what does alt do?}}
  
 
=== Configuration ===
 
=== Configuration ===
Line 169: Line 179:
 
*[[User:akede|Alex Kempkens]]
 
*[[User:akede|Alex Kempkens]]
 
*[[User:dperaza|Daniel Peraza]]
 
*[[User:dperaza|Daniel Peraza]]
 +
*[[User:nikosdion|Nicholas K. Dionysopoulos]]
  
 
[[Category:Extension development]]
 
[[Category:Extension development]]
 
[[Category:Specifications]]
 
[[Category:Specifications]]

Revision as of 15:23, 10 September 2011

Quill icon.png
Content is Incomplete

This article or section is incomplete, which means it may be lacking information. You are welcome to assist in its completion by editing it as well. If this article or section has not been edited in several days, please consider helping complete the content.
This article was last edited by Nikosdion (talk| contribs) 3 years ago. (Purge)

Quill icon.png
Page Actively Being Edited!

This article is actively undergoing a major edit for a short while.
As a courtesy, please do not edit this page while this message is displayed. The user who added this notice will be listed in the page history. This message is intended to help reduce edit conflicts; please remove it between editing sessions to allow others to edit the page. If this page has not been edited for several hours, please remove this template, or replace it with {{underconstruction}} or {{incomplete}}.

Contents

Introduction

Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the extension itself. Since Joomla! 1.6 Joomla 1.6, 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
module
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 1.6 All extensions String that identifies the version of Joomla for which this extension is developed. For Joomla 1.6 a version higher than 1.5 is required.
method new
upgrade
All extensions The default value install will be also used if the method attribute is not used. In these cases the installer will gracefully stop if he finds any existing file/folder of the new extension
client site
administrator
Modules The client allows 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)

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

Administration section

    <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>
            <menu link="anoption=avalue">COM_EXAMPLE_ANOPTION</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
view (optional) The name of the view to load. E.g. <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
img The (relative) path to an image (16x16 pixels) to appear beside the menu item
alt

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