Welcome to Elgg's documentation
This is the place to find documentation on all aspects of Elgg. If you would like to contribute your own documentation please do; we want this to be a real community effort!
Plugin description file
From Elgg Documentation
In the 0.9.x (see related discussion)series has been added the plugin.info file. This file like the Debian control files provides useful information that would be used for the Plugin Manager to make a better plugin management.
This file consists of a series of data fields; each field consists of the field name, followed by a colon and then the data/value associated with that field. Horizontal whitespace (spaces and tabs) may occur immediately before or after the value and is ignored there; it is conventional to put a single space after the colon.
Many fields' values may span several lines; in this case each continuation line must start with a space or a tab. Any trailing spaces or tabs at the end of individual lines of a field value are ignored.
In fields where it is specified that lines may not wrap, only a single line of data is allowed and whitespace is not significant in a field body. Whitespace must not appear inside names (of packages, architectures, files or anything else) or version numbers, or between the characters of multi-character version relationships.
Field names are not case-sensitive, but it is usual to capitalize the field names using mixed case as shown below.
[edit] Fields
[edit] Maintainer (mandatory)
The package maintainer's name, elgg.org username and email address. The name should come first, then the email address inside angle brackets <> (in RFC822 format) and the elgg.org username inside [] .
If the maintainer's name contains a full stop then the whole field will not work directly as an email address due to a misfeature in the syntax specified in RFC822; a program using this field as an address must check for this and correct the problem if necessary (for example by putting the name in round brackets and moving it to the end, and bringing the email address forward).
Example:
Maintainer: Renato Mendes Coutinho [renato] <renato.coutinho@gmail.com>
[edit] Title (mandatory)
Use this single field field to put your plugin's title. Try to keep it short and descriptive enough.
[edit] Description (mandatory)
This field contains a description of the package, consisting of two parts, the synopsis or the short description, and the long description. The field's format is as follows:
Description: <single line synopsis>
<extended description over several lines>
The lines in the extended description can have these formats:
- Those starting with a single space are part of a paragraph. Successive lines of this form will be word-wrapped when displayed. The leading space will usually be stripped off.
- Those starting with two or more spaces. These will be displayed verbatim. If the display cannot be panned horizontally, the displaying program will line wrap them "hard" (i.e., without taking account of word breaks). If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have indenting work correctly, for example).
Do not use tab characters. Their effect is not predictable.
[edit] Package (mandatory)
The name of the package. This is used in packages
Package names must consist only of lower case letters (a-z), digits (0-9), underscore (_), plus (+) and minus (-) signs, and periods (.). They must be at least two characters long and must start with an alphanumeric character.
[edit] Version (mandatory)
The version number of a package.
[edit] Distribution-URL (recommended)
Put here the URL to the stable release of your plugin. This is mandatory if your plugin resides outside elgg.org subversion repository.
[edit] Source-URL (recommended)
Put here the address for the source of your plugin code.
Take in mind that elgg project provides free subversion hosting for your plugins. Please read more about it.
[edit] Priority (recommendend)
This field indicates how relevant the package is to the elgg installation.
Valid values for this field are:
- required
Usually it means that without this mod the system wouldn't work. Usually core mods have this priority - optional
(In a sense every plugin that isn't required is optional, but that's not what is meant here.) This is all the mods that you might reasonably want to install if you didn't know what it was and don't have specialized requirements. - disrecommended
Use this if the plugin has severe bugs (like security ones) or has a high risk of irreversibly damage user's database. Specially useful to warn users about alpha versions not tested.
[edit] Tags (recommended)
A list of keywords related to the plugin, separated by commas.
[edit] Depends (recommended)
This declares an absolute dependency. A plugin will not be configured unless all of the packages listed in its Depends field have been correctly configured. In this field you should also declare which elgg version(s) is supported by your plugin.
The syntax for this and the other fields below is pretty much like Debian's. The package dependencies are separated by commas, with (optional) version specifications following each in parenthesis. For example:
Depends: elgg (>=0.9), messages (>=0.2), prfext
Note also that the plugin package name is specified in the relevant plugin.info and may be different of the folder name in the repository.
[edit] Recommends (optional)
This declares a strong, but not absolute, dependency. The Recommends field should list plugins that would be found together with this one in all but unusual installations.
[edit] Suggests (optional)
This is used to declare that one plugin may be more useful with one or more others.
[edit] Enhances (optional)
This field is similar to Suggests but works in the opposite direction. It is used to declare that the package can enhance the functionality of another package.
[edit] Conflicts (optional)
This declares that a plugin may not (or will not) work if the listed plugins are already installed in the system. Don't use this to list elgg core version requirement - use the Depends field instead.
[edit] Example file
Maintainer: Curverider <info@curverider.co.uk> Title: Advertiser Version: 1.0 Package: advertiser Distribution-URL: http://elgg.org/mod/plugins/plugin.php?id=14 Source-URL: https://svn.elgg.org/plugins/advertiser Depends: elgg (>= 0.8) Tags: advertisement, sidebar Priority: optional Description: Allows you to run ads on your site. Compatible with most advertising providers (and used with Adsense on Elgg.net).
