Plugins - advanced/ro

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

Dacă utilizați vizualizări împreună cu pluginul dvs., ar trebui să utilizați

$plugin->gT(„Traduceți-mă”);

pentru a face traducere specifică pentru plugin în viziunea dvs.

Puteți utiliza fișierul limesurvey.pot ca exemplu despre cum poate arăta un fișier pot. Acesta este importat în instrumentul dvs. de traducere.

Instrumente

Un instrument open-source pentru editarea fișierelor po și mo este Poedit.

Înregistrare ^{(New in 3 )}

Dacă doriți să conectați ceva din pluginul dvs., scrieți

$this->log(„Mesajul tău”);

Nivelul implicit de înregistrare este urmă, dar puteți da un alt nivel de jurnal ca al doilea argument opțional:

$this->log(„Ceva a mers prost!”, CLogger::LEVEL_ERROR);

Fișierul jurnal poate fi găsit în folder

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

Numele dvs. de plugin este folosit automat ca categorie. Un mod frumos de a vedea numai erorile de la plugin-ul tău este folosirea grep (pe Linux):

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

Mai multe informații despre configurarea logării în Yii 1: Optional_settings#Logging_settings.

Actualizări de extensie ^{(New in 4 )}

De la versiunea LimeSurvey 4.0.0, există un sistem care să se ocupe de actualizări de plugin și alte extensii. Pentru a utiliza acest sistem, fișierul dvs. de extensie config.xml trebuie să includă configurația de actualizare.

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

(Eticheta sursă de mai sus indică API-ul REST LimeStore, care va fi folosit pentru toate extensiile disponibile în LimeStore.)

Descrierile etichetelor de actualizare

Eticheta	Descriere
stabil	„1” dacă această sursă vă oferă doar numere de versiune stabile; „0” dacă sursa va furniza și versiuni instabile, cum ar fi 0.3.3-beta .
tip	Deocamdată, este acceptat doar tipul rest . Este ușor să adăugați noi tipuri de actualizare (verificatoare de versiuni), cum ar fi git, wget etc.
sursa	Adresa URL pentru a prelua versiunile noi de la.
manualUpdateUrl	URL la care utilizatorul poate accesa pentru a actualiza cea mai recentă versiune a extensiei.
automatUpdateUrl	TODO

Dacă nu doriți să furnizați un program de actualizare, ar trebui să puneți următorul text în fișierul XML de configurare:

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

În acest fel, îi spuneți sistemului că ați dezactivat în mod intenționat sistemul de actualizare și că nu ați uitat să îl adăugați.

Noul plugin UpdateCheck - instalat și activat implicit - verifică dacă există noi actualizări pentru toate extensiile instalate atunci când un super-administrator se conectează, asincron, maximum o dată la fiecare 24 de ore. Dacă se găsesc versiuni noi, este trimisă o notificare.

Dacă se găsește o nouă actualizare de securitate, notificarea se va deschide automat și va fi stilată în clasa „pericol”.

Puteți verifica manual actualizările accesând vizualizarea managerului de pluginuri și faceți clic pe „Verificați actualizările”. Rețineți că acest buton este vizibil numai dacă pluginul UpdateCheck este activat.

Sub capotă

Această secțiune oferă o scurtă prezentare generală asupra implementării programului de actualizare a extensiilor.

Actualizatorul extensiei face parte din biblioteca ExtensionInstaller. Mai jos este o diagramă UML pentru clasele legate de procesul de actualizare.

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

• Authentication plugin development
• Export plugin development

Available plugins

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