Actions

Plugins - geavanceerd

From LimeSurvey Manual

This page is a translated version of the page Plugins - advanced and the translation is 62% complete.

Other languages:
Deutsch • ‎English • ‎français • ‎日本語 • ‎Nederlands

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
  • default, als er waarde wordt ingevuld de standaardwaarde (alleen voor algemene instellingen, niet voor enquête-instellingen)
  • current, de huidige waarde
  • readOnly, toon de instelling als alleen-lezen
  • htmlOptions, de htmlOptions van het invoergedeelte ( lees Yii manual [[1]])
  • pluginOptions, voor enkele instellingen (html of select) : instelling widget-optie
  • labelOptions : htmlOptions van het label
  • controlOptions : htmlOptions van de wrapper van label en invoer

Een voorbeeld met alle huidige instellingen.

Lezen en schrijven

Je kunt in de code van de plugin direct de instellingen lezen en schrijven.

Voorbeeld:

$mySetting = $this->get('mySetting');
$this->set('mySetting', $mySetting + 1);

Je kunt een standaardwaarde krijgen als de instelling null is:

$mySetting = $this->get('mySetting', null, null, 10);  // 10 is standaardwaarde

Events

Een plugin reageert op gebeurtenissen (events) die optreden als de plugin zich daar eerst voor aangemeld (subscribe) heeft. Er is een lijst met de huidige events.

API

Plugins moeten alleen via de eigen LimeSurvey-API extenden. Je moet dus niet rechtstreeks de classes in de source-code aanroepen. Je voorkomt hiermee dat je bij een kleine wijziging aan onze kant zit met een niet meer werkende plugin.

Gebruik zoveel mogelijk deze methodes. Hetzelfde voor de events.

Het API-object is benaderbaar via $this->api bij het extenden van de PluginBase, anders krijg je het via de PluginManager-instantie door de plugin constructor.

Op verzoek kunnen er nieuwe functies aan de API worden toegevoegd.

Lokalisatie (Nieuw in 3 )

Een plugin kan eigen vertaalbestanden toevoegen. Het gebruikte bestandsformaat is mo, dat is het ook voor LimeSurvey zelf. De bestanden moeten staan in

<plugin root folder>/locale/<language>/<language>.mo

"<language>" staat voor de taalcode, dus voor Nederlands "nl".

Je kunt je vertaalbestand gebruiken met de plugin-functie gT:

$this->gT("A plugin text that needs to be translated");

Als de te vertalen tekst niet in je invoerbestand staat, zoekt de functie in de eigen LimeSurvey vertaalbestanden. Je kunt dus teksten als "Cancel" meestal wel vinden:

$this->gT("Cancel");  // Wordt ook vertaald als "Cancel" niet in het vertaalbestand van de plugin zit.

Als je views gebruikt in je plugin, dan wordt het

$plugin->gT("Translate me");

om de voor de plugin benodigde vertaling in je view te doen.

Logging (Nieuw in 3 )

Als je iets wilt loggen in je plugin, schrijf dan

$this->log("Your message");

Het standaardniveau van loggen is trace, maar je kunt een ander niveau opgeven:

$this->log("Something went wrong!", CLogger::LEVEL_ERROR);

Het logbestand staat in de map

<limesurvey root folder>/tmp/runtime/plugin.log

De naam van de plugin wordt als category gebruikt. Je kunt op Linux met grep dan eenvoudig alleen de logging van je eigen plugin zien:

$ tailf tmp/runtime/plugin.log | grep <pluginnaam>

Extension updates (New in 4 )

Since LimeSurvey version 4.0.0, there's a system in place to deal with plugin and other extension updates. To use this system, your extension config.xml file needs to include updater configuration.

<updaters>
    <updater>
        <stable>1</stable>
        <type>rest</type>
        <source>https://comfortupdate.limesurvey.org/index.php?r=limestorerest</source>
        <manualUpdateUrl>https://somedownloadlink.com/maybegithub</manualUpdateUrl>
    </updater>
</updaters>

(The source tag above points to the LimeStore REST API, which will be used for all extensions available in our LimeStore.)

Updater tag descriptions
Tag Description
stable "1" if this source only gives you stable version numbers; "0" if the source will also provide unstable versions, like 0.3.3-beta.
type For now, only type rest is supported. It's easy to add new updater types (version checkers), like git, wget, etc.
source The URL to fetch new versions from.
manualUpdateUrl URL which the user can go to to update the latest version of the extension.
automaticUpdateUrl TODO

If you don't want to supply an updater, you should put the following text in your config XML file:

<updaters disabled="disabled">
</updaters>

This way, you tell the system that you purposefully disabled the update system, and didn't just forget to add it.

The new plugin UpdateCheck - installed and activated by default - checks for new updates for all installed extensions when a super admin logs in, asynchronously, max one time every 24 hours. If any new versions are found, a notification is pushed.

Available updates

If a new security update is found, the notification will open automatically and be styled in "danger" class.

Available security updates

You can manually check for updates by going to the plugin manager view and click on "Check updates". Note that this button is only visible if the UpdateCheck plugin is activated.

Manually check for updates

Under the hood

This section provides a brief overview over the extension updater implementation.

The extension updater is part of the ExtensionInstaller library. Below is a UML diagram for the classes related to the updater process.

Extension updater UML diagram

Program flow when Yii starts:

 Yii init
   VersionFetcherServiceLocator->init()
     Add REST version fetcher
   ExtensionUpdaterServiceLocator->init()
     Add PluginUpdater
     TODO: Add an updater for each extension type (theme, question template, ...)

Program flow when running the UpdaterCheck plugin:

 Get all updaters from ExtensionUpdaterServiceLocator
 Loop each updater
   For each updater, loop through version fetchers configured by <updater> XML
     For each version fetcher, contact remote source and get version information
 Compose all versions into a notification

The checkAll method in the UpdateCheck plugin provides an example of how to query all extensions for new versions.

Adding new version fetchers

To add a new custom version fetcher, run this during Yii initialization:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
  'myNewVersionFetcherType',
  function (\SimpleXMLElement $updaterXml) {
    return new MyNewVersionFetcher($updaterXml);
  }
);

Of course, the class MyNewVersionFetcher has to subclass VersionFetcher.

To use your new version fetcher, configure the type tag in the updater XML to use myNewVersionFetcherType (instead of e.g. rest).

Adding new extension updaters

To add a new custom extension updater, run this during Yii initialization:

$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
  'myNewExtensionUpdater',
  function () {
    return MyNewExtensionUpdater::createUpdaters();
  }
);

Class MyNewExtensionUpdater has to subclass ExtensionUpdater.

The top type tag in config.xml ('plugin', 'theme', ...) will control which extension updater are used for this extension. The system is not fully customizable yet, since you also need to add a custom ExtensionInstaller, menu items, etc. But in theory, and maybe in the future, it should be possible to add a new type of extension this way.

Speciale plugins

Beschikbare plugins

Handleiding

In dit voorbeeld tonen we hoe je een plugin maakt die een post request doet bij het afronden van het invullen van de enquête. Je ziet onder meer hoe je globale en enquête-instellingen aanmaakt en bewaard en hoe je events registreert.