Actions

Plugins - advanced/nl: Difference between revisions

From LimeSurvey Manual

Han (talk | contribs)
No edit summary
m Text replacement - "http://manual.limesurvey.org" to "https://manual.limesurvey.org"
 
(80 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<languages />
<languages />
<span id="Overview"></span>
==Overzicht==
==Overzicht==


Line 10: Line 11:
Plugins moeten de [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin] interface implementeren. We bevelen aan dat je als basis voor je plugin class de [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase] class gebruikt.  
Plugins moeten de [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin] interface implementeren. We bevelen aan dat je als basis voor je plugin class de [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase] class gebruikt.  


Plugins maken gebruik van [http://manual.limesurvey.org/Plugin_events events].
Plugins maken gebruik van [https://manual.limesurvey.org/Plugin_events events].


<span id="Plugin_settings"></span>
== Plugin-instellingen ==
== Plugin-instellingen ==


Line 18: Line 20:
In het voorbeeld heeft de plugin maar één instelling: '''message''', de te tonen tekst.
In het voorbeeld heeft de plugin maar één instelling: '''message''', de te tonen tekst.


<syntaxhighlight lang="php" enclose="div">
<syntaxhighlight lang="php">
protected $settings = array(
protected $settings = array(
    'logo' => array(
    'logo' => array(
Line 37: Line 39:


* logo
* logo
* string
* int (integer getal)
* string (alfanumeriek)
* text
* html
* html
* choice
* relevance
* relevance
* info
* info
* password
* date
* select


Naast het type zijn er ook andere keys beschikbaar:
Naast het type zijn er ook andere keys beschikbaar:


* label, definieert het label
* label, definieert het label
* default, als er waarde wordt ingevuld de standaardwaarde (alleen voor algemene instellingen, niet voor enquête-instellingen)
* default, als er geen waarde wordt ingevuld de standaardwaarde (alleen voor algemene instellingen, niet voor enquête-instellingen)
* current, de huidige waarde
* current, de huidige waarde
* readOnly, toon de instelling als alleen-lezen
* readOnly, toon de instelling als alleen-lezen
Line 54: Line 60:
* controlOptions : htmlOptions van de wrapper van label en invoer
* controlOptions : htmlOptions van de wrapper van label en invoer


Een voorbeeld met alle huidige [https://framagit.org/Shnoulle/exampleSettings instellingen].
Een voorbeeld met alle huidige [https://gitlab.com/SondagesPro/SampleAndDemo/exampleSettings instellingen].
   
   
=== Lezen en schrijven ===
=== Lezen en schrijven ===
Line 71: Line 77:
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
$mySetting = $this->get('mySetting', null, null, 10);  // 10 is standaardwaarde
$mySetting = $this->get('mySetting', null, null, 10);  // 10 is standaardwaarde
</syntaxhighlight>
<span id="Survey_specific_plugin_settings"></span>
=== Enquête specifieke plug-in instellingen ===
Er worden twee gebeurtenissen gebruikt om enquêtespecifieke plug-in-instellingen te maken:
* newSurveySettings
* beforeSurveySettings
Voorbeeld om een plug-in uit te schakelen voor een specifieke enquête:
<syntaxhighlight lang="php">
 
    public function init()
    {
        $this->subscribe('beforeSurveySettings');
        $this->subscribe('newSurveySettings');
        // Other events...
    }
    public function beforeSurveySettings()
    {
    $event = $this->event;
    $surveyId = intval($event->get('survey'));
        $event->set(
            "surveysettings.{$this->id}",
            [
                'name' => get_class($this),
                'settings' => [
                    'isActive' => [
                        'type' => 'boolean',
                        'label' => 'isActive',
                        'current' => $this->getIsActive($surveyId),
                        'help' => 'Activate plugin for this survey'
                    ],
                ]
            ]
        );
    }
    public function newSurveySettings()
    {
        $event = $this->event;
        foreach ($event->get('settings') as $name => $value)
        {
            $this->set($name, $value, 'Survey', $event->get('survey'), false);
        }
    }
    private function getIsActive(int $sid): bool
    {
        return (bool) $this->get('isActive', 'Survey', $sid, false);
    }
</syntaxhighlight>
</syntaxhighlight>


Line 87: Line 148:
Op verzoek kunnen er nieuwe functies aan de API worden toegevoegd.
Op verzoek kunnen er nieuwe functies aan de API worden toegevoegd.


<span id="Form_extension{{NewIn|v=6}}"></span>
== Formulierextensie{{NewIn|v=6}} ==
<span id="Introduction"></span>
==Introductie==
Het systeem 'form extension' is een meer algemene manier om formulieren in de kern van LimeSurvey uit te breiden zonder voor elk formulier een nieuwe gebeurtenis toe te voegen.
Het bestaat uit de volgende componenten:
* Een algemene module genaamd '''FormExtensionService'''
* Een bibliotheek van '''input classes''' die plug-ins kunnen toevoegen aan bovenstaande module-initialisatie
* Een '''widget''', samen met aangepaste renderers, die worden gebruikt in de LimeSurvey-weergavebestanden
Elk formulier wordt geïdentificeerd door een '''position string''', zoals<form name><dot><tab name> . Voorbeeld: <code>globalsettings.general</code> of <code>globalsettings.security</code> .
Het punt achter een class-based systeem zonder HTML is om de auteurs van plug-ins te bevrijden van het werk om de HTML bij te werken wanneer de kern-HTML verandert. Toch kan de auteur indien nodig het type <code>RawHtmlInput</code> gebruiken.
Een ding dat u in dit systeem niet kunt doen, is het toevoegen van ''nieuwe tabbladen aan een formulier''.
<span id="Example"></span>
=== Voorbeeld ===
Om nieuwe invoer toe te voegen aan een formulier uit een plug-in, gebruikt u de volgende code van uw <code>init()</code> -functie:
OPEN: Opslaan in plug-in-instellingen in plaats van globaal
<syntaxhighlight lang="php">
// Bovenaan bestand
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;
// Inside init()
Yii::app()->formExtensionService->add(
'globalsettings.general',
new TextInput([
'name' => 'myinput',
'label' => 'Label',
'disabled' => true,
'tooltip' => 'Moo moo moo',
'help' => 'Enige helptekst',
'save' => function($request, $connection) {
$value = $request->getPost('myinput');
if ($value === 'een ongeldige waarde') {
throw new SaveFailedException("Kon aangepaste invoer 'myinput'" niet opslaan);
} else {
SettingGlobal::setSetting('myinput', $value);
}
} ,
'load' => function () {
return getGlobalSetting('myinput');
}
])
);
</syntaxhighlight>
<span id="Validation"></span>
=== Validatie ===
Validatie van de invoer gebeurt in de functie <code>save</code> (zie voorbeeld hierboven). Als de geposte waarde ongeldig is, maak dan een <code>SaveFailedException</code> , en er wordt een waarschuwing aan de gebruiker getoond.
<span id="Supported_forms"></span>
=== Ondersteunde formulieren ===
De volgende formulieren kunnen worden uitgebreid:
* globalsettings.general{{NewIn/nl|v=6.0.0}}
Als u ondersteuning voor een ander kernformulier wilt toevoegen, moet u de volgende wijziging toepassen in een pull-request:
Voeg in het weergavebestand toe:
<syntaxhighlight lang="php">
<?php
use LimeSurvey\Libraries\FormExtension\FormExtensionWidget;
use LimeSurvey\Libraries\FormExtension\Inputs\DefaultBaseRenderer;
?>
... meer HTML
<?= FormExtensionWidget::render(
    App()-> formExtensionService->getAll('globalsettings.security'),
new DefaultBaseRenderer()
); ?>
</syntaxhighlight>
Mogelijk moet u een nieuwe class  renderer maken op basis van <code>DefaultBaseRenderer</code> , als de formulier-HTML anders is dan andere formulieren. Mogelijk moet u ook de standaard class  renderer extenden met invoertypen die nog niet zijn toegevoegd.
De tweede wijziging die u moet doen, is een aanroep toevoegen van de service class voor formulierextensie in de controlleractie die het formulier opslaat:
<syntaxhighlight lang="php">
$request = App()->request;
Yii::app()->formExtensionService->applySave('globalsettings', $request);
</syntaxhighlight>
Dat is het!
<span id="Localization_{{NewIn|v=3}}"></span>
== Lokalisatie  {{NewIn/nl|v=3}} ==
== Lokalisatie  {{NewIn/nl|v=3}} ==


Line 115: Line 272:
om de voor de plugin benodigde vertaling in je view te doen.
om de voor de plugin benodigde vertaling in je view te doen.


U kunt het bestand [https://github.com/LimeSurvey/LimeSurvey/blob/master/locale/_template/limesurvey.pot limesurvey.pot] gebruiken als voorbeeld voor hoe dit bestand. Dit wordt geïmporteerd in uw vertaaltool.
=== Tools ===
Een open-source tool om po- en mo-bestanden te bewerken is [https://poedit.net/ Poedit].
<span id="Logging_{{NewIn|v=3}}"></span>
== Logging {{NewIn/nl|v=3}} ==
== Logging {{NewIn/nl|v=3}} ==


Line 131: Line 295:
Het logbestand staat in de map
Het logbestand staat in de map


  <limesurvey root folder>/tmp/runtime/plugin.log
  <syntaxhighlight lang="bash>
<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:
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>
  $ tail -f tmp/runtime/plugin.log | grep <your plugin name>


Informatie over [[Optional_settings/nl#Logging instellingen|logging in Yii 1]].
<span id="Extension_updates_{{NewIn|v=4}}"></span>
== Extensie-updates {{NewIn/nl|v = 4}} ==
== Extensie-updates {{NewIn/nl|v = 4}} ==


Line 197: Line 365:
[[File:manuallycheckforupdates.png||Handmatig controleren op updates]]
[[File:manuallycheckforupdates.png||Handmatig controleren op updates]]


=== Under the hood ===
<span id="Under_the_hood"></span>
===Onder de motorkap===


This section provides a brief overview over the extension updater implementation.
Dit gedeelte biedt een kort overzicht van de implementatie van de extensie-updater.


The extension updater is part of the ExtensionInstaller library. Below is a UML diagram for the classes related to the updater process.
De updater is onderdeel van de ExtensionInstaller-bibliotheek. Hieronder ziet u een UML-diagram met de classes die betrekking hebben op het updateproces.


[[File:extensionupdateruml.png||Extension updater UML diagram]]
[[File:extensionupdateruml.png||UML-diagram van extensie-updater]]


Program flow when Yii starts:
Programmastroom wanneer Yii start:


<syntaxhighlight lang="txt">
<pre>
  Yii init
  Yii init
   VersionFetcherServiceLocator->init()
   VersionFetcherServiceLocator->init()
Line 213: Line 382:
   ExtensionUpdaterServiceLocator->init()
   ExtensionUpdaterServiceLocator->init()
     Add PluginUpdater
     Add PluginUpdater
     TODO: Add an updater for each extension type (theme, question template, ...)
     NOG DOEN: Updater toevoegen voor elk type extensie (thema, vraagsjabloon, ...)
</syntaxhighlight>
</pre>


Program flow when running the UpdaterCheck plugin:
Programmastroom tijdens het uitvoeren van de plugin UpdaterCheck:


<syntaxhighlight lang="txt">
<pre>
Get all updaters from ExtensionUpdaterServiceLocator
Download alle updaters van ExtensionUpdaterServiceLocator
Loop each updater
Loop elke updater
  For each updater, loop through version fetchers configured by <updater> XML
  Voor elke updater doorloop versie-fetchers geconfigureerd door <updater> XML
    For each version fetcher, contact remote source and get version information
      Neem voor elke fetcher contact op met de externe bron en ontvang versie-informatie
Compose all versions into a notification
Stel alle versies samen in een boodschap
</syntaxhighlight>
</pre>


The [https://github.com/LimeSurvey/LimeSurvey/blob/develop/application/core/plugins/UpdateCheck/UpdateCheck.php#L130 checkAll] method in the UpdateCheck plugin provides an example of how to query all extensions for new versions.
De methode [https://github.com/LimeSurvey/LimeSurvey/blob/develop/application/core/plugins/UpdateCheck/UpdateCheck.php#L130 checkAll] in de UpdateCheck-plugin is een voorbeeld van hoe alle extensies naar nieuwe versies kunnen worden verwerkt.


==== Adding new version fetchers ====
<span id="Adding_new_version_fetchers"></span>
====Nieuwe versie-fetchers toevoegen====


To add a new custom version fetcher, run this during Yii initialization:
Als je een nieuwe aangepaste fetcher wilt toevoegen, voer dan  dit uit tijdens de Yii-initialisatie:


<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
Line 242: Line 412:
</syntaxhighlight>
</syntaxhighlight>


Of course, the class <code>MyNewVersionFetcher</code> has to subclass <code>VersionFetcher</code>.
Natuurlijk heeft de class <code>MyNewVersionFetcher</code> de subclass <code>VersionFetcher</code>.


To use your new version fetcher, configure the <code>type</code> tag in the updater XML to use
Om een nieuwe fetcher te gebruiken, configureer dan de <code>type</code> tag in de updater-XML
<code>myNewVersionFetcherType</code> (instead of e.g. <code>rest</code>).
<code>myNewVersionFetcherType</code> (in plaats van bijv. <code>rest</code> ).


==== Adding new extension updaters ====
<span id="Adding_new_extension_updaters"></span>
==== Nieuwe extensie-updaters toevoegen ====


To add a new custom extension updater, run this during Yii initialization:
Om een ​​nieuwe extensie-updater toe te voegen, voer dit uit bij de Yii-initialisatie:


<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
Line 261: Line 432:
</syntaxhighlight>
</syntaxhighlight>


Class <code>MyNewExtensionUpdater</code> has to subclass <code>ExtensionUpdater</code>.
Class <code>MyNewExtensionUpdater</code> moet een subclass zijn van <code>ExtensionUpdater</code>.
 
De top <code>type</code> 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.
 
<span id="Extension_installer"></span>
== Extensie-installatieprogramma ==
 
De bibliotheek van het installatieprogramma voor extensies bestaat uit twee abstracte klassen:
 
* ExtensionInstaller
* FileFetcher
 
De ExtensionInstaller is gesubklasseerd voor elk extensietype, zoals PluginInstaller, QuestionThemeInstaller, enz.
 
De FileFetcher is gesubklasseerd voor elke verschillende manier om bestanden op te halen. Nu worden alleen geüploade zip-bestanden ondersteund, maar in de toekomst zou er ook een Github- of LimeStore-fetcher kunnen zijn.


The top <code>type</code> 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.
[[File: extensioninstalleruml.png]]


<span id="Special_plugins"></span>
== Speciale plugins ==
== Speciale plugins ==


Line 273: Line 459:
* [[Authentication plugins]]
* [[Authentication plugins]]
* [[Audit log]]
* [[Audit log]]
* [[AzureOAuthSMTP Plugin]]
* [[CintLink]]
* [[CintLink]]
* [[Available third party plugins]]
* [[Available third party plugins]]

Latest revision as of 09:17, 15 October 2024

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
  • int (integer getal)
  • string (alfanumeriek)
  • text
  • html
  • relevance
  • info
  • password
  • date
  • select

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 [[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

Enquête specifieke plug-in instellingen

Er worden twee gebeurtenissen gebruikt om enquêtespecifieke plug-in-instellingen te maken:

  • newSurveySettings
  • beforeSurveySettings

Voorbeeld om een plug-in uit te schakelen voor een specifieke enquête:

   
    public function init()
    {
        $this->subscribe('beforeSurveySettings');
        $this->subscribe('newSurveySettings');
        // Other events...
    }

    public function beforeSurveySettings()
    {
	    $event = $this->event;
	    $surveyId = intval($event->get('survey'));

        $event->set(
            "surveysettings.{$this->id}",
            [
                'name' => get_class($this),
                'settings' => [
                    'isActive' => [
                        'type' => 'boolean',
                        'label' => 'isActive',
                        'current' => $this->getIsActive($surveyId),
                        'help' => 'Activate plugin for this survey'
                    ],
                ]
            ]
        );
    }

    public function newSurveySettings()
    {
        $event = $this->event;
        foreach ($event->get('settings') as $name => $value)
        {
            $this->set($name, $value, 'Survey', $event->get('survey'), false);
        }
    }

    private function getIsActive(int $sid): bool
    {
        return (bool) $this->get('isActive', 'Survey', $sid, false);
    }

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.

<span id="Form_extension (New in 6 )">

Formulierextensie (New in 6 )

Introductie

Het systeem 'form extension' is een meer algemene manier om formulieren in de kern van LimeSurvey uit te breiden zonder voor elk formulier een nieuwe gebeurtenis toe te voegen.

Het bestaat uit de volgende componenten:

  • Een algemene module genaamd FormExtensionService
  • Een bibliotheek van input classes die plug-ins kunnen toevoegen aan bovenstaande module-initialisatie
  • Een widget, samen met aangepaste renderers, die worden gebruikt in de LimeSurvey-weergavebestanden

Elk formulier wordt geïdentificeerd door een position string, zoals<form name><dot><tab name> . Voorbeeld: globalsettings.general of globalsettings.security .

Het punt achter een class-based systeem zonder HTML is om de auteurs van plug-ins te bevrijden van het werk om de HTML bij te werken wanneer de kern-HTML verandert. Toch kan de auteur indien nodig het type RawHtmlInput gebruiken.

Een ding dat u in dit systeem niet kunt doen, is het toevoegen van nieuwe tabbladen aan een formulier.

Voorbeeld

Om nieuwe invoer toe te voegen aan een formulier uit een plug-in, gebruikt u de volgende code van uw init() -functie:

OPEN: Opslaan in plug-in-instellingen in plaats van globaal

// Bovenaan bestand
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Inside init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'myinput', 
 'label' => 'Label',
 'disabled' => true,
 'tooltip' => 'Moo moo moo',
 'help' => 'Enige helptekst', 
 'save' => function($request, $connection) {
 $value = $request->getPost('myinput');
 if ($value === 'een ongeldige waarde') {
 throw new SaveFailedException("Kon aangepaste invoer 'myinput'" niet opslaan);
 } else {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'load' => function () {
 return getGlobalSetting('myinput');
 }
 ])
);

Validatie

Validatie van de invoer gebeurt in de functie save (zie voorbeeld hierboven). Als de geposte waarde ongeldig is, maak dan een SaveFailedException , en er wordt een waarschuwing aan de gebruiker getoond.

Ondersteunde formulieren

De volgende formulieren kunnen worden uitgebreid:

  • globalsettings.general (Nieuw in 6.0.0)

Als u ondersteuning voor een ander kernformulier wilt toevoegen, moet u de volgende wijziging toepassen in een pull-request:

Voeg in het weergavebestand toe:

 <?php
use LimeSurvey\Libraries\FormExtension\FormExtensionWidget;
use LimeSurvey\Libraries\FormExtension\Inputs\DefaultBaseRenderer;
?> 
... meer HTML
<?= FormExtensionWidget::render(
    App()-> formExtensionService->getAll('globalsettings.security'),
 new DefaultBaseRenderer()
); ?>

Mogelijk moet u een nieuwe class renderer maken op basis van DefaultBaseRenderer , als de formulier-HTML anders is dan andere formulieren. Mogelijk moet u ook de standaard class renderer extenden met invoertypen die nog niet zijn toegevoegd.

De tweede wijziging die u moet doen, is een aanroep toevoegen van de service class voor formulierextensie in de controlleractie die het formulier opslaat:

$request = App()->request;
Yii::app()->formExtensionService->applySave('globalsettings', $request);

Dat is het!

<span id="Localization_ (New in 3 )">

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.

U kunt het bestand limesurvey.pot gebruiken als voorbeeld voor hoe dit bestand. Dit wordt geïmporteerd in uw vertaaltool.

Tools

Een open-source tool om po- en mo-bestanden te bewerken is Poedit.

<span id="Logging_ (New in 3 )">

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:

  $ tail -f tmp/runtime/plugin.log | grep <your plugin name>

Informatie over [[Optional_settings/nl#Logging instellingen|logging in Yii 1]].

<span id="Extension_updates_{{NewIn|v=4}}"></span>
== Extensie-updates {{NewIn/nl|v = 4}} ==

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.

<syntaxhighlight lang="xml">
<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>

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

Updater tagbeschrijvingen
Tag Beschrijving
stable "1" als deze bron je alleen stabiele versienummers geeft; "0" als de bron ook onstabiele versies zal leveren, zoals 0.3.3-beta.
type Voorlopig wordt alleen type rest ondersteund. Het is gemakkelijk om nieuwe typen toe te voegen (versiecontroles), zoals git, wget, enz.
source De URL om nieuwe versies op te halen.
manualUpdateUrl URL waar de gebruiker naar kan gaan om de nieuwste versie van de extensie bij te werken.
automaticUpdateUrl Nog uitwerken

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

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

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.

Beschikbare updates

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

Beschikbare beveiligingsupdates

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.

Handmatig controleren op updates

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.

UML-diagram van extensie-updater

Programmastroom wanneer Yii start:

 Yii init
   VersionFetcherServiceLocator->init()
     Add REST version fetcher
   ExtensionUpdaterServiceLocator->init()
     Add PluginUpdater
     NOG DOEN: Updater toevoegen voor elk type extensie (thema, vraagsjabloon, ...)

Programmastroom tijdens het uitvoeren van de plugin UpdaterCheck:

Download alle updaters van ExtensionUpdaterServiceLocator
Loop elke updater
  Voor elke updater doorloop versie-fetchers geconfigureerd door <updater> XML
      Neem voor elke fetcher contact op met de externe bron en ontvang versie-informatie
Stel alle versies samen in een boodschap

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:

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

Natuurlijk heeft de class MyNewVersionFetcher de subclass VersionFetcher.

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

Nieuwe extensie-updaters toevoegen

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

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

Class MyNewExtensionUpdater moet een subclass zijn van ExtensionUpdater.

De top type 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.

Extensie-installatieprogramma

De bibliotheek van het installatieprogramma voor extensies bestaat uit twee abstracte klassen:

  • ExtensionInstaller
  • FileFetcher

De ExtensionInstaller is gesubklasseerd voor elk extensietype, zoals PluginInstaller, QuestionThemeInstaller, enz.

De FileFetcher is gesubklasseerd voor elke verschillende manier om bestanden op te halen. Nu worden alleen geüploade zip-bestanden ondersteund, maar in de toekomst zou er ook een Github- of LimeStore-fetcher kunnen zijn.

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.