Plugin.php

How do I connect to the wiki ?

Current Release 1.0.3 | e107.org | Download | Changelog | Forum | Plugins | Themes | RSS Feed of Latest Changes | Atom Feed of Latest Changes

How to write a plugin

Main page > I : First Aid > II : Development > III : Administration > IV : How To's > V : Plugin Writing > VI : Theming & Shortcodes

Contents 1 The plugin.php file 1.1 General Variables 1.1.1 $eplug_name 1.1.2 $eplug_version 1.1.3 $eplug_author 1.1.4 $eplug_folder 1.1.5 $eplug_icon/$eplug_icon_small 1.1.6 $eplug_url 1.1.7 $eplug_email 1.1.8 $eplug_description 1.1.9 $eplug_compatible 1.1.10 $eplug_readme 1.1.11 $eplug_compliant 1.1.12 $eplug_menu_name 1.1.13 $eplug_conffile 1.1.14 $eplug_caption 1.1.15 $eplug_link/$eplug_link_name/$eplug_link_url/$eplug_link_perms 1.1.16 $eplug_done 1.1.17 $eplug_upgrade_done 1.2 Variables Relating To Preferences 1.2.1 $eplug_prefs 1.2.2 $eplug_array_pref 1.2.3 $upgrade_add_prefs 1.2.4 $upgrade_add_array_pref 1.2.5 $upgrade_remove_prefs 1.2.6 $upgrade_remove_array_pref 1.3 Variables Relating To Database Tables 1.3.1 $eplug_table_names 1.3.2 $eplug_tables 1.3.3 $upgrade_alter_tables 1.4 Functions 1.4.1 myplugin_install() 1.4.2 myplugin_upgrade() 1.4.3 myplugin_uninstall() 1.5 Deprecated Variables (not needed anymore) 1.5.1 $eplug_done 1.5.2 $eplug_bb 1.5.3 $eplug_latest 1.5.4 $eplug_module 1.5.5 $eplug_sc 1.5.6 $eplug_status

The plugin.php file

This file is the heart of your plugin - it defines lots of things about your plugin such as the plugin name, preferences and database definitions.

In actual fact, it is just a list of well known PHP variables with values assigned. The variables are known to e107 and used during plugin install, upgrade, and uninstall. They are also used for other e107 functionality such as determining if a plugin has menus.

These variables are discussed below. There is no required order that the variables are declared in, but convention tends to group similar types of variables together.

Note 1: some example values in the following descriptions should really be PHP constant values, defined in your plugins language file.

Note 2: all variables are PHP strings unless otherwise stated.

General Variables

Note: Setting of some of these variables is used to determine if a plugin requires installation (i.e. the admin must click the install button) or not. A plugin that requires installation is one which has one or more of the following variables set and non-empty:

• $eplug_link_url
• $eplug_link
• $eplug_prefs
• $eplug_array_pref
• $eplug_table_names
• $eplug_user_prefs
• $eplug_sc
• $eplug_userclass
• $eplug_module
• $eplug_bb
• $eplug_latest
• $eplug_status

This roughly translates to a plugin that:

• has no admin pages
• is not a module
• has no database tables it needs to create
• has no preferences to set
• has no short codes
• has no BB codes
• has no integration into the main Admin pages Status or Latest areas

$eplug_name

The name of your plugin.

$eplug_name = "MyPlugin";

$eplug_version

The version number of your plugin.

By convention:

• early versions of plugins that might be release for testing or feedback follow the sequence 0.1, 0.2, 0.3, etc.
• full releases follow the sequence 1.0, 2.0, 3.0, etc.
• interim, minor or bug fix releases follow the sequence 1.1, 1.2, 1.3, etc. or even 1.1, 1.11, 1.12, 1.13, etc.

Whatever version numbering system you use, a maximum of 10 characters are stored in the database (may be less if you use utf-8 and non-ASCII characters). In addition, if the plugin is to be uploaded to [www.e107coders.org e107 Coders] for public release the version number can not be more than 5 characters long (including the dots).

$eplug_version = "1.0";

$eplug_author

Your name, e107 user name or nickname - your choice.

$eplug_author = "bugrain";

$eplug_folder

The folder name that your plugin installs to.

$eplug_folder = "myplugin";

$eplug_icon/$eplug_icon_small

Image files to be used as icons for your plugin. Displayed on the Admin->Plugin Manager page.

The files should be 32x32 pixels and 16x16 pixels in size. Any image file type should be OK but PNG and GIF are usually used as it allows for transparent backgrounds.

$eplug_icon = $eplug_folder."/images/icon_32.png";
$eplug_icon_small = $eplug_folder."/images/icon_16.png";

Note 1: we use the $eplug_folder variable that has already been defined so that if the folder name is changed in future it only needs changing in one place.

Note 2: prior to e107 0.7 the variable $eplug_logo was used instead of these two variables.

$eplug_url

Your website - advertise yourself! Displayed on the Admin->Plugin Manager' page. A link to it is displayed on the Admin->Plugin Manager' page.

$eplug_url = "http://www.mysite.com";

$eplug_email

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.

$eplug_email = "myname@mysite.com";

$eplug_description

A brief description of your plugin. Displayed on the Admin->Plugin Manager page.

$eplug_description = "A configurable contact form to allow website visitors
to e-mail you without exposing e-mail addresses.";

$eplug_compatible

The lowest version of e107 that your plugin will work with. Displayed on the Admin->Plugin Manager page.

$eplug_compatible = "e107v0.7+";

$eplug_readme

The name of your Read Me file. This can be a simple text file, an HTML file or a PHP file which is fully integrated into e107. A link to it is displayed on the Admin->Plugin Manager page.

$eplug_readme = "admin_readme.php";

$eplug_compliant

Indicates whether or not your plugin is fully XHTML compliant or not. You can read more about this and check your plugins compliance at the W3C Markup Validation Service website.

note: the value should be a PHP boolean (TRUE or FALSE).

$eplug_compliant = TRUE;

$eplug_menu_name

A plugin can have zero, one or more associated menus.

If the plugin has no menus this variable should be set to FALSE (or just don't set it).

If the plugin has only one menu, set this variable to the menus source file without the .php extension.

If the plugin has multiple menus set this variable to TRUE. When TRUE this setting simply determines the text that is displayed instead of the Install button on the Admin->Plugin Manager page if your plugin does require installation.

$eplug_menu_name = "myplugin_menu";

for multi-language purpose use $eplug_menu_name = 'MYPLUGIN_NAME'; where MYPLUGIN_NAME is a constant defined in the language file accessed by plugin.php

Note: no .php file extension required.

Note: In e107 0.6x this was the name of your plugin's menu file (without the .php file extension. In this version, a plugin could only have one menu file.

$eplug_conffile

The name of your plugin's main admin page. This is the page that will first be displayed when a user navigates to your plugin's admin area and is normally the top item in your plugin's admin menu.

To ensure that your admin pages are displayed in the correct Admin theme, these files should all be prefixed with admin_.

$eplug_conffile = "admin_emails.php";

$eplug_caption

Text to be used as the title attribute for the link to your plugin's admin pages on the Admin->Plugin Manager page. Most browsers will display this text as a tooltip when the mouse is moved over the link.

$eplug_caption = "Configure Contact Form";

$eplug_link/$eplug_link_name/$eplug_link_url/$eplug_link_perms

Indicates if a link to your plugins page should be created (in Sitelinks) when it is installed.

$eplug_link is a PHP boolean (TRUE or FALSE).

If TRUE then you should set $eplug_link_name to the text for the link and $eplug_link_url to a URL relative to the base installation folder of e107.

Optionally, you can set the viewability of the link that is created. eg. For an admin-only plugin, you may wish to set $eplug_link_perms to Admin.

$eplug_link = TRUE;
$eplug_link_name = "My Plugin";
$eplug_link_url = e_PLUGIN."myplugin/myplugin.php";
$eplug_link_perms = "Admin"; // Optional: Guest, Member, Admin, Everyone    

$eplug_done

Message to be displayed when your plugin has been successfully installed.

$eplug_done = "Installation Successful...";

$eplug_upgrade_done

Message to be displayed when your plugin has been successfully upgraded.

$eplug_upgrade_done = "Upgrade successful...";

Variables Relating To Preferences

$eplug_prefs

An associative array of your plugins preferences and their default values to be added when your plugin is installed.

Each preference is defined with the preference name as an array element index and the preference value as the array element value.

Preference names should be assigned a prefix to uniquely identify them with your plugin as they are stored globally.

Can be set to an empty string if there are none.

$eplug_prefs = array(
   "myplugin_max_items"   => "20",
   "myplugin_visibility"  => "0"
);

An array value may also be assigned.

Note: The area available for storing preferences is limited (by database constraints), so other means (e.g. a separate database record in e107_core) should be used if a plugin has a significant amount of preference data.

$eplug_array_pref

(N.B. no ending 's')

Used for 'cumulative' preferences - where several plugins may each contribute a value. (For an example see the linkwords plugin, which links itself in as a supplementary parser using the 'tohtml_hook' pref).

Such preferences cannot be an array value

Value can be omitted, or set to an empty string, if there are no such preferences to add.

All the values provided by installed plugins are concatenated into a comma-separated list.

Note: This feature was not fully operational prior to e107 version 0.7.8

$eplug_array_pref = array (
   "tohtml_hook"       => "linkwords"
);

$upgrade_add_prefs

Preferences to be added when the user upgrades your plugin.

Can be set to an empty string if there are none.

$upgrade_add_prefs = array (
   "myplugin_width"       => "50",
);

$upgrade_add_array_pref

'Array' or 'cumulative' preferences to be added when the user upgrades your plugin.

$upgrade_remove_prefs

Preferences to be removed when the user upgrades your plugin.

Can be set to an empty string if there are none.

$upgrade_remove_prefs = array("
   "myplugin_max_items"   => "20",
);

$upgrade_remove_array_pref

'Array' or 'cumulative' preferences to be removed when the user upgrades your plugin.

Variables Relating To Database Tables

Also see plugin.php Hints and Tips

$eplug_table_names

A string array of database tables created by your plugin. Does not require the e107 database prefix.

Can be set to an empty string if there is none.

$eplug_table_names = array("myplugin_table1");

$eplug_tables

A string array containing the SQL used to create and, if required, populate your database tables when your plugin is installed. You need to use the e107 constant MPREFIX to prefix your table names.

Can be set to an empty string if there are none.

$eplug_tables = array(
   "CREATE TABLE ".MPREFIX."myplugin_table1 (
      id             int(11)     NOT NULL auto_increment,
      title          varchar(50) NOT NULL default '',
      full_name      text        NOT NULL,
      PRIMARY KEY (id)
   ) TYPE=MyISAM;",
   "INSERT INTO ".MPREFIX."myplugin_table1 VALUES (1, 'Mr','Plugin Programmer');",
);

$upgrade_alter_tables

A string array containing the SQL used to update your database tables when your plugin is upgraded. You need to use the e107 constant MPREFIX to prefix your table names.

Can be set to an empty string if there are none.

$upgrade_alter_tables = "array(
   ALTER TABLE ".MPREFIX."myplugin_table1 ADD approve char(1)
NOT NULL default '' AFTER id"
)";

Functions

Note: as the plugin.php file can be loaded multiple times for some admin pages (e.g. Plugin Manager) you should ensure that these functions cannot be declared multiple times. This can be done, for example, by wrapping the function declaration inside a function_exists() check.

myplugin_install()

Define the function myplugin_install(), where myplugin is the name of the plugin's folder, in your plugin.php file and it will be executed during the plugin's install.

This is useful as the plugin.php file is read on many occasions, so this prevents install only functionality from running when it shouldn't.

This function is run before any e107 plugin install processing is done.

myplugin_upgrade()

Define the function myplugin_upgrade(), where myplugin is the name of the plugin's folder, in your plugin.php file and it will be executed when the plugin is upgraded.

This is useful as the plugin.php file is read on many occassions, so this prevents upgrade only functionality from running when it shouldn't.

This function is run before any e107 plugin upgrade processing is done.

myplugin_uninstall()

Define the function myplugin_uninstall(), where myplugin is the name of the plugin's folder, in your plugin.php file and it will be executed when the plugin is uninstalled.

This is useful as the plugin.php file is read on many occassions, so this prevents uninstall only functionality from running when it shouldn't.

This function is run before any e107 plugin uninstall processing is done.

Deprecated Variables (not needed anymore)

$eplug_done

If not defined LAN_INSTALL_SUCCESSFUL is used instead.

$eplug_bb

Replaced by e_bb.php file in the plugin directory.

Used to add plugin specific BB codes.

$eplug_latest

Replaced by e_latest.php file in the plugin directory.

It adds content to the 'latest' menu on the admin page.

$eplug_module

Replaced by e_module.php file in the plugin directory.

Used to mark the plugin as a module.

$eplug_sc

Replaced by e_sc.php file in the plugin directory.

Used to add plugin specific shortcodes.

$eplug_status

Replaced by e_status.php file in the plugin directory.

It adds content to the 'status' menu on the admin page.

How to add an article to the handbook