Revision as of 17:16, 23 February 2009

Writing A Minimal Geeklog Plugin

Writing a Geeklog plugin isn't really hard. This example demonstrates the absolute minimum required for a Geeklog plugin.

You need:

• a directory in the /path/to/geeklog/plugins directory
• a functions.inc file in that directory
• an entry in the gl_plugins table

Plugins Directory

A fully-fledged plugin typically uses three directories. Let's name our plugin foo to make things clearer:

1. /path/to/geeklog/plugins/foo
2. /path/to/geeklog/public_html/foo
3. /path/to/geeklog/public_html/admin/plugins/foo

The first directory contains the plugin's main code, the functions.inc file (we come to that in a moment), SQL files, languages files, and config data. The second directory contains the part of the plugin that is visible by a typical user. And the third directory contains the admin interface.

But the last two directories are optional. For a plugin without a public UI and without an admin interface, you can simply leave them out.

functions.inc

The functions.inc file is where the plugin API is implemented. In other words, this file contains the code that interfaces with Geeklog.

If you open up lib-common.php and scroll to the end of that file, you'll see the piece of code that loads the functions.inc of all the installed and enabled plugins.

A Database Entry

Geeklog simply ignores any files and directories in the plugins directory. To tell Geeklog that our foo directory is supposed to be a plugin, we need an entry in the gl_plugins table. Only then will Geeklog recognize our plugin and load the functions.inc:

INSERT INTO gl_plugins (pi_name, pi_version, pi_gl_version, pi_enabled, pi_homepage)
  VALUES ('foo', '1.0.0', '1.6.0', 1, 'http://www.example.com/');

The fields have the following meaning:

• pi_name - name of our plugin. This must match the name of our directory in the plugins directory!
• pi_version - version number of our plugin. It's completely up to us to decide what the version number means. It's recommended to follow the usual convention of two or three numerical values separated by dots.
• pi_gl_version - the version of Geeklog required to use this plugin. This isn't actually checked at the moment and is mostly for the user's information.
• pi_enabled - contains 1 (one) when the plugin is enabled and 0 (zero) when it's disabled.
• pi_homepage - link to our, i.e. the plugin's, homepage. Only used for information.

The above INSERT statement acts as our "install script". To uninstall, we would use

DELETE FROM gl_plugins WHERE pi_name = 'foo';

This will do for now. Please not that it's actually not that hard to provide proper install and uninstall functions.

That's All, Folks!

Well, not quite. Let's implement one plugin API function in our functions.inc file so that our plugin actually does something. We'll pick an autotag, since that doesn't require any user or admin UI. So here's a function that implements a [foo:] autotag. This is the complete content of our functions.inc file:

<?php

function plugin_autotags_foo($op, $content = '', $autotag = '')
{
    if ($op == 'tagname' ) {
        return 'foo'; // this is the name of our autotag
    } elseif ($op == 'parse') { // we're supposed to do something ...
        $word = COM_applyFilter($autotag['parm1']);
        $url = 'http://en.wikipedia.org/wiki/' . $word;
        $foo = COM_createLink("Look up \"$word\" on Wikipedia.", $url);

        return $foo;
    }
}

?>

So what does it do? That is left as an exercise for the reader ;-)