Writing A Plugin
e107 Wiki: English | Русский | Deutsch | Français | Magyar | Português | Български | Česky | Nederlands | Ελληνικά | Italiano | Norske | Polska | Slovenščina | Español | Svenska | Translate: Wiki | Page
This article aims to lead the plugin writing beginner through the basics of writing a simple plugin for e107. It will not go in to detail on every aspect of plugin writing.
Certain assumptions are made, specifically that you are familiar with the basics of:
The example plugin in this article is called myplugin. It will have an admin page where some preferences can be set by the site administrator, a main page and a menu.
All plugins reside in their own folder within the e107_plugins folder. Prior to e107 0.7, if the plugin required a menu then the folder name had to end with
Actually, within your plugins folder there are only a few rules as to what goes where. After that, you are free to create whatever directory structure suits your plugin best.
For this example, we will use a fairly common structure within your plugins folder. Here's the basic layout we will be using:
e107_plugins (dir) | +--myplugin (dir) | | | +--images (dir) | | +-- icon_16.png | | +-- icon_32.png | | | +--languages (dir) | | +-- myplugin_English.php | | | +--plugin.php | +--admin_menu.php | +--admin_config.php | +--admin_readme.php | +--help.php | +--myplugin.php | +--myplugin_menu.php
Note the files prefixed
Alternately, you can declare the variable
This file defines many attributes of the plugin. It must be called
The file basically contains a list of PHP variables with values that tell e107 information about the plugin such as the plugins name, version, author, etc.
The file is read when the e107 Admin->Plugin Manager page is displayed and is used when a plugin is installed, updated or uninstalled. It can also be read by e107 under other circumstances.
See plugin.php for more details about this file.
myplugin_English.php (language file)
A file consisting of PHP
This file can then be translated into other languages to easily convert the whole plugin in to a different language.
It is a good idea to always create a language file for your plugin even if you are only using a small amount of pre-defined text on your plugins pages. If you don't, it can be quite a chore to add one later in development.
Two image files, the first is 16x16 pixels, the 2nd is 32x32. They do not have to be PNG files, other file types are allowed.
References to these files are added to the
This is the main page of your plugin, it will be viewed with a URL like:
Its job is to format the HTML for the 'main' section of the page. The main section is the bit that isn't the header, footer or a menu area. Obviously, where this is depends on the theme that is in use, but this should not concern you. Just concentrate on writing the HTML to display whatever you need.
This file needs to perform certain actions at the start and end to ensure the whole page is displayed correctly. Fortunately, this is not much and is nicely hidden from you by e107.
So, what's going on in this file?
First, we include
Second, we set page title (the title on the top of browser window).
Next, we include a file called
The language file is included next. include_lan checks that the set language (e_LANGUAGE) exists, if not, it defaults the language to English.
The main part of our
The penultimate step is to pass our HTML to e107 to get it displayed on the page. To do this we use a well known variable (a variable that has been set by e107 and is guaranteed to be available) -
To pass our HTML to e107 we call the
Finally, we include the file
If the plugin has a menu file (any file whose name ends in
This file has no predefined structure other than it must pass the HTML it generates to e107 for including in the page at the end.
The file is included by e107 when it is needed, you cannot assume that the menu is before or after your page or any other menu so you cannot (generally) assume that certain things has happened.
This file defines the menu that is displayed in the Admin area of your plugin. The menu provides links to any options, configuration, data input, etc. pages that your plugin might need to allow an Administrator to perform administrator tasks.
For example, you may have a preferences page to allow the Administrator to tailor your plugin to only make it available to members of a specific userclass or to set the number of items displayed on the main page.
There are four basic steps that you should do in this file:
Note: for clarity, I have not used a language file in the above example.
First, we give our menu a title (
Next, we add our two menu options, each has three parts - Name, PHP file, ID. The Name is the text that will be displayed to the user, the PHP file is the plugins file that will handle the functionality for that admin menu and the ID is a unique (within you plugin) identifier for the menu option (an example of its use is to highlight the selected menu option in some way to distinguish it from other menu options).
The menu options are then used to build a fairly complex array. Don't worry too much at this stage how this works if you don't understand it, just follow the pattern exactly as above.
Finally, we call a function to pass our menu details back to e107 to include it in the Admin page.
A simple file this one. It is used to display some help text to the Administrator when they are viewing your plugin's Admin pages.
The help text is free format and can be whatever you think appropriate.
Convention is that the text is split into paragraphs and that paragraphs have an option bold heading. Uses the standard HTML markup paragraph (<p> and </p>) and bold (<b> and </b>) tags for this.
This page is included here purely to show an example of an admin preferences page. Equally, it could have been a page that adds, updates and deletes from a plugins database table (if it had one).
The idea is not to show how to write the 'preferences' or 'database' code (as there are many ways of doing this) but to give the PHP file structure that goes around this functionality.
Note: See point "Something on auth.php (Workaround on a problem)" for further informations on including your own scripts in this script. --Marco.link 03:40, 23 August 2006 (CDT)
Some plugins have a 'Configure' option within the drop-down on the 'Menus' page. This is (obviously) intended to allow quick configuration of options affecting that menu display.
There are two ways of linking to this option.
The simplest is to include a file 'config.php' within your plugin directory - this executes whatever configuration code is required.
For plugins with multiple menus, you can have multiple configuration files, named menufilename_config.php.
You must go for one option or the other!
In many cases the file will contain a simple redirect to the admin_config.php menu, perhaps with an associated query:
This is non-functional but it is always a good idea to include it.
It should give some information about your plugin, what it does, current version, recent changes/updates, contact e-mail - that sort of thing.
This file contains the SQL that creates the tables used by the plugin.
It isn't actually PHP code, just plain text.
It is used by the e107 Database Tool to check the validity of the plugins tables. If a discrepancy is found between this file and the table in the database then the administrator can choose to attempt to repair the table.