This brief HowTo explains how to write your own LightPress plugins. If you follow this tutorial, you will not only be able to write a plugin, but will understand how our plugin system works. (Howto in development, refresh the page to view the latest version).
Plugin Types
To better understand the LightPress plugin system, we can distinguish between two classes of plugins: those that directly manipulate data, and those that set template variables. The plugin's behaviour mainly depends from the point in the LightPress process where it is run (the hook, explained below), and from the desired action. An example of the first class of plugins is Jerome's Preformatted, while an example of the second class is the Links plugin in the standard LightPress distribution, which displays your WP links (blogroll, etc.) in the sidebar. Both classes share the same plugin structure (properties and methods), the difference is in the code you write.
Hooks
As with most other plugin systems, LightPress plugins can be attached to one or more predefined hooks, which are nothing more than points in code identified by a text label, where the system checks for, and runs, any plugin which have been declared active for that particular label. So if your plugin needs to modify the blog header, you would look for a "header-something" hook and declare it inside your plugin (more on this later).
As of LightPress 1.0.4, there are seven defined hooks:
-
get_posts -
get_posts_loop -
start_render -
sidebar -
parse_post -
parse_comment -
render
The hooks' names roughly correspond to the relevant method in the Frontend class, so that if you are unsure what a hook is for, you can quickly find the relevant part of the code.
Plugins are classes
Every LightPress plugin is contained must be a class, contained in a file with the same name of the class itself in the
plugins/
folder. Let's start developing our HelloWorld plugin by opening a file in the
plugins/
folder named
HelloWorld.php
, and declaring an empty class (the comments at the beginning of the file are optional, but it's good practice to add them).
Even though our plugin is a class, is valid PHP code, and lives in the right file at the right place, it is not yet a valid LightPress plugin. In order to be used by our plugin system, a PHP class needs two mandatory properties, and three methods.
Mandatory properties
Two properties are needed in your plugin class to tell LightPress if the plugin is active, and in which hooks to run it. The first property is a boolean value called
active
, the second property is an array called
hooks
containing one or more hook labels. Let's add them to our HelloWorld plugin:
By adding the two properties, we are telling the LightPress Frontend that our plugin is active (more on this later), and that it must be attached to the
get_posts_loop
hook.
Mandatory methods
Three methods are needed in your plugin class for the LightPress Frontend to be able to correctly create an instance, run your plugin, or hide it from the page.
Class constructor The first method, unsurprisingly, is the class constructor, a method with the same name of your class used by PHP to initialize a class instance. Your plugin class needs to have a constructor, because the Frontend will pass an argument to it. Let's add the constructor to our class, and a private property to hold its argument.
As you have probably guessed from the above code, the single argument passed to the constructor is the running instance of the Frontend itself. Using this instance, you can access and use from your plugins every property or method inside Frontend, eg the database driver (
$db =& $this->_frontend->db;
), the template object (
$tpl =& $this->_frontend->tpl;
), your blog's options (
$opt_charset = $this->_frontend->options['charset'];
), etc. The only thing you should make sure of, is to always manipulate (eg receive and set) the frontend instance and all its properties as a reference, otherwise you will not be using the right object but a copy of it.
hide() The second method we have to add to our plugin is called
hide
, and is used by the Frontend in those rare situations where the plugin cannot be run, usually when the URL is incorrect and there are no posts to display. This method is only useful for plugins that directly set template variables (e.g. the Links or Delicious plugins included with LightPress), but it's a good idea to include it anyway.
run()
method is where everything happens, as it's the method called from Frontend to run the plugin. This method accepts a single argument, a generic payload whose contents depend from the hook where
run()
is called. In our example, the
get_posts_loop
hook passes to our
run()
method an array containing all the current post's attributes. As in the constructor example above, the
run()
argument is passed by reference, so that any addition/modification you make (eg replacing the post date, or the post content, etc.) are applied to the same object used by Frontend, and not on a copy.
As you can see from the above code, our HelloWorld plugin is not particularly useful, limiting itself to setting the post content to 'Hello World!' in the unlikely case it is empty.
Declaring Your Plugin
What is left before our plugin can be run by LightPress, is to add it to the
plugins
option in
config.php
. The option is an associative array, haviong as keys the plugin names, and as values an optional string to limit the context where the plugin is run: if your plugins is only useful eg when viewing a single post page, you can save some processing cycles by setting it to 'post', so that Frontend knows it can safely skip it in all other contexts (index page, categories, search, etc.).
Template-based Plugins
Template-based plugins (as opposed to plugins like HelloWorld which manipulate the live data) are easier and less risky to develop. You can find quite a few of them included with LightPress. Only remember to include the appropriate template variable in your templates, otherwise your plugin will run, but no output will be shown.