Plugins - geavanceerd
From LimeSurvey Manual
Overzicht
Sinds versie 2.05 ondersteunt LimeSurvey plugins. Enkele plugins worden door het LimeSurvey-team feitelijk toegevoegd aan LimeSurvey. Andere plugins worden door anderen ondersteund. Je kunt ons vragen om hier een door jou gemaakte plugin te vermelden!
Met een plugin kun je de functionaliteit uitbreiden van LimeSurvey en toch gebruikt blijven maken van onze normale updates.
Deze documentatie is niet bedoeld voor eindgebruikers maar voor ontwerpers die een plugin willen gaan maken voor hun cliënten die LimeSurvey gebruiken.
Plugins moeten de iPlugin interface implementeren. We bevelen aan dat je als basis voor je plugin class de PluginBase class gebruikt.
Plugins maken gebruik van events.
Plugin-instellingen
Door extending gebruik je de voor plugins benodigde functionaliteit die al door ons is gemaakt. Een van de functies is de implementatie van de functie getPluginSettings. Deze functie moet als resultaat een array teruggeven met de configuratie-opties voor de gebruiker.
In het voorbeeld heeft de plugin maar één instelling: message, de te tonen tekst.
protected $settings = array(
'logo' => array(
'type' => 'logo',
'path' => 'assets/logo.png'
),
'message' => array(
'type' => 'string',
'label' => 'Message'
)
);
Het array bevat per instelling een naam als key. Elke waarde is een array met de benodigde metagegevens.
De ondersteunde types:
- logo
- string
- html
- choice
- relevance
- info
Naast het type zijn er ook andere keys beschikbaar:
- label, definieert het label (gebruik een Engelse tekst, het label wordt later wel vertaald).
- default, als er waarde wordt ingevuld de standaardwaarde.
- current, de huidige waarde.
- readOnly, is het een alleen-lezen instelling.
Een voorbeeld met alle huidige instellingen : exampleSettings
Lezen en schrijven
It's possible to read and write plugin settings directly from your plugin code.
Voorbeeld:
$mySetting = $this->get('mySetting');
$this->set('mySetting', $mySetting + 1);
You can get a default value if the setting happens to be null:
$mySetting = $this->get('mySetting', null, null, 10); // 10 is standaardwaarde
Events
Plugins subscribe to events and can interact with LimeSurvey when the event is fired. For a list of currently available events check Plugin events.
API
Plugins should only extend LimeSurvey via its "public" API. This means that directly using classes found in the source code is a bad practice. Though we can't force you not to, you risk having a broken plugin with every minor update we do.
As much as possible interact with LimeSurvey only via methods described here. Same as for events.
The API object is available via $this->api
when extending from PluginBase, otherwise you can get it from the PluginManager instance that is passed to your plugins' constructor.
New functions can be added to the API object upon request.
Lokalisatie (nog niet beschikbaar)
It's possible for plugins to add their own locale files. File format used is .mo, same as core translations. The files must be stored in
<plugin root folder>/locale/<language>/<language>.mo
where "<language>" is a two letter word like "de" or "fr".
To use the specific locale file, use the plugin function gT:
$this->gT("A plugin text that needs to be translated");
If the given string can't be found in the plugin specific locale file, the function will look in the core locale files. So it's safe to use strings like "Cancel":
$this->gT("Cancel"); // Will be translated even if "Cancel" is not in the plugin locale file
If you are using views together with your plugin, you should use
$plugin->gT("Translate me");
to do plugin specific translation in your view.
Logging (nog niet beschikbaar)
If you want to log something from your plugin, just write
$this->log("Your message");
The default logging level is trace, but you can give another log level as an optional second argument:
$this->log("Something went wrong!", CLogger::LEVEL_ERROR);
The log file can be found in folder
<limesurvey root folder>/tmp/runtime/plugin.log
Your plugin name is automatically used as category. A nice way to see only the errors from your plugin is using grep (on Linux):
$ tailf tmp/runtime/plugin.log | grep <your plugin name>
Speciale plugins
Beschikbare plugins
Handleiding
This step-by-step tutorial shows how to create a plugin that sends a post request on every survey response submission. The tutorial shows you how to create and save global and per-survey settings, how to register events and more.