Difference between revisions of "Minimal Plugin"

From GeeklogWiki
Jump to: navigation, search
(Minimal plugin example)
 
m (added link to Plugin API)
 
(4 intermediate revisions by the same user not shown)
Line 12: Line 12:
 
= Plugins Directory =
 
= Plugins Directory =
  
A fully-fledged plugin typically used three directories. Let's name our plugin '''foo''' to make things clearer:
+
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/plugins/foo</tt>
Line 18: Line 18:
 
# <tt>/path/to/geeklog/public_html/admin/plugins/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 file, 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.
+
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.
 
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.
Line 25: Line 25:
 
= functions.inc =
 
= 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.
+
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.
 
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.
Line 32: Line 32:
 
= A Database Entry =
 
= A Database Entry =
  
Geeklog simply ignores any files and directories in its <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>:
+
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)
 
<pre>INSERT INTO gl_plugins (pi_name, pi_version, pi_gl_version, pi_enabled, pi_homepage)
Line 41: Line 41:
 
* <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_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_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.
 
* <tt>pi_homepage</tt> - link to our, i.e. the plugin's, homepage. Only used for information.
  
Line 46: Line 47:
  
 
<pre>DELETE FROM gl_plugins WHERE pi_name = 'foo';</pre>
 
<pre>DELETE FROM gl_plugins WHERE pi_name = 'foo';</pre>
 +
 +
This will do for now. Please note that it's actually not that hard to provide proper [[Plugin Autoinstall|install]] and [[Plugin Auto-Uninstall|uninstall]] functions.
  
  
 
= That's All, Folks! =
 
= 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:
+
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
 
<pre><?php

Latest revision as of 21:35, 23 May 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 note 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 ;-)