-
-
Notifications
You must be signed in to change notification settings - Fork 214
plugin.php_and_plugin.xml
The plugin.xml is introduced in e107 v2.0, and will replace the plugin.php file going forward. This will provide much more flexibility with plugins, as well as using the file for its intended purpose. While e107 will continue to support the plugin.php file, it is considered deprecated and may not be supported beyond v2.0.
Note that any database tables used must now be defined in a xxx_sql.php file (previously this was optional).
This file is the heart of your plugin - it defines lots of things about your plugin such as the plugin name, preferences and configuration options. It is used by the plugin manager for plugin install, upgrade and uninstall, and it is used by other parts of the core to obtain information about your plugin.
Let's look at an example file:
<?xml version="1.0" encoding="utf-8"?>
<e107Plugin name="Forum" version="2.0" compatibility="0.8" installRequired="true" xhtmlcompliant="true" >
<author name="e107 Inc." url="http://e107.org" />
<description>This plugin is a fully featured Forum system</description>
<category>content</category>
<languageFiles>
<file type='install' path='languages/--LAN--_install.php' />
<file type='log' path='languages/--LAN--_log.php' />
</languageFiles>
<adminLinks>
<link url='forum_admin.php' description='Configure Forum' icon='images/forums_32.png' iconSmall='images/forums_16.png' primary='true' >Configure Forum</link>
<link url="forum_admin.php" description="Forum Front Page" icon="manage" >Front Page</link>
<link url="forum_admin.php?cat" description="Create Forum Parents" icon="add" >Create Parents</link>
<link url="forum_admin.php?create" description="Create Forums" icon="images/forums_16.png" >Create Forums</link>
<link url="forum_admin.php?opt" description="Forum Preferences" icon="settings" perm="mainadmin" >Preferences</link>
</adminLinks>
<siteLinks>
<link url="forum/forum.php" perm='everyone'>Forum</link>
</siteLinks>
<pluginPrefs>
<pref name="forum_show_topics">1</pref>
<pref name="forum_postfix">[more...]</pref>
<pref name="forum_poll">255</pref>
<pref name="forum_popular">10</pref>
<pref name="forum_track">1</pref>
<pref name="forum_eprefix">[forum]</pref>
<pref name="forum_enclose">1</pref>
<pref name="forum_title">Forums</pref>
<pref name="forum_postspage">10</pref>
<pref name="forum_threadspage">25</pref>
<pref name="forum_hilightsticky">1</pref>
</pluginPrefs>
<userClasses>
<class name="forum_moderator" description="Moderator of all forums" />
</userClasses>
<extendedFields>
<field name="viewed" type='EUF_TEXTAREA' default='0' active="true" />
<field name="posts" type='EUF_INTEGER' default='0' active="true" />
</extendedFields>
</e107Plugin>
The following sections describe the various tags. Where a tag or attribute is described as 'mandatory', it must be present to avoid (sometimes obscure) errors. If necessary define it with an empty string.
WARNING : MUCH OF THE INFORMATION BELOW IS OUTDATED
This is the namespace the configuration lives in, all plugin.xml files must begin and end with this tag.
<e107Plugin name="Forum" version="2.0" compatibility="0.8" installRequired="true">
... all content belongs here ...
</e107Plugin>
Key attributes of the plugin are also defined here:
[mandatory]
The name of your plugin. This MUST be in English and NOT a constant (LAN_XXX). Equivalent constants are determined by the 'lang' attribute.
<e107Plugin name="Forum" lang="PLUG_NAME_CONSTANT" ...
[mandatory]
The version number of your plugin.
<...version="2.0"
This must follow the PHP-Standardized version number, as specified here: http://php.net/manual/en/function.version-compare.php
This is used to show the version number on the main plugin page, and also to determine if you have uploaded a new version and require your plugin to run the update routines.
[recommended]
For integration of your plugin into the admin navigation. Choose from either: settings, users, content, tools, manage, misc, about
<category>content</category>
[mandatory]
The lowest version of e107 that your plugin will work with. Displayed on the Admin->Plugin Manager page. This must also follow the PHP-Standardized version number. If the user's e107 version number does not meet the requirements, installation will not be allowed
<compatibility>0.7.10</compatibility>
[mandatory]
This indicates whether or not your plugin will require installation. In the past we let the plugin manager attempt to determine this based on what variables were set in plugin.php, this is no longer the case. To provide better control by the plugin author it is now a required fields in the plugin.xml file.
<installRequired>true</installRequired>
[mandatory]
Identifies you, and some information about you.
<author name="e107dev" url="http://e107.org/" email="[email protected]" />
Note the ' /' to close the tag at the end.
[mandatory]
Your name, e107 user name or nickname - your choice.
<...name="e107dev"
[mandatory]
Your e-mail address, useful to get feedback and bug reports on your plugin. A mailto link to it is displayed on the Admin->Plugin Manager page.
<...email="[email protected]"
[mandatory]
Your website - advertise yourself! Displayed on the ''Admin->Plugin Manager' page. A link to it is displayed on the ''Admin->Plugin Manager' page.
<...url="http://www.mysite.com" >
[mandatory]
A brief description of your plugin. Displayed on the Admin->Plugin Manager page.
<description>A configurable contact form to allow website visitors to e-mail you without exposing e-mail addresses</description>
The folder name that your plugin installs to. If the plugin is not uploaded into this folder, it will be completely ignored by the plugin manager.
<folder>forum</folder>
Required if comments can be associated with this plugin - specifies the tag used, so that comments can be deleted when the plugin is uninstalled.
Multiple lines of this format are permitted if the plugin uses more than one comment tag.
Example format:
<commentID>forum1</commentID>
<commentID>forum2</commentID>
The E107 admin log supports multi-language titles for the entries, if generated by the plugin. This specifies the language file containing these titles. For a simple plugin, it may be the file containing all the language defines; for a more complex plugin there may be a specific file for these messages.
A path and filename from the root of the plugin/s folder must be specified, as the following examples:
<logLanguageFile filename='language/--LAN--/admin_calendar_log.php' />
<logLanguageFile filename='language/--LAN--_calendar_log.php' />
In both cases the text '--LAN--' is replaced with the current language before loading the file.
Sometimes there are a reasonable number of language defines which are required only during install/uninstall/upgrade (this doesn't include strings displayed by, for example, plugin manager). Examples include a need to pre-populate a DB table with standard messages. To allow for this circumstance, it is possible to define a language file which is loaded only during install/uninstall/upgrade.
A path and filename from the root of the plugin/s folder must be specified, as the following examples:
<logLanguageFile filename='language/--LAN--/admin_calendar_log.php' />
<logLanguageFile filename='language/--LAN--_calendar_log.php' />
In both cases the text '--LAN--' is replaced with the current language before loading the file.
[mandatory]
These options control the behavior and appearance of your plugin in the plugin manager. All options here must be between the tags:
<administration>
<configFile>forum_admin.php</configFile> - File directed to for plugin configuration
<icon>images/forums_32.png</icon> - 32x32 pixel icon shown in plugin manager
<iconSmall>images/forums_16.png</iconSmall> - 16x16 pixel icon show in admin dropdown
<caption>Configure Forum</caption> - Text shown when hovering over plugin icon
<installDone>Your forum is now installed</installDone> - Message shown to user when plugin has been installed
</administration>
Any image file type should be OK; PNG and GIF are usually used as they allow for transparent backgrounds.
Indicates if a link to your plugins page should be created in Sitelinks when it is installed (or deleted when the plugin is uninstalled).
<menuLink name="Forum" url="forum.php" perm='everyone' active='true' />
name - Name of the link to be added
url - URL to be added, relative to the current plugin directory
perm - Sets the visibility perms for the link (guest, member, admin, everyone)
active - If set to false, this link will be removed on plugin upgrade
Each entry inside the section defines a specific (preference value, or setting). These determine the main preferences that are added to your database when the plugin is installed. They are added to the main preferences and will be assigned to the $pref array on each pageload. The preferred method for plugins is to use , which works in a similar fashion and stores the values in it's own table row.
You can specify each pref as a separate key/value pair:
<pref name="forum_show_topics">1</pref>
<pref name="forum_old_pref" active="false" >test</pref>
Creates $pref['forum_show_topics'] = '1'
Setting the 'active' parameter to false will cause the pref to be removed on plugin upgrade
Or you can have the pref as an associative array:
<pref name="forum_tmp" type="array">
<key name="pref1" active="false">val1</key>
<key name="pref2">val2</key>
<key name="pref3">val3</key>
</pref>
Removes:
$pref['forum_tmp']['pref1'] - since the 'active' parameter is set to false
Creates:
$pref['forum_tmp']['pref2'] = 'val2';
$pref['forum_tmp']['pref3'] = 'val3';
Then there are two 'special' pref formats:
This adds a value to the comma-separated list stored in $pref['pref_name'] - useful for accumulating a list of those plugins which are active in a particular area (e.g. hooked parsers) (as previously defined in $eplug_array_pref)
Will create a new userclass on plugin install. Any number of these items may exist.
<userclass name="forum_moderator" description="Moderator of all forums" />
name - Name of the userclass to be added
description - The description of the userclass
The class name is always converted to upper case. The class is added on upgrade only if it doesn't already exist. The class is removed (including removing membership of the class from all users) on uninstall.
This will allow a plugin to create a new extended user fields on plugin install.
<extendedField name='viewed' type='EUF_INTEGER' default='0' active="true" />
name - Name of the field to added. This will ALWAYS be auto prepended with 'plugin_'<plugin_folder>
type - Type of field to add, this should be one of the constants found in user_extended_class.php
default - The default value for the field
active - Whether or not the field is active, setting this to 'false' will tell the system
to delete the field on upgrade. This field on not required for install.
Each entry inside the section allows the plugin author to configure custom code that will be executed during install, upgrade, or uninstall. This code can be executed before the plugin manager executes it code, or after. There are three possible sections inside the section and they all contain the same parameters.
Valid sections are: <install ... /> <upgrade ... /> <uninstall ... />
<install when="post" type="classFunction" file="forum_management.php" class="forum_management" function="forum_install_post" />
when - (pre, post)
type - (classFunction, fileFunction)
file - filename to load that contains the function or class
class - If 'classFunction' was specified, the name of the class
function - The name of the procedural function or class function that needs to be executed
"when" determines when the management routine is executed:
'pre' - executes the routine after validity checks are complete, but before any processing which affects the overall installation is done (so for install, the DB tables haven't been created, for example).
'post' - executes the routine last thing, immediately before updating the plugin install status in the DB.
These functions must return a string value, which may be an empty string. This string is included in the text which is displayed after the install/uninstall/upgrade has been completed.
It is perfectly acceptable to have both 'pre' and 'post' management routines.
There is no need to define any of these sections if they are not required. Note that during an upgrade, any database tables that have been changed or added will be automatically updated as the first step in the upgrade process.
This section allows specification of plugin dependencies; prerequisites for a successful install.
An example section is:
<depends>
<plugin name='chatbox_menu' />
<plugin name='calendar_menu' min_version='3.70' />
<PHP name='core' min_version='5.2.5' />
<MySQL name='server' min_version='4.9' />
<extension name='curl' min_version='1.3' />
<extension name='mb_string' />
</depends>
Thus specific E107 plugins can be required, optionally of a minimum version. Specific PHP extensions can be required, again optionally of a minimum version. While it is strongly preferred that plugins work with any version of PHP and MySQL supported by E107 itself, it is also possible to require a minimum version of them.
All version numbering must be in the PHP-Standardized version number format.
Note that version checking is only carried out on install and upgrade; there is no ongoing checking that the requirements are met, nor is uninstallation of the required plugins prevented in any way.
As with any XML-format file, comments may be added:
<!-- This is a comment -->
In particular, for any plugin.xml file which is being saved in CVS or other versioning system, an appropriate tag should be added; e.g.:
<!-- $Id: plugin.xml,v 1.2 2008/08/12 19:59:59 e107steved Exp $ -->
(In the case of CVS, at least, the above tag will be updated on each new commit).
XML supports just five entities, and requires that these are escaped within data fields. These are:
& - ampersand
< - 'less than' or tag opening character
> - 'greater than' or tag closing character
" - double quotation mark
' - single quotation mark (Apostrophe)
The curly brackets {...} have a special function; if they are used they must be 'escaped' with a backslash:
<pref name="Title" value="Formatted \{SHORTCODE\} text">
At present the 'escaping' is removed within pref values, but not elsewhere.
e107 v2.x