Minimal Plugin - Revision history

Dirk: added link to Plugin API

2009-05-23T21:35:28Z

added link to Plugin API

Dirk: Typo

2009-05-04T14:17:35Z

Typo

Dirk: links to autoinstall and auto-uninstall

2009-02-23T17:16:43Z

links to autoinstall and auto-uninstall

Dirk: Typo

2009-02-06T19:48:12Z

Typo

Dirk: Forgot pi_enabled; fixed typos

2009-02-06T19:47:00Z

Forgot pi_enabled; fixed typos

Dirk: Minimal plugin example

2009-02-06T19:39:06Z

Minimal plugin example

New page

= 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 used 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 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.

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 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>:

<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_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>

= 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]]

← Older revision		Revision as of 14:17, 4 May 2009
Line 48:		Line 48:
	<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 ~~not~~ that it's actually not that hard to provide proper [[Plugin Autoinstall\|install]] and [[Plugin Auto-Uninstall\|uninstall]] functions.	+	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.

← Older revision		Revision as of 17:16, 23 February 2009
Line 47:		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 not that it's actually not that hard to provide proper [[Plugin Autoinstall\|install]] and [[Plugin Auto-Uninstall\|uninstall]] functions.

@@ Line 25: / Line 25: @@
 = 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.
@@ Line 53: / Line 53: @@
 = 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

@@ Line 18: / Line 18: @@
 # <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.

@@ Line 12: / Line 12: @@
 = 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>
@@ Line 32: / Line 32: @@
 = 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)
@@ 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_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_homepage</tt> - link to our, i.e. the plugin's, homepage. Only used for information.