Manifests

Elgg plugins are required to have a manifest.xml file in the root of a plugin. This file contains information about the plugin like author and version. The format of this file changed between Elgg 1.7 and 1.8.

Elgg 1.8

The manifest.xml file in Elgg 1.8 includes information about the plugin itself, requirements to run the plugin, and optional information including where to display the plugin in the admin area and what APIs the plugin provides.

Syntax

The manifest file is a standard XML file in UTF-8. Everything is a child of the "plugin_manifest" element. It is important to specify the correct XML Namespace on this element to signify which manifest format you're using. For plugins development in 1.8, use the namespace: http://www.elgg.org/plugin_manifest/1.8.

<?xml version="1.0" encoding="UTF-8" ?>
 
<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">

In Elgg 1.8 the manifest syntax is as follows:

<name>value</name>

Many elements can contain children attributes:

<parent_name>
    <child_name>value</child_name>
    <child_name_2>value_2</child_name_2>
</parent_name>

Required Elements

All plugins are required to define the following elements in their manifest files:

• name - The display name of the plugin. (Note: This is different to the plugin id, which is the name of the directory the plugin uses.)
• author - The name of the author who wrote the plugin.
• version - The version of the plugin.
• description - A description of the what the plugin provides, its features, and other relevant information
• requires - Each plugin must specify the version of Elgg it was developed for. See the Plugin Dependencies page for more information.

Available Elements

In addition to the require elements above, the follow elements are available to use:

• blurb - A short description of the plugin.
• category - The category of the plugin. It is recommended to follow the plugin guidelines and use one of the defined categories. There can be multiple entries.
• conflicts - Specifies that the plugin conflicts with a certain system configuration.
• copyright - The plugin's copyright information.
• license - The plugin's license information.
• provides - Specifies that this plugin provides the same functionality as another Elgg plugin or a PHP extension.
• screenshot - Screenshots of the plugin. There can be multiple entries. See the advanced example for syntax.
• suggests - Parallels the requires system, but doesn't affect if the plugin can be enabled. Used to suggest other plugins that interact or build on the plugin. See the Plugin Dependencies page for more information.
• website - A link to the website for the plugin.

Simple Example

This manifest file is the bare minimum a plugin must have.

<?xml version="1.0" encoding="UTF-8"?>
<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
	<name>Example Manifest</name>
	<author>Elgg</author>
	<version>1.0</version>
	<description>This is a simple example of a manifest file.  In this example, there are not screenshots, dependencies, or additional information about the plugin.</description>
 
	<requires>
		<type>elgg_release</type>
		<version>1.8</version>
	</requires>
</plugin_manifest>

Advanced example

This example uses all of the available elements:

<?xml version="1.0" encoding="UTF-8"?>
<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
	<name>Example Manifest</name>
	<author>Brett Profitt</author>
	<version>1.0</version>
	<blurb>This is an example manifest file.</blurb>
	<description>This is a simple example of a manifest file.  In this example, there are many options used, including screenshots, dependencies, and additional information about the plugin.</description>
	<website>http://www.elgg.org/</website>
	<copyright>(C) Brett Profitt 2011</copyright>
	<license>GNU Public License version 2</license>
 
	<category>3rd_party_integration</category>
 
	<!-- All plugins must require either elgg_version or elgg_release. -->
	<requires>
		<type>elgg_version</type>
		<version>2011010401</version>
	</requires>
 
	<!-- The path is relative to the plugin's root. -->
	<screenshot>
		<description>Elgg profile.</description>
		<path>screenshots/profile.png</path>
	</screenshot>
 
	<provides>
		<type>plugin</type>
		<name>example_plugin</name>
		<version>1.8</version>
	</provides>
 
	<suggests>
		<type>plugin</type>
		<name>twitter</name>
		<version>1.0</version>
	</suggests>
</plugin_manifest>

Elgg 1.7 and below

In Elgg 1.7 and below, manifest.xml uses a different syntax. This format is deprecated as of Elgg 1.8. Though Elgg 1.8 still supports this syntax, many options are unavailable if you choose not to use the 1.8 manifest syntax.

Syntax

The deprecated manifest.xml file uses the attributes from self-closing 'field' elements to specify keys and values:

    <field key="name" value="value" />

Keys

The following are the only keys supported in the deprecated manifest:

• author
• version
• description
• website
• copyright
• license
• elgg_version

Example

<?xml version="1.0" encoding="UTF-8"?>
<plugin_manifest>
        <field key="author" value="Marcus Povey" />
        <field key="version" value="1.0" />
        <field key="description" value="Provide a list of your or your friends recent activity!" />
        <field key="website" value="http://www.elgg.org/" />
        <field key="copyright" value="(C) Curverider 2008" />
        <field key="licence" value="GNU Public License version 2" />
</plugin_manifest>

Elgg version management

A plugin author may specify a minimum version of Elgg core required to run their plugin using:

<field key="elgg_version" value="YYYYMMDDVV" />

Where YYYYMMDDVV is the contents of the $version variable in version.php, eg: 2009021501.

Updating

To update your manifest files to 1.8, download and run the manifest_update_18.php script at https://github.com/brettp/elgg-plugin-migration-tools

Alternatively, you can run this series of regular expression find/replace:

• <field key="(.*)" value="(.*)" /> ==> <$1>$2</$1>
• <depends>(.*)</depends> ==> <requires>$1</requires>
• <requires>(.*)</requires> ==><requires>\n\t\t<type>plugin</type>\n\t\t<name>$1</name>\n\t</requires>
• <elgg_version>(.*)</elgg_version> ==> <requires>\n\t\t<type>elgg_version</type>\n\t\t<version>$1</version>\n\t</requires>
• <licence>(.*)</licence> ==> <license>$1</license>

You will then have to manually add the "<name>My Plugin</name>" field. That's it!