Bővítmények – haladó

This page is a translated version of the page Plugins and the translation is 100% complete.

Áttekintés

A LimeSurvey funkcionalitása bővítményekkel egészíthető ki. A LimeSurvey már eleve számos alapbővítményt tartalmaz. Nézze meg a harmadik féltől származó bővítmények listáját is, és a jövőben akár saját bővítményét is felveheti rá!

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 bővítmények egy eseménykezelő 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
default, meghatároz egy megjelenítendő értéket arra az esetre, ha nincs megadva érték (csak a globális beállításoknál, a kérdőív-beállításoknál nem)
current, a jelenlegi értéket határozza meg.
readOnly : a beállítást csak olvashatóként jeleníti meg
htmlOptions, a beviteli rész htmlOptions értéke (lásd a Yii kézikönyvét: [[1]])
pluginOptions, egyes beállításoknál (html vagy select) : a widget beállítása
labelOptions : a címke htmlOptions értéke
controlOptions : a címkét és a beviteli mezőt körülvevő elem htmlOptions értéke
localized : ha igaz, az érték nyelvenként tárolódik. A beviteli mező értéke name[language] formában érkezik, a current pedig nyelvkóddal indexelt tömb kell, hogy legyen.
language : a localized beállítással együtt használatos. Vagy egyetlen nyelvkód, vagy ^{(New in X.Y.Z )} nyelvkódok tömbje, amellyel nyelvenként egy beviteli mező jelenik meg (lásd: Nyelvfüggő bővítménybeállítások)

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

Kérdőívspecifikus bővítménybeállítások

A kérdőívspecifikus bővítménybeállítások létrehozásához két esemény szolgál:

newSurveySettings
beforeSurveySettings

Példa egy bővítmény letiltására egy adott kérdőívnél:

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

Nyelvfüggő bővítménybeállítások ^{(New in 7.4 )}

Ha ugyanahhoz a beállításhoz kérdőív-nyelvenként egy-egy beviteli mezőt szeretne megjeleníteni, állítsa a localized értékét igazra, a language paraméterben pedig adja meg a nyelvek listáját. A nyelv neve hozzáadódik az egyes beviteli mezők címkéjéhez.

    public function beforeSurveySettings()
    {
        $event = $this->event;
        $surveyId = intval($event->get('survey'));
        $survey = Survey::model()->findByPk($surveyId);

        $event->set(
            "surveysettings.{$this->id}",
            [
                'name' => get_class($this),
                'settings' => [
                    'errorText' => [
                        'type' => 'text',
                        'label' => $this->gT('Error text'),
                        'localized' => true,
                        'language' => $survey->getAllLanguages(),
                        // Nyelvkóddal indexelt tömb, pl. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

A beküldött érték nyelvkóddal indexelt tömb, ezért a fenti példában szereplő newSurveySettings függvény változtatás nélkül elmenti. Az aktuális nyelvhez tartozó szöveg kiolvasása:

$errorTexts = $this->get('errorText', 'Survey', $surveyId, []);
$errorText = $errorTexts[App()->getLanguage()] ?? '';

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 lehetséges, a LimeSurvey-jel csak az itt leírt metódusokon keresztül lépjen kapcsolatba. Ez az eseményekre is igaz.

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>

Bővítmény hiba miatti deaktiválásának naplózása ^{(New in 6.13.3 )}

A LimeSurvey 5-ös verziója óta egy bővítmény PHP-hiba esetén automatikusan deaktiválható.

A rendszer automatikusan e-mailt küld a LimeSurvey üzemeltetőjének. A naplózási rendszer segítségével riasztást is generálhat a többi szerverüzemeltetőnek.

Példa riasztási üzenet küldésére:

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

További információ a naplózás konfigurálásáról a Yii 1-ben: Optional_settings/hu#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ímkék leírása
Címke	Leírás
stable	„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`.
type	Egyelőre csak a `rest` típus támogatott. Könnyen hozzáadhatók új frissítőtípusok (verzióellenőrzők), például git, wget stb.
source	Az az URL, ahonnan az új verziók letölthetők.
manualUpdateUrl	Az az URL, ahol a felhasználó manuálisan frissítheti a kiterjesztést a legújabb verzióra.
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, ...)

Programfolyamat az UpdaterCheck beépülő modul futtatásakor:

 Szerezze be az összes frissítést az ExtensionUpdaterServiceLocator!N webhelyről! Hurok minden frissítőt
 Minden egyes frissítő esetében böngéssze át a által konfigurált verzióletöltőket<updater> XML
 Minden egyes verzióletöltő esetén lépjen kapcsolatba a távoli forrással, és szerezze be a verzióinformációkat
 Állítsa össze az összes verziót értesítésbe

Az UpdateCheck beépülő modul checkAll metódusa példát ad arra, hogyan lehet lekérdezni az összes bővítményt új verziókért .

Új verzióletöltő hozzáadása

Új egyéni verziólekérő hozzáadásához futtassa ezt a Yii inicializálása során:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
 'myNewVersionFetcherType',
 függvény (\SimpleXMLElement $updaterXml) {
 return new MyNewCher(
 $updaterXml);
 }
);

Természetesen a MyNewVersionFetcher osztálynak VersionFetcher alosztályba kell tartoznia.

Az új verzióletöltő használatához állítsa be a type a frissítő XML-ben az

myNewVersionFetcherType (pl. rest helyett).

Új bővítményfrissítők hozzáadása

Új egyéni bővítményfrissítő hozzáadásához futtassa ezt a Yii inicializálása során:

$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
 'myNewExtensionUpdater',
 function () {
 return MyNewExtensionUpdater::()Updaters ;
 }
);

MyNewExtensionUpdater osztálynak ExtensionUpdater alosztályba kell tartoznia.

A config.xml legfelső type címkéje ('plugin', 'theme', ...) szabályozza, hogy mely bővítményfrissítőket használják ehhez a bővítményhez. A rendszer még nem teljesen testreszabható, hiszen hozzá kell adni egy egyedi ExtensionInstallert, menüpontokat, stb. De elméletileg, és talán a jövőben is lehetséges lenne így egy új típusú bővítmény hozzáadása.

Kiterjesztés telepítője

A bővítménytelepítő könyvtár két absztrakt osztályból áll:

ExtensionInstaller
FileFetcher

Az ExtensionInstaller minden bővítménytípushoz alosztályozva van, például PluginInstaller, QuestionThemeInstaller stb.

A FileFetcher a fájlok lekérésének minden egyes módja szerint alosztályozva van. Jelenleg csak a feltöltött zip fájlok támogatottak, de a jövőben Github vagy LimeStore letöltő is megjelenhet.

Oktatóanyag

Ez a lépésenkénti oktatóanyag bemutatja, hogyan hozhat létre olyan bővítményt, amely minden kérdőívkitöltés beküldésekor post kérést küld. Az oktatóanyag azt is megmutatja, hogyan hozhat létre és menthet globális és kérdőívenkénti beállításokat, hogyan regisztrálhat eseményeket, és még sok mást.

Fő fejezetek

Bővítmények – haladó

From LimeSurvey Manual

Tartalomjegyzék

Áttekintés

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

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

Kérdőívspecifikus bővítménybeállítások

Nyelvfüggő bővítménybeállítások ^{(New in 7.4 )}

Események

API

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

Bevezetés

Példa

Érvényesítés

Támogatott űrlapok

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

Eszközök

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

Bővítmény hiba miatti deaktiválásának naplózása ^{(New in 6.13.3 )}

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

A motorháztető alatt

Új verzióletöltő hozzáadása

Új bővítményfrissítők hozzáadása

Kiterjesztés telepítője

Oktatóanyag

Fő fejezetek

Bővítmények – haladó

From LimeSurvey Manual

Áttekintés

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

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

Kérdőívspecifikus bővítménybeállítások

Nyelvfüggő bővítménybeállítások (New in 7.4 )

Események

API

Űrlapkiterjesztés (New in 6 )

Bevezetés

Példa

Érvényesítés

Támogatott űrlapok

Lokalizáció (New in 3 )

Eszközök

Naplózás (New in 3 )

Bővítmény hiba miatti deaktiválásának naplózása (New in 6.13.3 )

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

A motorháztető alatt

Új verzióletöltő hozzáadása

Új bővítményfrissítők hozzáadása

Kiterjesztés telepítője

Oktatóanyag

Nyelvfüggő bővítménybeállítások ^{(New in 7.4 )}

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

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

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

Bővítmény hiba miatti deaktiválásának naplózása ^{(New in 6.13.3 )}

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