This wiki page introduces how to develop plugins for OntoWiki. Developing Erfurt plugins is basically the same but you don't have Zend events, views and action controllers.

Folder structure for plugins

Declare the plugin folder (relative to application's root dir) in OntoWiki's config.ini:

plugins.ontowiki = ./plugins/

Currently only one folder can be declared, in future versions of OntoWiki different folders may be possible. In the same way you may declare the folder for Erfurt plugins in Erfurt's config.ini: plugins.erfurt = ./erfurtplugins/ (relative to Erfurt folder).

There every plugin has its own folder. A plugin folder can include several other plugin folders but it is not possible to have two different plugins packages parallel in one folder. Every plugin package can include different plugin classes and libraries, and it haves its own config.ini which must be located in the root folder of the plugin package. For example:

|-ontowiki/
  |-plugins/
    |-plugin-one/
    | |-config.ini
    | |-Plugin-one.php
    | |-templates/
    | |-controllers/
    | |-library/
    | |-plugin-two/
    |   |-config.ini
    |   |-Plugin-two.php
    |-plugin-three/
      |-config.ini
      |-Plugin-three-A.php
      |-another-folder/
      | |-Plugin-three-B.php
      |-api/

The class file have to be named like the inluded plugin class extended by .php, e.g. if you have a plugin class called Myplugin then you have to store it in Myplugin.php.

The plugin class

Like we said before one plugin can be composed of different plugin classes. Each of those plugin classes can provide methods for API functions or — most important for plugin developement — event handlers for OntoWiki/Erfurt events. A plugin class may extend the general plugin classes of OntoWiki or Erfurt. This is not is not necessary but it prevents a lot of problems and it provides a better interface to OntoWiki/Erfurt.


class YourPluginClass extends OntoWiki_Plugin {

  public function yourEventHandler() {

    // your event handler without event data

  }

  public function yourOtherEventHandler(&$data) {

    // your event handler with data passed
    // now you can do something with $data (but do not overwrite it accidently)

  }

  // your other stuff for the plugin class

}

Your event handlers cannot be private because the event dispatcher must be able to call them. If you want to write plugins only for Erfurt you may extend Erfurt_Plugin. You have to name the file like the plugin class extended by .php, in our example above it is YourPluginClass.php.

If you write event handler methods for events passing data, you must use references (&$var).

What to do

Writing plugins for OntoWiki is based on using events, writing event handlers, and using functionality provided by OntoWiki or Erfurt or by Zend helper classes (eg. the view helpers for OntoWiki to manipulate/extend the output). You can change templates/views, replace or insert action controllers, and doing smaller tasks like adding tabulators or menu options to windows and so on.

Using the interface, methods and objects

The parent plugin classes from OntoWiki and Erfurt provide some methods and objects as an interface for plugins to core functionality. Currently provided interface objects are:

$_erfurtApp: Erfurt object to use the Erfurt API
$_eventDispatcher: the event dispatcher object
$_pluginManager: the plugin manager object
$_action: object of currently used action controller (if available)
$_view: view object (instance of Zend_View) provided by current action controller or the viewRenderer helper
$_viewRenderer: object of currently used viewRenderer helper (if available)

Please have a look at the referenced documents how to use the methods of these objects. Some of those methods we use in our examples but generally you can do more. Methods provided by the parent plugin classes currently are:

_setEnvironment(): this method tries to allocate the $_action and $_view$ objects, because they could change between application states when event handlers are called
_getPluginRootDir(): returns the server dir where the plugin is located (as string)
_getPluginBaseUri(): returns the URL of the plugin folder, needfull when a plugin tries to add own javascript or stylesheet files to the theme
_getOntoWikiBaseUri(): returns the URL of the OntoWiki installation
_getActiveModel(): returns the URI of the currently choosen knowledge base

Maybe there will be new methods in future. If you have any requests for new simplyfied interfaces to OntoWiki/Erfurt/Zend functionality, please add your request to our issue tracker.

Replace a template

OntoWiki provides standard templates for all actions but sometimes it makes sense to replace them by your own, for example if you want to add event triggers or other new stuff to the template. This will become important for delivering plugins when you write event handlers for your own template triggers. Another case is a new template needed by a new controller action added by a plugin.

To replace a template you need at least the addScriptPath method from Zend_View (_view object) and the setScriptAction method of the viewRenderer helper (_viewRenderer).


function replaceTemplate() {

  // 1. Test for _view and _viewRenderer
  $this->_setEnvironment(); // getting the right objects for _view and _viewRenderer
        
  // 2. add the template folder within the plugin folder (use _view object)
  $this->_view->addScriptPath($this->_getPluginRootDir().'/templates/');
        
  // 3. exchange the template script (use _viewRenderer helper)
  // within your new template folder, the script must be in a folder called like controller (lowercase!)
  $this->_viewRenderer->setScriptAction('replace-template'); // set name (NAME.php) of template

  // alltogether the template is now PLUGINFOLDER/templates/resource/replace-template.php

}

Of course the example is simplyfied, usually it is better to check the obejects before, have a look a the similar event handler from our Example plugin.

Now you have to announce your event handler replaceTemplate to the ZendPostDispatch event (may also work with Zend Pre Dispatch event). If you only want to replace a template for a special action in one controller then you can add their names as prefix, dont forget default as prefix for the module. Like in the Example plugin we only replace the template for the view action of the resource controller, we will get default_resource_view_ZendPostDispatch as the name of the event the event handler has to be announced to. You can specify those announcements in the plugin's configuration file:

announce.0.event  = "default_resource_view_ZendPostDispatch"
announce.0.class  = "YourPluginClass"
announce.0.method = "replaceTemplate"

See the corresponding announcement from our Example plugin's config.ini.

Add / Replace an action controller

You will need methods from Zend's Front Controller and the Request object to add or replace a controller or only one action:


function addYourController()
{
  // 1. get front controller
  $frontController = Zend_Controller_Front::getInstance();

  // 2. get request object
  $request = $frontController->getRequest();

  // 3a. save controller name
  $controller = $request->getControllerName();

  // 3b. you can also save the action's name if you want to replace only the controller when a special action is called
  $action     = $request->getActionName(); // not needed in this example
        
  // 4. check for controller [/action] name (your new controller)
  if ($controller == 'yourcontroller') {
    // add the directory from your plugin folder where controllers are located in
    $frontController->addControllerDirectory($this->_getPluginRootDir().'/controller/');

    // alltogether the controller is now PLUGINFOLDER/controller/YourcontrollerController.php
  }
}

Now announce this event handler in your plugin's configuration file. Use ZendRouteShutdown for new controllers, ZendPreDispatch is for replacing controllers.

Plugin configuration

Every plugin package has its own config.ini — stored in the root folder of the plugin package — to make declarations about plugin's folder structure, event handlers or translation files. Currently their are four main parts: meta information about the plugin, local folder structure, announcements for event handlers and announcing additional classes (e.g. for simple integration of APIs or other libraries). It also keeps information about the plugin's state (enabled or disabled). The configuration file of the Example plugin can be found in the SVN. Every plugin configuration has to start with [general].

Meta information about the plugin

Right now meta information are not necessary but Onto Wiki may get an overview or manager of running plugins later (or you could write a plugin for that issue ;) ). But providing meta information may be helpfully at all.

[general]

;-----------------------------------------------------------------------------;
; Information about Plugin                                                    ;
;-----------------------------------------------------------------------------;

name = "Example Plugin"
description = "This is an example for an OntoWiki/Erfurt plugin."
author = "Michael Haschke"
url = "http://ontowiki.net/"
version = "$Id:$"

switch = "off";is plugin active? on|off

Describe folder structure

It may be necessary to split a plugin into different classes in several sub folders (e.g. see 'plugin-three' in our directory example above). If you add those folders to the configuration file they will be managed automatically by the plugin manager. Declare folders relative to the plugin's root folder (the folder where the configuration file is located):

;-----------------------------------------------------------------------------;
; Which folders are needed                                                    ;
;-----------------------------------------------------------------------------;

folder.0 = "./"; its not necessary to declare './' (plugin root itself)
folder.1 = "./another-folder"
folder.2 = "./api"

It's important to declare all folders you want use plugin classes from.

Announcing event handlers

You can announce methods from a plugin class as event handlers, you have to declare the event name, name of the plugin class and name of the method from that class:

;-----------------------------------------------------------------------------;
; Announcements of event handlers                                             ;
;-----------------------------------------------------------------------------;

announce.0.event  = "ZendPostDispatch"          ; name of event
announce.0.class  = "Plugin-three-A"            ; name of plugin class
announce.0.method = "changeTitleAtPostDispatch" ; name of method from plugin class

announce.1.event  = "default_resource_view_ZendPostDispatch"
announce.1.class  = "Plugin-three-B"
announce.1.method = "changeViewTemplate"

Additional class registrations

You can declare additional plugin classes which do not provide event handlers (e.g. providing an API or library for other plugins) because access to those classes will be easier through the plugin manager.

;-----------------------------------------------------------------------------;
; Announce additional Classes                                                 ;
;-----------------------------------------------------------------------------;

add.0.class = "ClassName"

Private configuration sections

In case your plugin needs some configuration internally, we encourage you to use one or more sections in your config.ini file, e.g. [private]. You also can use another name for the section or define more than one section, but in most cases a [private] section should fullfill your needs.
You can access the config in your plugin class by calling the protected _getPluginConfig() method. This method will return an instance of Zend_Config. In case your section is called [private] you would access your configuration the following way: $this->_getPluginConfig()->private->foo->bar.

Language configuration files

Your plugin can have it's own language configuration file in order to support multiple languages or change the default behaviour of Onto Wiki. You just have to create a file called string.ini in your plugin root folder and add at least two sections: [english] and [default : english]. So your file could look like this:

[english]
foo = "Bar"

[default : english]

Code definitions

Is coming later ...

Files [Hide files/form]

There is no comment on this page. [Display comments/form]

Information

Last Modification: 2010-07-05 14:40:00 by Sebastian Dietzold