The plugin bus classes are important if you want your plugin to act on certain events in Opinio. For example, when a respondent has completed a survey, you want to do something with the data (like sending an email). To know when this respondent has completed, you need to receive an event notification.
To receive this notification, the plugin must register itself on the plugin bus. There are two plugin buses available:
PluginBusSurvey: handles the events in the Survey module. Event types are DisplayQuestionEvent, NewRespondentEvent, RespondentCompleteEvent, ResponseEvent,
PluginBusAdmin: handles administration module events. When a new Opinio user is created, for example, a NewUserEvent is fired. Event types are: NewSurveyEvent, NewUserEvent, SurveyDeletedEvent, UserDeletedEvent
For example, in the start() method of your plugin, you can register your plugin to listen to the administration events:
public void start() {
// add this plugin to the admin bus
PluginBusAdmin.addToBus(this);
}
This plugin must also implement the handleEvent() method, so that the events received are handled correctly. For example:
public void handleEvent(PluginBusEvent event) {
if (event instanceof NewSurveyEvent) {
NewSurveyEvent nsEvent = (NewSurveyEvent) event;
long surveyId = nsEvent.getSurveyId();
// Do something with the survey; send an email,
// call an external system etc.
....
}
}
Other event types will be added later, as suggestions from users are reviewed and implemented.
If your plugin needs a setup screen for the user to set various configuration values, it is possible to implement the two methods getSetupHTML() and processSetup(). Note that only Opinio users with all access rights (super users) have access to the Opinio setup screen. The getSetupHTML is called by Opinio when displaying the setup screen for the plugin. The plugin must then return the HTML code for a complete HTML form. Your code should look something like:
public String getSetupHTML() {
return "<FORM ACTION=\"plugin.do?action=process\" METHOD=POST>" +
"<input type=hidden name=pluginName value=MyPlugin>" +
... the HTML form elements ...
"</form";
}
The hidden field pluginName must be included. When the user submits the form, Opinio receives the values, and passes them along to the plugin for processing. The processSetup() method is called by Opinio, and may look like this:
public String processSetup(Map values) {
// get the values from the form
String[] sArray1 = (String[]) values.get("myElement1");
String[] sArray2 = (String[]) values.get("myElement2");
// do something with the setup values
...
return "The plugin configuration was saved successfully";
}
Remember, it is up to the plugin author to make the setup values persistent. Functionality for making this easier will be added in future versions. Look in the example plugin included with the distribution on how to make the configuration persistent.