LimeSurvey Manual - User contributions [en]

Plugin system architecture

2014-08-20T20:47:19Z

Sparkbird:

Table of contents:{toc}

Some random stuff on plugin architecture.

A plugin can extend functionality of LimeSurvey. The plugin registers on what events it wants to extend. This could be adding a button to the menu, do something when a respondent starts or finishes the survey... the possibilities are endless.

For the plugin to be able to do it's magic it might need some special configuration. Below is the 'lifetime of a plugin':

'''beforeInstall''' When the plugin is added to the system, this event is fired on the plugin. This way the plugin can set a default config, of check for dependencies. The method can return success or failure and an optional message. This method is also fired when a new version of the plugin is uploaded. This way the plugin can handle upgrades when neccessary.

'''beforeActivate''' Like the beforeInstall event, but this time it is fired when the plugin is activated.

'''beforeDeactivate''' You guessed right, on deactivation. Might show a warning about dependencies of other plugins, lost functionaity etc.

'''beforeDeinstall''' This should handle cleanup of extra tables, config etc.

The plugins will extend a base class.

The base plugin class will initialize a storage interface and create wrapper functions for the get and set implemented in the interface.

Code below might contain mistakes, textarea doesnt have syntax checking :p

<syntaxhighlight lang="php" enclose="div">interface PluginStorage {

/**

Returns plugin data.

@param object $plugin The plugin object getting its data.

@param string | null $key The storage key, if null will return all data for the plugin.

@param string $model Name of a model in case its model specific plugin data, like for a specific question or survey.

@param int $id Id of the model for which the data is retreived

@return mixed The data stored.
*/

public function get($plugin, $key = null, $model = null, $id = null);

/**

Stores plugin data.

@param object $plugin The plugin object getting its data.

@param string $key The storage key to identify the data.

@param mixed $data The data to be stored, serialized using serialize.

@param string $model Name of a model in case its model specific plugin data, like for a specific question or survey.

@param int $id Id of the model for which the data is retreived
*/

public function set ($plugin, $key, $data, $model = null, $id = null);

}

class PluginBase {

protected $storage = 'PluginStorage';

private $store = null;

public function '''construct()

{

$this->store = Plugin::getStore($this->storage);

}

/**

This function stores plugin data.

*/

protected function set($key, $data, $model = null, $id = null)

{

if (isset($this->store))

{

return $this->store->set($this, $key, $model, $id);

}

return false;

}

/**

This function retrieves plugin data. Do not cache this data; the plugin storage

engine will handling caching. After the first call to this function, subsequent

calls will only consist of a few function calls and array lookups.

*/

protected function get($key = null, $model = null, $id = null)

{

if (isset($this->store))

{

return $this->store->get($this, $key, $model, $id);

}

return false;

}

}</syntaxhighlight>

To see how to add a new menu item and display a page when the menu item is clicked see [[Add_new_menu_and_view_by_a_plugin]]

Add new menu and view by a plugin

2014-08-20T20:41:41Z

Sparkbird:

How to write a plugin that adds a menu to the admin menubar & when clicked renders some content

1. Create a new plugin. let us call it Rewards

2. register for events afterAdminMenuLoad and newDirectRequest in the constructor

3. implement the above methods methods in the new plugin class

4. In the method afterAdminMenuLoad, add a new menu item and link it to
admin/plugins/direct?plugin=<plugin_name>&function=<plugin_action>
e.g
admin/plugins/direct?plugin=rewards&function=assignRewards

5. implement the method newDirectRequest

public function newDirectRequest(){
$event = $this->event;

// you can get other params from the request object
$request = $event->get('request');

//get the function name to call and use the method call_user_func
$functionToCall = $event->get('function');
$content = call_user_func(array($this,$functionToCall));
//set the content on the event
$event->setContent($this, $content);
}

6. implement the method plugin_action, in our case it is assignRewards().
In this method currently i am just trying to return some dummy content, you can have sophisticated page rendered.

<nowiki>public function assignRewards() {
$content = "<h1> plugin content set succesfully </h1>";
return $content;
}</nowiki>

7. The full Rewards.php
[[File:Rewards1.zip]]

8. This is how the UI looks now.
[[File:Screenshot_2014-08-21_01.34.05.png]]

File:Rewards1.zip

2014-08-20T20:40:57Z

Sparkbird:

Add new menu and view by a plugin

2014-08-20T20:40:24Z

Sparkbird:

How to write a plugin that adds a menu to the admin menubar & when clicked renders some content

1. Create a new plugin. let us call it Rewards

2. register for events afterAdminMenuLoad and newDirectRequest in the constructor

3. implement the above methods methods in the new plugin class

4. In the method afterAdminMenuLoad, add a new menu item and link it to
admin/plugins/direct?plugin=<plugin_name>&function=<plugin_action>
e.g
admin/plugins/direct?plugin=rewards&function=assignRewards

5. implement the method newDirectRequest

public function newDirectRequest(){
$event = $this->event;

// you can get other params from the request object
$request = $event->get('request');

//get the function name to call and use the method call_user_func
$functionToCall = $event->get('function');
$content = call_user_func(array($this,$functionToCall));
//set the content on the event
$event->setContent($this, $content);
}

6. implement the method plugin_action, in our case it is assignRewards().
In this method currently i am just trying to return some dummy content, you can have sophisticated page rendered.

<nowiki>public function assignRewards() {
$content = "<h1> plugin content set succesfully </h1>";
return $content;
}</nowiki>

7. The full Rewards.php
[[File:Rewards.zip]]

8. This is how the UI looks now.
[[File:Screenshot_2014-08-21_01.34.05.png]]

File:Screenshot 2014-08-21 01.34.05.png

2014-08-20T20:39:09Z

Sparkbird:

Add new menu and view by a plugin

2014-08-20T20:38:36Z

Sparkbird:

How to write a plugin that adds a menu to the admin menubar & when clicked renders some content

1. Create a new plugin. let us call it Rewards

2. register for events afterAdminMenuLoad and newDirectRequest in the constructor

3. implement the above methods methods in the new plugin class

4. In the method afterAdminMenuLoad, add a new menu item and link it to
admin/plugins/direct?plugin=<plugin_name>&function=<plugin_action>
e.g
admin/plugins/direct?plugin=rewards&function=assignRewards

5. implement the method newDirectRequest

public function newDirectRequest(){
$event = $this->event;

// you can get other params from the request object
$request = $event->get('request');

//get the function name to call and use the method call_user_func
$functionToCall = $event->get('function');
$content = call_user_func(array($this,$functionToCall));
//set the content on the event
$event->setContent($this, $content);
}

6. implement the method plugin_action, in our case it is assignRewards().
In this method currently i am just trying to return some dummy content, you can have sophisticated page rendered.

<nowiki>public function assignRewards() {
$content = "<h1> plugin content set succesfully </h1>";
return $content;
}</nowiki>

7. The full Rewards.php
[[File:Rewards.zip]]

8. This is how the UI looks now.
https://www.dropbox.com/s/i01sw6rb5lvhts6/Screenshot%202014-08-21%2001.34.05.png

File:Rewards.php

2014-08-20T20:33:41Z

Sparkbird:

Add new menu and view by a plugin

2014-08-20T20:30:06Z

Sparkbird: plugin that adds a menu to the admin menubar & when clicked renders some content

How to write a plugin that adds a menu to the admin menubar & when clicked renders some content

1. Create a new plugin. let us call it Rewards

2. register for events afterAdminMenuLoad and newDirectRequest in the constructor

3. implement the above methods methods in the new plugin class

4. In the method afterAdminMenuLoad, add a new menu item and link it to
admin/plugins/direct?plugin=<plugin_name>&function=<plugin_action>
e.g
admin/plugins/direct?plugin=rewards&function=assignRewards

5. implement the method newDirectRequest

public function newDirectRequest(){
$event = $this->event;

// you can get other params from the request object
$request = $event->get('request');

//get the function name to call and use the method call_user_func
$functionToCall = $event->get('function');
$content = call_user_func(array($this,$functionToCall));
//set the content on the event
$event->setContent($this, $content);
}

6. implement the method plugin_action, in our case it is assignRewards().
In this method currently i am just trying to return some dummy content, you can have sophisticated page rendered.

<nowiki>public function assignRewards() {
$content = "<h1> plugin content set succesfully </h1>";
return $content;
}</nowiki>

7. The full Rewards.php

8. This is how the UI looks now.
https://www.dropbox.com/s/i01sw6rb5lvhts6/Screenshot%202014-08-21%2001.34.05.png