UserGuide: How to write a plugin

This revision is from 2009/05/08 12:32. You can Restore it.

Do you miss some feature and have the ability to write one? Go ahead, writing plugins for LionWiki is very simple. This page will tell you everything you need to know (from LionWiki view, of course). If you're tired of reading and keen on programming, close this page and take a look on some plugins in LionWiki, they are mostly self-explanatory.

File, class, etc.(Edit)

Plugins are stored in plugins folder. They are all named "wkp_MyNewPlugin.php", this is not just convention but neccesity - LionWiki accepts only plugins with prefix "wkp_" and extension ".php".

Your plugin should contain at least one class, and must be named similarly as file - in this case MyNewPlugin. Again, this is neccessary.

Description of a plugin(Edit)

This is not at all neccessary, just recommended if you want to distribute your plugin to other LionWiki users.

If you take a look at some plugin in LionWiki, you'll see, that one of the first lines is something like this:

var $desc = array(
  array("Admin plugin", "provides advanced administration functions protected by password"),
  array(
	array("<a href=\"?action=admin-blockip\" rel=\"nofollow\">IP blocking</a>", 
			"Blocks specified addresses from editing"),
	array("<a href=\"?action=admin-blacklist\" rel=\"nofollow\">Black list</a>", 
			"List of expressions forbidden in pages"),
	array("<a href=\"?action=admin-pages\" rel=\"nofollow\">Read-only pages</a>", 
			"Can set certain pages as unwritable"),
	array("<a href=\"?action=admin-plugins\" rel=\"nofollow\">Disabled plugins</a>", 
			"List of disabled plugins")
  )
);

What does this mean? This array is intended for use in ListPlugins plugin. This plugin takes a look on all loaded plugins and gets this array and displays it. Its purpose is to be simple interface to all functionality of all plugins.

$desc array again contains array(s). This array can contain either an array(s) (starts to be confusing, right?) or tuple consisting of:

  1. Name of function, if possible with link
  2. Short explanation or usage of function

$desc array is actually tree with all leaves containing this tuple. Take a look at here how it is displayed.

This example was actually the most complicated $desc present in current LionWiki plugins, other plugins have something like this:

var $desc = array(
	array("Captcha plugin", "is a spam filtering plugin asking simple questions.")
);

Events(Edit)

In general, plugins usually works one of these two ways:

  1. Plugins register themselves to some events. These events then trigger plugins registered to this event
  2. Main program calls all plugins when some event occur, plugins then can choose to take action or do nothing

LionWiki plugin system is of type 2). List of events:

  • pluginsLoaded is triggered immediately after all plugins are instantiated, this is specifically intended for Admin plugin, so it can delete unwanted plugins
  • pluginsLoaded2 is called immediately after pluginsLoaded
  • actionBegin - triggered before "actions" (like saving a page or loading an old revision) are treated
  • writingPage - right before writing page to the file, used by spam checking plugins
  • pageWritten - right after page was written to file, used by RSS plugin
  • formatBegin - before substituting wiki syntax (Tables plugin)
  • pageLoaded - right after page (or revision) was loaded into $CON variable
  • subPagesLoaded - triggered after all subpages were inserted into the page
  • formatEnd - after substituting wiki syntax
  • formatFinished - right after formatEnd
  • template - substituting template
  • finished - right before outputting content to the browser (and therefore right before terminating the process)
  • diff - used by alternative diff plugins
  • any unknown action parameter (in URL) is triggered as event

Event is served by simply creating method with name of the event in your plugin class.

If this method returns false, LionWiki thinks that no such method exists (plugin does not want to treat this event for some reason).

Events were added to LionWiki on demand - I didn't create any events with no current use. If you're programming new plugin and miss some event, tell me, and if it's sensible, I'll add it into core LionWiki.

For almost any meaningful plugin, you'll need to know at least few things from LionWiki source. You can take a look at Understanding core LionWiki.

PHP5 vs. PHP4 objects(Edit)

LionWiki tries to be PHP4 compatible. If you want to distribute your "MyNewPlugin" to other LionWiki users, it would be good to be too PHP4 compatible. These are two simple things to keep in mind to write PHP4 compatible plugins:

  1. Name of the constructor is not __construct(), but MyNewPlugin
  2. Don't use public, private and protected in your class, declare your member variables with var $variable (synonym of public)