Plugin Registration

From KnowledgeTree Document Management Made Simple

Given that KnowledgeTree is entirely driven by plugins, the basics of creating and registering a plugin are essential for any new developer. Lucky for you, it's also dead simple. There are just three things you need to understand about Plugins & KnowledgeTree to have a solid grasp of how it works:

1. KnowledgeTree is totally dynamic - everything works by having "slots" and "registries", with the actual components being selected "on the fly".
2. Every one of those components needs a way to name it uniquely - be it a column type, a document action, or a admin dispatcher. Each one therefore gets a namespace - a name that's unique across all KT installations. The format for these is usually something like: plugin_creator.plugin_name.whatever.kind.of.component. For example, if I was creating a new plugin to provide a workflow trigger that mails a copy to someone, then i'd call the plugin something like bshuttle.emailtrigger.plugin
3. Plugins should be self-contained: they should have everything inside their folder (e.g. not physically change any of the normal KT code).

The simplest example

So: Having said that, lets look at a dead-simple plugin from the Column Writing Tutorial.

<?php

// Tutorial code from wiki.ktdms.com

require_once(KT_LIB_DIR . "/plugins/plugin.inc.php");
require_once(KT_LIB_DIR . "/plugins/pluginregistry.inc.php");

These provide the two tools we'll need to get started - the first provides the KTPlugin class, which we'll be subclassing. The second provides the KTPluginRegistry singleton (the first of many singletons in KT), which is what we actual register with.

class TutorialColumnPlugin extends KTPlugin {
     var $sNamespace = 'wikitutorial.columntutorial.plugin';

The basics. These lines create our new plugin class, and give it a namespace.

     function TutorialColumnPlugin($sFilename = null) {
          $res = parent::KTPlugin($sFilename);
          $this->sFriendlyName = _kt("Column Tutorial Plugin");
     }

Here we give the plugin a user-friendly name. We use a Constructor to do this since the "Friendly Name" will probably depend on the language of the user, and translation is handled by the _kt() function.

     function setup() {
          $this->registerColumn(_kt("Tutorial Column"), 'wikitutorial.columntutorial.column', 'TutorialColumn','TutorialColumn.php');
     } 

The meat of the plugin. The "setup()" function is called by the plugin registry to do the hard work of registering all the bits and pieces. We'll look at what goes here in more detail a little further down, under Registration.

}


$oRegistry =& KTPluginRegistry::getSingleton();
$oRegistry->registerPlugin('TutorialColumnPlugin','wikitutorial.columntutorial.plugin', __FILE__);

?>

And finally, the code which tells the Plugin Registry about the plugin. Two things are essential:

1. You must use =& when getting the registry (or you'll end up with a copy, not a reference. see References in KT for more details).
2. The format for the registerPlugin call is:
   1. Plugin class name
   2. Plugin Namespace
   3. the file where its located (in this case the special variable __FILE__ which refers to the current file).

Registration

The major point of a plugin is to register various different components. As stated before, these range from the simple to the complex - from Document Actions to Browse Columns. A quick overview is given below, but the important common features are:

1. The class name which provides the item (e.g. KTCheckOutAction)
2. The filename where that class can be found (e.g. KTDocumentActions.inc.php - if you don't start the filename with a /, it will assume that its relative to the current directory.)
3. A namespace name for the item (e.g. ktcore.actions.checkout)

FIXME: fill in the stubs for each different function