View source for Minimal Plugin

= 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 <tt>/path/to/geeklog/plugins</tt> directory
* a <tt>functions.inc</tt> file in that directory
* an entry in the <tt>gl_plugins</tt> table


= Plugins Directory =

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

# <tt>/path/to/geeklog/plugins/foo</tt>
# <tt>/path/to/geeklog/public_html/foo</tt>
# <tt>/path/to/geeklog/public_html/admin/plugins/foo</tt>

The first directory contains the plugin's main code, the <tt>functions.inc</tt> 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 <tt>functions.inc</tt> file is where the plugin API is implemented. In other words, this file contains the code that interfaces with Geeklog.

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


= A Database Entry =

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

<pre>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/');</pre>

The fields have the following meaning:
* <tt>pi_name</tt> - name of our plugin. This '''must''' match the name of our directory in the <tt>plugins</tt> directory!
* <tt>pi_version</tt> - 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.
* <tt>pi_gl_version</tt> - 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.
* <tt>pi_enabled</tt> - contains 1 (one) when the plugin is enabled and 0 (zero) when it's disabled.
* <tt>pi_homepage</tt> - link to our, i.e. the plugin's, homepage. Only used for information.

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

<pre>DELETE FROM gl_plugins WHERE pi_name = 'foo';</pre>

This will do for now. Please not that it's actually not that hard to provide proper [[Plugin Autoinstall|install]] and [[Plugin Auto-Uninstall|uninstall]] functions.


= That's All, Folks! =

Well, not quite. Let's implement one plugin API function in our <tt>functions.inc</tt> 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 <tt>[foo:]</tt> autotag. This is the complete content of our <tt>functions.inc</tt> file:

<pre><?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;
    }
}

?></pre>

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


[[Category:Plugin Development]]