Plugins - advanced/hu

Áttekintés

A LimeSurvey 2.05-től kezdve a LimeSurvey hivatalosan is támogatja a bővítményeket. Egyes beépülő modulokat a LimeSurvey csapata támogatni fog, és bekerülnek a magba. Néhányat mások is támogatnak a LimeSurvey csapatán kívül. A keresés megkönnyítése érdekében nézze meg az Elérhető harmadik féltől származó beépülő modulokat, és adja hozzá saját bővítményét!

A beépülő modulok lehetővé teszik a felhasználók számára, hogy testreszabják telepítésük funkcionalitását, miközben továbbra is élvezhetik a rendszeres szoftverfrissítések előnyeit.

Ez a dokumentáció azoknak a fejlesztőknek szól, akik saját vagy ügyfeleik számára bővítik a LimeSurveyt; ez a dokumentáció nem segít a végfelhasználóknak.

A beépülő moduloknak megvalósítaniuk kell a iPlugin felületet. Javasoljuk, hogy bővítse ki beépülő modulját a PluginBase osztályból.

A beépülő modulok egy event mechanizmus köré épülnek.

Beépülő modul beállításai

A bővítés révén élvezheti az általunk már megvalósított bővítmények által megkövetelt közös funkciók előnyeit. Az egyik ilyen funkció a getPluginSettings függvény megvalósítása. Ennek a függvénynek egy tömböt kell visszaadnia, amely leírja a felhasználó konfigurációs beállításait.

A példabővítmény csak 1 konfigurálható beállítást tesz közzé, az üzenetet, amely megjelenik.

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

'message' => array(
 'type' => 'string',
 'label' => 'Üzenet'
 )
);

A tömb minden beállításhoz kulcsként egy nevet tartalmaz. Az értékek a szükséges metaadatokat tartalmazó tömbök.

A támogatott típusok a következők:

• logó
• int (egész szám)
• string (alfanumerikus)
• szöveg
• html
• relevancia
• info
• jelszó
• dátum
• válasszon

A típuson kívül számos más billentyű is elérhető:

• label, meghatároz egy címkét
• alapértelmezett, meghatároz egy értéket, amely megmutatja, ha nincs megadva érték (csak a globális beállításoknál, nem a felmérési beállításoknál)
• aktuális, az aktuális értéket határozza meg.
• readOnly : a beállítások csak olvashatóként jelennek meg
• htmlOptions, a beviteli rész htmlOpciói (lásd Yii kézikönyv [[1]])
• pluginOptions, for néhány beállítás (html vagy válasszon) : állítsa be a widget opciót
• labelOptions : htmlA címke beállításai
• controlOptions : htmlA címke és a bemenet burkolójának beállításai

Az összes tényleges beállítást használó beépülő modul példáját itt találja: exampleSettings

Beépülő modul beállításainak olvasása és írása

A beépülő modul beállításai közvetlenül a beépülő modul kódjából olvashatók és írhatók.

Példa:

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

Alapértelmezett értéket kaphat, ha a beállítás nulla:

$mySetting = $this->get('mySetting', null, null, 10); // A 10 az alapértelmezett

Események

A beépülő modulok előfizetnek az eseményekre, és interakcióba léphetnek a LimeSurvey szolgáltatással, amikor az esemény elindul. Az aktuálisan elérhető események listáját tekintse meg a Plugin events oldalon.

API

A beépülő modulok csak a „nyilvános” API-n keresztül bővíthetik ki a LimeSurvey-t. Ez azt jelenti, hogy a forráskódban található osztályok közvetlen használata rossz gyakorlat. Bár nem kényszeríthetjük rá, hogy ne tegye meg, minden kisebb frissítésnél fennáll annak a kockázata, hogy elromlik a plugin.

Amennyire csak lehetséges, csak a itt leírt módszerekkel lépjen kapcsolatba a LimeSurvey-vel. Ugyanaz, mint a rendezvényeknél.

Az API-objektum $this->api keresztül érhető el, ha a PluginBase-ből bővíti, ellenkező esetben a beépülő modulok konstruktorának átadott PluginManager-példányból szerezheti be.

Kérésre új funkciókat lehet hozzáadni az API objektumhoz.

Űrlapkiterjesztés ^{(New in 6 )}

Bevezetés

Az űrlapkiterjesztési rendszer egy általánosabb módja az űrlapok kiterjesztésének a központi LimeSurveyben anélkül, hogy minden űrlaphoz új eseményt adna hozzá.

A következő összetevőkből áll:

• Egy globális modul FormExtensionService
• bemeneti osztályok könyvtára, amelyet a pluginek hozzáadhatnak a fenti modul inicializálásához
• Egy widget, valamint egyéni megjelenítők, amelyeket a LimeSurvey nézetfájlokban használnak

Minden űrlapot egy ''pozíciós karakterlánc azonosít, pl<form name><dot><tab name> . Példa: globalsettings.general vagy globalsettings.security .

A HTML nélküli osztályalapú rendszer mögött az a lényeg, hogy fel kell szabadítani a munka beépülő moduljait a HTML frissítésére, amikor az alapvető HTML megváltozik. Ennek ellenére a szerző használhatja a RawHtmlInput típust, ha szükséges.

Egy dolog, amit ebben a rendszerben nem tehet meg, az "új űrlaplapok" hozzáadása.

Példa

Ha egy beépülő modulból új bemenetet szeretne hozzáadni egy űrlaphoz, használja az alábbi kódot init() függvényből:

TEENDŐ: Mentse a plugin beállításaiba a globális helyett

// A fájl tetején
használja a LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Inside init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'saját bemenet', 
 'label' => 'Címke',
 'disabled' => true,
 'tooltip' => 'Moo mú mú',
 'help' => 'Néhány súgószöveg', 
 'mentés' => function($request, $connection) {
 $value = $request->getPost('saját bemenet');
 if ($value === 'valamilyen érvénytelen érték') {
 throw new SaveFailedException("Nem sikerült elmenteni a 'myinput' egyéni bevitelt");
 } else {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'load' => function () {
 return getGlobalSetting('myinput');
 }
 ])
);

Érvényesítés

A bemenet érvényesítése a save funkcióban történik (lásd a fenti példát). Ha a közzétett érték érvénytelen, dobjon egy SaveFailedException , és egy figyelmeztető gyorsüzenet jelenik meg a felhasználó számára.

Támogatott űrlapok

A következő űrlapok bővíthetők:

• globalsettings.general ^{(New in 6.0.0 )}

Ha egy másik alapűrlaphoz szeretne támogatást hozzáadni, a következő változtatást kell alkalmaznia egy lehívási kérelemben:

A nézetfájlban adja hozzá:

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

Lehet, hogy új megjelenítő osztályt kell létrehoznia DefaultBaseRenderer alapján, ha az űrlap HTML-kódja eltér a többi űrlaptól. Előfordulhat, hogy ki kell bővítenie az alapértelmezett renderelő osztályt a még fel nem vett beviteli típusokkal is.

A második változtatás, amelyet meg kell tennie, az űrlapot mentő vezérlőműveletben egy hívás hozzáadása az űrlapkiterjesztés szolgáltatási osztályához:

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

Ez az!

Lokalizáció ^{(New in 3 )}

A beépülő modulok saját területi fájlokat adhatnak hozzá. A használt fájlformátum a .mo, ugyanaz, mint az alapvető fordításoknál. A fájlokat ebben kell tárolni

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

ahol "<language> " egy kétbetűs szó, például "de" vagy "fr".

Az adott területi fájl használatához használja a gT beépülő modul függvényt:

$this->gT("A beépülő modul szövege, amit le kell fordítani");

Ha az adott karakterlánc nem található a beépülő modul-specifikus területi beállításfájlban, a függvény az alapterületi fájlokban fog keresni. Tehát biztonságos az olyan karakterláncok használata, mint a "Mégse":

$this->gT("Mégse"); // Akkor is le lesz fordítva, ha a "Mégse" nincs a bővítmény nyelvi fájljában

Ha nézeteket használ a beépülő modullal együtt, akkor használja

$plugin->gT("Fordítsd le");

bővítményspecifikus fordítás elvégzéséhez az Ön nézetében.

Példaként használhatja a limesurvey.pot fájlt, hogy hogyan nézhet ki egy pot fájl. Ez importálva van a fordítóeszközébe.

Eszközök

A po- és mo-fájlok szerkesztésére szolgáló nyílt forráskódú eszköz a [2].

Naplózás ^{(New in 3 )}

Ha naplózni szeretne valamit a bővítményéből, csak írjon

$this->log("Az Ön üzenete");

Az alapértelmezett naplózási szint a nyomkövetés, de megadhat egy másik naplózási szintet opcionális második argumentumként:

$this->log("Valami hiba történt!", CLogger::LEVEL_ERROR);

A naplófájl a mappában található

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

A beépülő modul neve automatikusan kategóriaként kerül felhasználásra. Egy szép módja annak, hogy csak a beépülő modul hibáit nézze meg, ha használja a grep-et (Linuxon):

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

További információ a naplózás konfigurálásáról a Yii 1-ben: Optional_settings#Logging_settings.

A bővítmény frissítései ^{(New in 4 )}

A LimeSurvey 4.0.0-s verziója óta létezik egy rendszer a beépülő modulok és egyéb bővítmények frissítéseinek kezelésére. A rendszer használatához a config.xml kiterjesztésű fájlnak tartalmaznia kell a frissítő konfigurációját.

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

(A fenti forráscímke a LimeStore REST API-ra mutat, amelyet a LimeStore-ban elérhető összes bővítményhez használunk.)

Frissítő címkeleírások

Tag	Leírás
stabil	"1", ha ez a forrás csak stabil verziószámokat ad meg; "0", ha a forrás instabil verziókat is biztosít, például 0.3.3-beta .
típus	Egyelőre csak a típusú rest támogatott. Könnyen hozzáadható új frissítőtípusok (verzióellenőrzők), például git, wget stb.
forrás	Az új verziók letöltéséhez szükséges URL.
manualUpdateUrl	URL, amelyre a felhasználó felkereshet a kiterjesztés legújabb verziójának frissítéséhez.
automaticUpdateUrl	TODO

Ha nem szeretne frissítőt biztosítani, akkor tegye a következő szöveget a konfigurációs XML fájlba:

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

Így közli a rendszerrel, hogy szándékosan letiltotta a frissítési rendszert, és nem felejtette el hozzáadni.

Az új „UpdateCheck” bővítmény – alapértelmezés szerint telepítve és aktiválva – ellenőrzi az új frissítéseket az „összes” telepített bővítményhez, amikor egy kiemelt rendszergazda bejelentkezik aszinkron módon, legfeljebb 24 óránként. Ha bármilyen új verziót talál, a rendszer értesítést küld.

Ha új biztonsági frissítést talál, az értesítés automatikusan megnyílik, és a „veszély” osztályba sorolható.

Manuálisan ellenőrizheti a frissítéseket a bővítménykezelő nézetben, és kattintson a "Frissítések ellenőrzése" gombra. Vegye figyelembe, hogy ez a gomb csak akkor látható, ha az UpdateCheck beépülő modul aktiválva van.

A motorháztető alatt

Ez a szakasz rövid áttekintést nyújt a bővítményfrissítő megvalósításáról.

A bővítményfrissítő az ExtensionInstaller könyvtár része. Az alábbiakban egy UML diagram látható a frissítési folyamathoz kapcsolódó osztályokhoz.

Programfolyamat, amikor a Yii elindul:

 Yii init
 VersionFetcherServiceLocator->init()
 Adja hozzá a REST verzió lekérőjét
 ExtensionUpdaterServiceLocator->init()
 Add PluginUpdater
 TODO: Adjon hozzá egy frissítőt minden bővítménytípushoz (téma, kérdéssablon, ...)

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.