Plugins - advanced/nl

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.

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 geen 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 [])
 * 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:

Je kunt een standaardwaarde krijgen als de instelling null is:

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  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
Een plugin kan eigen vertaalbestanden toevoegen. Het gebruikte bestandsformaat is mo, dat is het ook voor LimeSurvey zelf. De bestanden moeten staan in

/locale/ / .mo

" " staat voor de taalcode, dus voor Nederlands "nl".

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

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:

Als je views gebruikt in je plugin, dan wordt het

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

Logging
Als je iets wilt loggen in je plugin, schrijf dan

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

Het logbestand staat in de map

/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

Extensie-updates
Sinds LimeSurvey versie 4.0.0 is er een systeem om plug-ins en andere extensie-updates te doen. Als je dit systeem wilt gebruiken, moet je extensiebestand config.xml de updater-configuratie bevatten.

https://somedownloadlink.com/maybegithub

(De broncode hierboven verwijst naar de LimeStore REST API, die wordt gebruikt voor alle extensies die beschikbaar zijn in onze LimeStore.)

Als je geen updater wilt aanbieden, moet je de volgende tekst in het XML-configuratiebestand zetten:

Op deze manier geef je aan dat je het updatesysteem doelbewust hebt uitgeschakeld en niet bent vergeten om het toe te voegen.

De nieuwe plugin UpdateCheck, standaard geïnstalleerd en geactiveerd, controleert maximaal 1 keer per 24 uur asynchroon op nieuwe updates van alle geïnstalleerde extensies wanneer een superbeheerder zich aanmeldt. Als er nieuwe versies worden gevonden, wordt er een melding gepusht.



Als er een nieuwe beveiligingsupdate wordt gevonden, wordt de melding automatisch geopend en weergegeven in de class "danger".



Je kunt ook handmatig controleren op updates door naar de pluginmanager te gaan en op "Updates controleren" te klikken. Deze knop is alleen zichtbaar is als de plugin UpdateCheck actief is.



Onder de motorkap
Dit gedeelte biedt een kort overzicht van de implementatie van de extensie-updater.

De updater is onderdeel van de ExtensionInstaller-bibliotheek. Hieronder ziet u een UML-diagram met de classes die betrekking hebben op het updateproces.



Programmastroom wanneer Yii start:

Programmastroom tijdens het uitvoeren van de plugin UpdaterCheck:

De methode checkAll in de UpdateCheck-plugin is een voorbeeld van hoe alle extensies naar nieuwe versies kunnen worden verwerkt.

Nieuwe versie-fetchers toevoegen
Als je een nieuwe aangepaste fetcher wilt toevoegen, voer dan dit uit tijdens de Yii-initialisatie:

Natuurlijk heeft de class  de subclass.

Om een nieuwe fetcher te gebruiken, configureer dan de  tag in de updater-XML (in plaats van bijv.  ).

Nieuwe extensie-updaters toevoegen
Om een ​​nieuwe extensie-updater toe te voegen, voer dit uit bij de Yii-initialisatie:

Class  moet een subclass zijn van.

De top  tag in config.xml ( 'plugin', 'thema', ...) zal bepalen welke extensie-updater wordt gebruikt voor deze extensie. Het systeem is nog niet volledig aanpasbaar, omdat je ook een eigen ExtensionInstaller, menu-items, enz. moet toevoegen. Maar in theorie, en misschien in de toekomst, zou het mogelijk moeten zijn om op deze manier een nieuw type extensie toe te voegen.

Speciale plugins

 * Authentication plugin development
 * Export plugin development

Beschikbare plugins

 * Authentication plugins
 * Audit log
 * CintLink
 * Available third party 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.