Pluginuri - avansate

Other languages:

Prezentare generală

Începând cu LimeSurvey 2.05, LimeSurvey va accepta oficial plugin-uri. Unele plugin-uri vor fi susținute de echipa LimeSurvey și vor intra în core. Unii vor fi sprijiniți de alții din afara echipei LimeSurvey. Pentru a le găsi, consultați Pluginurile terțe disponibile și adăugați-i propriul plugin!

Pluginurile permit utilizatorilor să personalizeze funcționalitatea instalării lor, putând, în același timp, să beneficieze de actualizări regulate de software.

Această documentație este destinată dezvoltatorilor care extind LimeSurvey pentru uz propriu sau pentru clienții lor; utilizatorii finali nu vor fi ajutați de această documentație.

Pluginurile trebuie să implementeze interfața iPlugin. Vă recomandăm să vă extindeți clasa de plugin din clasa PluginBase.

Pluginurile sunt dezvoltate în jurul unui mecanism event.

Setări plugin

Prin extindere, beneficiați de funcționalitatea comună cerută de pluginurile pe care le-am implementat deja pentru dvs. Una dintre aceste funcții este implementarea funcției getPluginSettings. Această funcție trebuie să returneze o matrice care descrie opțiunile de configurare pentru utilizator.

Exemplul de plugin expune doar 1 setare configurabilă, mesajul pe care îl va afișa.

protected $settings = array(
 'logo' => array(
 'type' => 'logo',
 'path' => 'assets/logo.png'
 ) ,

'message' => array(
 'type' => 'șir',
 'label' => 'Mesaj'
 )
);

Matricea conține un nume pentru fiecare setare ca cheie. Valorile sunt matrice care conțin metadatele necesare.

Tipurile acceptate sunt:

logo
int (număr întreg)
șir (alfanumeric)
text
html
relevanță
info
parolă
dată
selectați

Pe lângă tip, sunt disponibile o serie de alte chei:

etichetă, definește o etichetă
implicită, definește o valoare care să arate dacă nu este specificată nicio valoare (doar pentru setările globale, nu pentru setările sondajului)
curent, definește valoarea curentă.
readOnly : setările sunt afișate ca doar în citire
htmlOptions, htmlOptions ale părții de intrare (vezi manualul Yii [[1]])
pluginOptions, pentru unele setări (html sau select) : setați opțiunea widget
labelOptions : htmlOpțiuni ale etichetei
controlOptions : htmlOpțiuni ale pachetului de etichete și de intrare

Puteți găsi un exemplu de plugin folosind toate setările reale la exampleSettings

Citiți și scrieți setările pluginului

Este posibil să citiți și să scrieți setările pluginului direct din codul dvs. de plugin.

Exemplu:

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

Puteți obține o valoare implicită dacă setarea se întâmplă să fie nulă:

$mySetting = $this->get('mySetting', null, null, 10); // 10 este implicit

Evenimente

Pluginurile se abonează la evenimente și pot interacționa cu LimeSurvey atunci când evenimentul este declanșat. Pentru o listă a evenimentelor disponibile în prezent, verificați Evenimente plugin.

API

Pluginurile ar trebui să extindă LimeSurvey numai prin intermediul API-ului său „public”. Aceasta înseamnă că utilizarea directă a claselor găsite în codul sursă este o practică proastă. Deși nu vă putem forța să nu o faceți, riști să ai un plugin rupt cu fiecare actualizare minoră pe care o facem.

Pe cât posibil, interacționați cu LimeSurvey numai prin metodele descrise aici. La fel ca pentru evenimente.

Obiectul API este disponibil prin $this->api atunci când se extinde din PluginBase, altfel îl puteți obține de la instanța PluginManager care este transmisă constructorului pluginurilor dumneavoastră.

La cerere, pot fi adăugate noi funcții la obiectul API.

Extensie formular^{(New in 6 )}

Introducere

Sistemul de extensie a formularelor este o modalitate mai generală de a extinde formularele din LimeSurvey de bază fără a adăuga un nou eveniment pentru fiecare formular.

Se compune din următoarele componente:

Un modul global numit FormExtensionService
O bibliotecă de clase de intrare pe care pluginurile le pot adăuga la inițializarea modulului de mai sus
Un widget, împreună cu randare personalizate, care sunt utilizate în fișierele de vizualizare LimeSurvey

Fiecare formular este identificat printr-un „șir de poziție”, cum ar fi<form name><dot><tab name> . Exemplu: globalsettings.general sau globalsettings.security .

Ideea din spatele unui sistem bazat pe clasă fără HTML este de a elibera autorii pluginurilor lucrării pentru a actualiza HTML-ul atunci când HTML-ul de bază se schimbă. Totuși, autorul poate folosi tipul RawHtmlInput dacă este necesar.

Un lucru pe care nu îl puteți face în acest sistem este să adăugați „file noi de formulare”.

Exemplu

Pentru a adăuga o nouă intrare la un formular dintr-un plugin, utilizați următorul cod din funcția init() :

TODO: Salvați în setările pluginului în loc de global

// În partea de sus a fișierului
utilizați LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
utilizați LimeSurvey\Libraries\FormExtension\SaveFailedException;

// În interiorul init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'myinput', 
 'label' => 'Etichetă',
 'disabled' => adevărat,
 'tooltip' => 'Moo moo moo',
 'help' => 'Un text de ajutor', 
 „salvare” => funcție($cerere, $conexiune) {
 $valoare = $cerere->getPost('inputul meu');
 dacă ($valoare === 'o valoare nevalidă') {
 throw new SaveFailedException("Nu s-a putut salva intrarea personalizată 'myinput'");
 } altfel {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'încărcare' => funcție () {
 return getGlobalSetting('myinput');
 }
 ])
);

Validare

Validarea intrării se face în funcția save (vezi exemplul de mai sus). Dacă valoarea postată este nevalidă, aruncați o SaveFailedException și utilizatorului va fi afișat un mesaj flash de avertizare.

Forme acceptate

Următoarele forme pot fi extinse:

globalsettings.general^{(New in 6.0.0 )}

Dacă doriți să adăugați suport pentru un alt formular de bază, trebuie să aplicați următoarea modificare într-o cerere de extragere:

În fișierul de vizualizare, adăugați:

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

Este posibil să trebuiască să creați o nouă clasă de redare bazată pe DefaultBaseRenderer , dacă formularul HTML este diferit de alte forme. De asemenea, ar putea fi necesar să extindeți clasa de redare implicită cu tipuri de intrare care nu sunt încă adăugate.

A doua modificare pe care trebuie să o faceți este să adăugați un apel la clasa de serviciu de extensie de formular în acțiunea controlerului care salvează formularul:

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

Asta este!

Localizare ^{(New in 3 )}

Este posibil ca pluginurile să adauge propriile fișiere locale. Formatul de fișier utilizat este .mo, la fel ca și traducerile de bază. Fișierele trebuie să fie stocate în

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

Unde "<language> „ este un cuvânt de două litere precum „de” sau „fr”.

Pentru a utiliza fișierul local specific, utilizați funcția plugin gT:

$this->gT(„Un text plugin care trebuie tradus”);

Dacă șirul dat nu poate fi găsit în fișierul local specific pluginului, funcția va căuta în fișierele locale de bază. Deci, este sigur să folosiți șiruri precum „Anulare”:

$this->gT(„Anulează”); // Va fi tradus chiar dacă „Anulare” nu se află în fișierul local al pluginului

If you are using views together with your plugin, you should use

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

to do plugin specific translation in your view.

You can use the limesurvey.pot file as an example of how a pot file can look like. This is imported into your translation tool.

Tools

One open-source tool to edit po- and mo-files is Poedit.

Logging ^{(New in 3 )}

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):

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

More info about configuring logging in Yii 1: Optional_settings#Logging_settings.

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.

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

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.

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.

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.

Extension installer

The extension installer library consists of two abstract classes:

ExtensionInstaller
FileFetcher

The ExtensionInstaller is subclassed for each extension type, like PluginInstaller, QuestionThemeInstaller, etc.

The FileFetcher is subclassed for each different way to fetch files. Currently, only uploaded zip files are supported, but in the future, there could be a Github or LimeStore fetcher too.

Special plugins

Available plugins

Tutorial

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.

Pluginuri - avansate

From LimeSurvey Manual

Contents

Prezentare generală

Setări plugin

Citiți și scrieți setările pluginului

Evenimente

API

Extensie formular^{(New in 6 )}

Introducere

Exemplu

Validare

Forme acceptate

Localizare ^{(New in 3 )}

Tools

Logging ^{(New in 3 )}

Extension updates ^{(New in 4 )}

Under the hood

Adding new version fetchers

Adding new extension updaters

Extension installer

Special plugins

Available plugins

Tutorial

Pluginuri - avansate

From LimeSurvey Manual

Prezentare generală

Setări plugin

Citiți și scrieți setările pluginului

Evenimente

API

Extensie formular (New in 6 )

Introducere

Exemplu

Validare

Forme acceptate

Localizare (New in 3 )

Tools

Logging (New in 3 )

Extension updates (New in 4 )

Under the hood

Adding new version fetchers

Adding new extension updaters

Extension installer

Special plugins

Available plugins

Tutorial

Extensie formular^{(New in 6 )}

Localizare ^{(New in 3 )}

Logging ^{(New in 3 )}

Extension updates ^{(New in 4 )}