Plugins - advanced/ro: Difference between revisions
From LimeSurvey Manual
Maren.fritz (talk | contribs) (Created page with "== Înregistrare {{NewIn|v=3}} ==") |
Maren.fritz (talk | contribs) (Created page with "<syntaxhighlight lang="php"> $this->log(„Mesajul tău”); </syntaxhighlight>") |
||
Line 219: | Line 219: | ||
<syntaxhighlight lang="php"> | <syntaxhighlight lang="php"> | ||
$this->log( | $this->log(„Mesajul tău”); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Nivelul implicit de înregistrare este urmă, dar puteți da un alt nivel de jurnal ca al doilea argument opțional: | |||
<syntaxhighlight lang="php"> | <syntaxhighlight lang="php"> |
Revision as of 11:55, 9 November 2023
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("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.)
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.