Manifest files

Content is Incomplete

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 , there are very few differences between the manifest file formats for the different types of extensions, allowing each type to access the full power of the Joomla! installer.

Naming conventions

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

Syntax

Root element

The primary tag of the installation file is:

<extension></extension>

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

Attribute	Values	Applicable to	Description
type	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	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 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)

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:

• Google Groups - joomla-dev-cms thread
• Google Groups - joomla-dev-cms thread

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>
		<menu link="anoption=avalue">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

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.

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

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.

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.

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

Script file

    <scriptfile>example.script.php</scriptfile>

An optional script file (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <scriptfile> element. This file should contain a class named "<element_name>IntallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins requires to state the group (e.g. plgsystempluginname). The structure of the class is as follows:

class com_componentnameInstallerScript
{
	/**
	 * Constructor
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 */
	public function __constructor(JAdapterInstance $adapter);
	
	/**
	 * Called before any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install)
	 * @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)
	 * @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

Examples

For a real-life example, see the manifest of the Banner component in version 1.6.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:

• com_alpha manifest
• mod_alpha manifest
• plg_system_alpha manifest
• tpl_simple manifest
• lng_xx-XX manifest

Contributors

• Alex Kempkens
• Daniel Peraza
• Nicholas K. Dionysopoulos
• Prasit Gebsaap
• Craig Phillips