Writing_A_Plugin
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:
- e107 and what a plugin is
- the PHP programming language
- HTML and Cascading Stylesheets (CSS)
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 _menu. With 0.7, this is no longer the case, this is mentioned just because you will still see many plugins with this suffix on the folder names.
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 admin_ not only identify the files as being admin pages rather than main site pages, they also ensure, by the prefix, that the sites Admin theme is used when these pages are displayed and not the main site theme.
Alternately, you can declare the variable $eplug_admin and set it to true in any file that represents an admin page.
Attention ! This variable should be declared before calling class2.php
This file defines many attributes of the plugin. It must be called plugin.php (case sensitive).
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.
A file consisting of PHP define() statements. Each statement defines constant that has some text as its value. This text will, at some point, be displayed on the screen. These constants are then used throughout the rest of the plugin where that text is required.
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 plugin.php file and used by e107 to display icons next to your plugin in various sections of the Admin area.
This is the main page of your plugin, it will be viewed with a URL like:
mywebsite.com/e107_plugins/myplugin/myplugin.php
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 class2.php. This is essential and is almost always the first thing we do with a plugins page file. class2.php is the heart of e107 - it initialises all sorts of things, too much to go into (or worry about) here.
Second, we set page title (the title on the top of browser window).
Next, we include a file called HEADERF. This is a constant that has been set by class2.php and we don't need to know what the real file name is (because we trust e107!). This bit basically generates the HTML for the start of the page up to the start of the 'main' area. Notice it is a e107 specific 'require_once' used here, this function allows for when debugging is set to on.
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 myplugin.php is next. It doesn't look like much here, but this will expand quickly as we add the code to generate the required HTML. Note that, unlike some PHP conventions, we do not echo our HTML directly to the page. Instead we assign/append it to a variable ($text) that is used in the next step.
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) - $ns. $ns is actually an instance of an e107Table class that is already declared so we can use it.
To pass our HTML to e107 we call the e107Table classes tablerender function ($ns->tablerender(). This takes two parameters, the page title and the HTML for the page. In our example the page title is a constant that we would have defined in our language file, the HTML is the value of the $text variable. $ns->tablerender(MYPLUGIN_LAN_TITLE, $text);
Finally, we include the file FOOTERF. Like HEADERF it is a constant set by e107 and we don't actually care what is is just so long as we include it. This generates the HTML for the rest of the page, from the end of the 'main' section onwards.
If the plugin has a menu file (any file whose name ends in _menu.php then this menu will be available for selection on the e107 Admin->Menus page and can be positioned in any of the available menu areas as defined by the users theme.
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:
- include your language file (optional but a good idea)
- define your menu title
- define your menu item(s)
- generate the menu
Note: for clarity, I have not used a language file in the above example.
First, we give our menu a title ($menutitle). Not essential we assign it to a variable here but may be useful to do so in a more complex menu.
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 (
and
) and bold ( and ) 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.
Also see Hints and Tips and Tutorials