AKSW - Projects/OntoWiki/EventPluginArchitecture/PluginDevelopment

2008-07-22 16:34:10

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-07-22 16:34:10 and 2008-07-22 19:25:09

Additions:

Plugins and Events

Overview: Plugins and Events
Plugin Development
- Plugin Cookbook (work in process)
- Examples

2008-07-22 16:30:41

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-07-22 16:30:41 and 2008-07-22 16:34:10

Additions:

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

2008-07-19 18:36:44

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-07-19 18:36:44 and 2008-07-22 16:30:41

Additions:

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

Deletions:

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, it haves its own config.ini. For example:
Every plugin package has its own config.ini 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].

2008-07-18 15:59:28

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-07-18 15:59:28 and 2008-07-19 18:36:44

Additions:

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.

_setEnvironment(): this method tries to allocate the $_action and $_view$ objects, because they could change between application states when event handlers are called

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:
Now announce this event handler in your plugin's configuration file. Use ZendRouteShutdown for new controllers, ZendPreDispatch is for replacing controllers.

Deletions:

_setEnvironment(): this method tires to allocate the $_action and $_view$ objects, because they could change between application states when event handlers are called

Now you have to announce your event handler replaceTemplate to the Zend Post Dispatch 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:
Now announce this event handler in your plugin's configuration file. Use Zend Route Shutdown for new controllers, Zend Pre Dispatch is for replacing controllers.

2008-07-18 15:17:29

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-07-18 15:17:29 and 2008-07-18 15:59:28

Additions:

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/Yourcontroller Controller.php

Now announce this event handler in your plugin's configuration file. Use Zend Route Shutdown for new controllers, Zend Pre Dispatch is for replacing controllers.

2008-07-08 22:02:58

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-07-08 22:02:58 and 2008-07-18 15:17:29

Additions:

Contents

Folder structure for plugins

The plugin class

What to do

Using the interface, methods and objects

Replace a template

Add / Replace an action controller

Plugin configuration

Meta information about the plugin

Describe folder structure

Announcing event handlers

Additional class registrations

Private configuration sections

Language configuration files

Code definitions

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:

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

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 Zend Post Dispatch 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 = "Your Plugin Class"
announce.0.method = “replaceTemplate”
See the corresponding announcement from our Example plugin's config.ini.

Add / Replace an action controller

Deletions:

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

$_view: 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 their stuff we will use in our examples but generally you can do more. Methods provided by the parent plugin classes are:

Change a template

Replace an action controller

2008-05-18 22:45:24

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-05-18 22:45:24 and 2008-07-08 22:02:58

Additions:

Every plugin package has its own config.ini 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].

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.
%%(php)
class Your Plugin Class extends Onto Wiki_ 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 Your Plugin Class.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 generell 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: object of currently used viewRenderer helper (if available)

_setEnvironment(): this method tires 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.

Change a template

Replace an action controller

Deletions:

2008-05-18 22:40:48

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-05-18 22:40:48 and 2008-05-18 22:45:24

Additions:

How to develop an OntoWiki Plugin

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.

Deletions:

How to develope an OntoWiki Plugin

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

2008-05-16 20:55:03

Comparison for /Projects / Onto Wiki / Event Plugin Architecture / Plugin Development of 2008-05-16 20:55:03 and 2008-05-18 22:40:48

Additions:

|-another-folder/
| |-Plugin-three- B.php
|-api/

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.
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 = "Zend Post Dispatch" ; 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”
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 = "Class Name"

Deletions:

In that folder 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, it haves its own config.ini. For example:

|-another-folder/
| |-Plugin-three- B.php
|-api/

It may be necessary to split a plugin into several plugin class in several sub folders (e.g. see plugin-three in our directory example above).