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

Survey specific plugin settings

Two events are used to create survey specific plugin settings:

• newSurveySettings
• beforeSurveySettings

Example to disable a plugin for a specific survey:

   
    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);
    }

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.

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

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!

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

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.

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

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

Logging plugin deactivation due to error ^{(New in 6.13.3 )}

Since version 5 of Limesurvey: a plugin can be automatically deactivated in the event of a PHP error.

An email was sent automatically to LimeSurvey administrator. You can use the log system to generate an alert to the other server administrators.

For example: to send an alert message

                // Plugin error happen, plugin was disable : send email using CLogRoute
                'pluginError' => array(
                    'class' => 'CEmailLogRoute', // https://www.yiiframework.com/doc/api/1.1/CEmailLogRoute
                    'categories' => 'application.model.plugin.setLoadError', // A plugin was disable
                    'subject' => '[ERROR] Plugin deactivated',
                    'emails' => ['webmaster@example.org'],
                    'sentFrom' => 'noreply@example.org',
                    'enabled' => 1, // enabled here
                )

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

<span id="Extension_updates_ ^{(New in 4 )}">

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.

Fluxul programului când pornește Yii:

 Yii init
 VersionFetcherServiceLocator->init()
 Adăugați un element de preluare a versiunii REST
 ExtensionUpdaterServiceLocator->init()
 Adăugați PluginUpdater
 TODO: Adăugați un update pentru fiecare tip de extensie (temă, șablon de întrebare, ...)

Fluxul programului când rulați pluginul UpdaterCheck:

 Obțineți toate actualizările de la ExtensionUpdaterServiceLocator
 Buclă fiecare actualizare
 Pentru fiecare program de actualizare, parcurgeți versiunile de preluare a versiunilor configurate de<updater> XML
 Pentru fiecare preluare de versiuni, contactați sursa de la distanță și obțineți informații despre versiune
 Compune toate versiunile într-o notificare

Metoda checkAll din pluginul UpdateCheck oferă un exemplu de interogare a tuturor extensiilor pentru versiuni noi.

Adăugarea unor noi versiuni de preluare

Pentru a adăuga o nouă versiune personalizată de preluare, rulați aceasta în timpul inițializării Yii:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
 'myNewVersionFetcherType',
 funcţie (\SimpleXMLElement $updaterXml) {
 returnează nou MyNewVersionFetcher( $updaterXml);
 }
);

Desigur, clasa MyNewVersionFetcher trebuie să fie subclasa VersionFetcher .

Pentru a utiliza noua versiune de preluare, configurați eticheta type în XML-ul de actualizare pentru a utiliza

myNewVersionFetcherType (în loc de ex. rest ).

Adăugarea de noi actualizări de extensii

Pentru a adăuga un nou program de actualizare a extensiilor personalizate, rulați acest lucru în timpul inițializării Yii:

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

Clasa MyNewExtensionUpdater trebuie să fie subclasa ExtensionUpdater .

Eticheta type superior din config.xml („plugin”, „temă”, ...) va controla ce program de actualizare a extensiilor este utilizat pentru această extensie. Sistemul nu este încă complet personalizabil, deoarece trebuie să adăugați și un ExtensionInstaller personalizat, elemente de meniu etc. Dar, în teorie, și poate în viitor, ar trebui să fie posibil să adăugați un nou tip de extensie în acest fel.

Instalator extensie

Biblioteca de instalare a extensiilor constă din două clase abstracte:

• ExtensionInstaller
• FileFetcher

ExtensionInstaller este subclasat pentru fiecare tip de extensie, cum ar fi PluginInstaller, QuestionThemeInstaller etc.

FileFetcher este subclasat pentru fiecare modalitate diferită de a prelua fișiere. În prezent, sunt acceptate doar fișierele zip încărcate, dar în viitor, ar putea exista și un program de preluare Github sau LimeStore.

Pluginuri speciale

• Dezvoltare plugin de autentificare
• Dezvoltare plugin pentru export

Pluginuri disponibile

• Plugin-uri de autentificare
• Jurnal de audit
• CintLink
• Pluginuri terțe disponibile

Tutorial

Acest tutorial pas cu pas arată cum să creați un plugin care trimite o solicitare de postare la fiecare răspuns la sondaj supunere. Tutorialul vă arată cum să creați și să salvați setări globale și per sondaj, cum să înregistrați evenimente și multe altele.