Doplnky

Prehľad

LimeSurvey umožňuje rozšíriť funkčnosť pomocou doplnkov. LimeSurvey už obsahuje množstvo základných doplnkov. Pozrite si aj náš zoznam doplnkov tretích strán a možno v budúcnosti do neho pridáte aj vlastný doplnok!

Doplnky umožňujú používateľom prispôsobiť funkčnosť ich inštalácie a zároveň ťažiť z pravidelných aktualizácií softvéru.

Táto dokumentácia je určená vývojárom, ktorí rozširujú LimeSurvey pre vlastné potreby alebo pre svojich klientov; koncovým používateľom táto dokumentácia nepomôže.

Doplnky musia implementovať rozhranie iPlugin. Odporúčame, aby trieda vášho doplnku dedila z triedy PluginBase.

Doplnky sú vyvíjané na základe mechanizmu udalostí.

Nastavenia doplnku

Dedením získate spoločnú funkčnosť, ktorú doplnky potrebujú a ktorú sme už pre vás implementovali. Jednou z týchto funkcií je implementácia funkcie getPluginSettings. Táto funkcia musí vrátiť pole opisujúce konfiguračné možnosti pre používateľa.

Ukážkový doplnok poskytuje iba jedno konfigurovateľné nastavenie, a to správu, ktorú zobrazí.

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

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

Pole obsahuje názov každého nastavenia ako kľúč. Hodnoty sú polia obsahujúce požadované metadáta.

Podporované typy sú:

• logo
• int (celé číslo)
• string (alfanumerický)
• text
• html
• relevance
• info
• password
• date
• select

Okrem typu je k dispozícii niekoľko ďalších kľúčov:

• label, definuje popisok
• default, definuje hodnotu, ktorá sa zobrazí, ak nie je zadaná žiadna hodnota (iba pre globálne nastavenia, nie pre nastavenia prieskumu)
• current, definuje súčasnú hodnotu.
• readOnly : zobrazí nastavenia len na čítanie
• htmlOptions, htmlOptions vstupnej časti ( pozrite príručku Yii [[1]])
• pluginOptions, pre niektoré nastavenia (html alebo select) : nastaví možnosť widgetu
• labelOptions : htmlOptions popisku
• controlOptions : htmlOptions obalu popisku a vstupu
• localized : ak je true, hodnota sa ukladá pre každý jazyk osobitne. Vstup sa odosiela ako name[language] a current musí byť pole indexované kódom jazyka.
• language : používa sa spolu s localized. Buď jeden kód jazyka, alebo ^{(New in X.Y.Z )} pole kódov jazykov na zobrazenie jedného vstupu pre každý jazyk (pozrite Lokalizované nastavenia doplnku)

Príklad doplnku využívajúceho všetky aktuálne nastavenia nájdete na exampleSettings

Čítanie a zápis nastavení doplnku

Nastavenia doplnku je možné čítať a zapisovať priamo z kódu vášho doplnku.

Príklad:

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

Ak je nastavenie null, môžete získať predvolenú hodnotu:

$mySetting = $this->get('mySetting', null, null, 10);  // 10 is default

Nastavenia doplnku špecifické pre prieskum

Na vytvorenie nastavení doplnku špecifických pre prieskum sa používajú dve udalosti:

• newSurveySettings
• beforeSurveySettings

Príklad vypnutia doplnku pre konkrétny prieskum:

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

<span id="Localized_plugin_settings_ ^{(New in 7.4 )}">

Lokalizované nastavenia doplnku ^{(New in 7.4 )}

Ak chcete zobraziť jedno vstupné pole pre každý jazyk prieskumu pre to isté nastavenie, nastavte localized na true a v language odovzdajte zoznam jazykov. Názov jazyka sa pridá k popisku každého vstupného poľa.

    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(),
                        // Pole indexované kódom jazyka, napr. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Odoslaná hodnota je pole indexované kódom jazyka, takže funkcia newSurveySettings z predchádzajúceho príkladu ju uloží bez akejkoľvek zmeny. Takto načítate text pre aktuálny jazyk:

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

Udalosti

Doplnky sa prihlasujú na odber udalostí a po ich spustení môžu komunikovať s LimeSurvey. Zoznam aktuálne dostupných udalostí nájdete v časti Udalosti doplnkov.

API

Doplnky by mali rozširovať LimeSurvey iba prostredníctvom jeho „verejného“ API. To znamená, že priame používanie tried zo zdrojového kódu je zlý postup. Hoci vám v tom nemôžeme zabrániť, riskujete, že vám doplnok prestane fungovať pri každej menšej aktualizácii.

S LimeSurvey pracujte pokiaľ možno iba prostredníctvom metód popísaných tu. To isté platí aj pre udalosti.

Objekt API je dostupný cez $this->api, ak doplnok rozširuje triedu PluginBase. V opačnom prípade ho môžete získať z inštancie PluginManager, ktorá sa odovzdáva konštruktoru vášho doplnku.

Na požiadanie je možné do objektu API pridať nové funkcie.

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

Rozšírenie formulárov ^{(New in 6 )}

Úvod

Systém rozšírenia formulárov je všeobecnejší spôsob rozširovania formulárov v jadre LimeSurvey bez nutnosti pridávať novú udalosť pre každý formulár.

Skladá sa z týchto komponentov:

• Globálny modul s názvom FormExtensionService
• Knižnica vstupných tried, ktoré môžu doplnky pridať pri inicializácii uvedeného modulu
• Widget spolu s vlastnými rendermi, ktoré sa používajú v súboroch zobrazení LimeSurvey

Každý formulár je identifikovaný reťazcom pozície v tvare <form name><dot><tab name>. Príklad: globalsettings.general alebo globalsettings.security.

Zmyslom systému založeného na triedach bez HTML je zbaviť autorov doplnkov práce s aktualizáciou HTML pri zmene HTML v jadre. Autor však môže v prípade potreby použiť typ RawHtmlInput.

V tomto systéme nie je možné pridávať nové karty formulárov.

Príklad

Ak chcete z doplnku pridať nové vstupné pole do formulára, použite nasledujúci kód vo svojej funkcii init():

TODO: Ukladať do nastavení doplnku namiesto globálnych nastavení

// At top of file
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Inside init()
Yii::app()->formExtensionService->add(
    'globalsettings.general',
    new TextInput([
        'name' => 'myinput',
        'label' => 'Label',
        'disabled' => true,
        'tooltip' => 'Moo moo moo',
        'help' => 'Some help text',
        'save' => function($request, $connection) {
            $value = $request->getPost('myinput');
            if ($value === 'some invalid value') {
                throw new SaveFailedException("Could not save custom input 'myinput'");
            } else {
                SettingGlobal::setSetting('myinput', $value);
            }
        },
        'load' => function () {
            return getGlobalSetting('myinput');
        }
    ])
);

Validácia

Validácia vstupu sa vykonáva vo funkcii save (pozri príklad vyššie). Ak je odoslaná hodnota neplatná, vyvolajte výnimku SaveFailedException a používateľovi sa zobrazí varovné flash hlásenie.

Podporované formuláre

Možno rozšíriť tieto formuláre:

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

Ak chcete pridať podporu pre ďalší základný formulár, musíte v rámci pull requestu použiť nasledujúcu zmenu:

Do súboru zobrazenia (view) pridajte:

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

Možno budete musieť vytvoriť novú triedu rendereru založenú na DefaultBaseRenderer, ak sa HTML formulára líši od ostatných formulárov. Možno tiež bude potrebné rozšíriť predvolenú triedu rendereru o typy vstupov, ktoré ešte neboli pridané.

Druhou zmenou je pridať volanie triedy služby rozšírenia formulárov v akcii kontroléra, ktorá formulár ukladá:

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

To je všetko!

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

Lokalizácia ^{(New in 3 )}

Doplnky môžu pridávať vlastné jazykové súbory. Používa sa formát .mo, rovnako ako pri základných prekladoch. Súbory musia byť uložené v

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

kde "<language>" je dvojpísmenový kód, napríklad "de" alebo "fr".

Ak chcete použiť konkrétny jazykový súbor, použite funkciu doplnku gT:

$this->gT("A plugin text that needs to be translated");

Ak sa daný reťazec nenájde v jazykovom súbore doplnku, funkcia ho vyhľadá v základných jazykových súboroch. Preto je bezpečné používať reťazce ako "Cancel":

$this->gT("Cancel");  // Will be translated even if "Cancel" is not in the plugin locale file

Ak spolu s doplnkom používate zobrazenia (views), mali by ste použiť

$plugin->gT("Translate me");

na preklad špecifický pre doplnok vo vašom zobrazení.

Súbor limesurvey.pot môžete použiť ako príklad toho, ako môže vyzerať súbor pot. Tento súbor sa importuje do vášho prekladateľského nástroja.

Nástroje

Jedným z open-source nástrojov na úpravu súborov po a mo je Poedit.

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

Logovanie ^{(New in 3 )}

Ak chcete z doplnku niečo zaznamenať do logu, jednoducho napíšte

$this->log("Your message");

Predvolená úroveň logovania je trace, ale ako voliteľný druhý argument môžete zadať inú úroveň:

$this->log("Something went wrong!", CLogger::LEVEL_ERROR);

Súbor logu nájdete v priečinku

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

Názov vášho doplnku sa automaticky používa ako kategória. Pohodlným spôsobom, ako zobraziť iba chyby z vášho doplnku, je použiť grep (v systéme Linux):

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

<span id="Logging_plugin_deactivation_due_to_error_ ^{(New in 6.13.3 )}">

Logovanie deaktivácie doplnku z dôvodu chyby ^{(New in 6.13.3 )}

Od verzie 5 LimeSurvey: doplnok sa môže automaticky deaktivovať v prípade chyby PHP.

Správcovi LimeSurvey bol automaticky odoslaný e-mail. Systém logovania môžete použiť na vytvorenie upozornenia pre ostatných správcov servera.

Napríklad: odoslanie upozornenia

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

Viac informácií o konfigurácii logovania v Yii 1: Nastavenia logovania.

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

Aktualizácie rozšírení ^{(New in 4 )}

Od verzie LimeSurvey 4.0.0 existuje systém na správu aktualizácií doplnkov a iných rozšírení. Ak chcete tento systém používať, súbor config.xml vášho rozšírenia musí obsahovať konfiguráciu aktualizátora.

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

(Značka source vyššie odkazuje na LimeStore REST API, ktoré sa použije pre všetky rozšírenia dostupné v našom LimeStore.)

Popis značiek aktualizátora

Značka	Popis
stable	"1", ak tento zdroj poskytuje iba čísla stabilných verzií; "0", ak zdroj poskytuje aj nestabilné verzie, napríklad 0.3.3-beta.
type	Zatiaľ je podporovaný iba typ rest. Pridať nové typy aktualizátorov (kontrolórov verzií), ako git, wget a pod., je jednoduché.
source	Adresa URL, z ktorej sa načítavajú nové verzie.
manualUpdateUrl	Adresa URL, na ktorú môže používateľ prejsť a aktualizovať rozšírenie na najnovšiu verziu.
automaticUpdateUrl	TODO

Ak nechcete poskytovať aktualizátor, vložte do konfiguračného XML súboru nasledujúci text:

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

Takto systému oznámite, že ste systém aktualizácií zámerne vypli a nezabudli ste ho len pridať.

Nový doplnok UpdateCheck – predvolene nainštalovaný a aktivovaný – kontroluje nové aktualizácie pre všetky nainštalované rozšírenia, keď sa prihlási superadministrátor, a to asynchrónne, najviac raz za 24 hodín. Ak sa nájdu nové verzie, zobrazí sa upozornenie.

Ak sa nájde nová bezpečnostná aktualizácia, upozornenie sa otvorí automaticky a zobrazí sa v štýle triedy "danger".

Aktualizácie môžete skontrolovať manuálne tak, že prejdete do zobrazenia správcu doplnkov a kliknete na "Check updates". Upozorňujeme, že toto tlačidlo je viditeľné iba vtedy, ak je aktivovaný doplnok UpdateCheck.

Ako to funguje

Táto časť poskytuje stručný prehľad implementácie aktualizátora rozšírení.

Aktualizátor rozšírení je súčasťou knižnice ExtensionInstaller. Nižšie je UML diagram tried súvisiacich s procesom aktualizácie.

Priebeh programu pri spustení Yii:

 Yii init
   VersionFetcherServiceLocator->init()
     Add REST version fetcher
   ExtensionUpdaterServiceLocator->init()
     Add PluginUpdater
     TODO: Add an updater for each extension type (theme, question template, ...)

Priebeh programu pri spustení doplnku UpdaterCheck:

 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

Metóda checkAll v doplnku UpdateCheck poskytuje príklad, ako sa opýtať všetkých rozšírení na nové verzie.

Pridanie nových nástrojov na zisťovanie verzií

Ak chcete pridať nový vlastný nástroj na zisťovanie verzií, spustite počas inicializácie Yii nasledujúci kód:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
  'myNewVersionFetcherType',
  function (\SimpleXMLElement $updaterXml) {
    return new MyNewVersionFetcher($updaterXml);
  }
);

Trieda MyNewVersionFetcher samozrejme musí byť podtriedou VersionFetcher.

Ak chcete použiť nový nástroj na zisťovanie verzií, nastavte značku type v XML aktualizátora tak, aby používala myNewVersionFetcherType (namiesto napr. rest).

Pridanie nových aktualizátorov rozšírení

Ak chcete pridať nový vlastný aktualizátor rozšírení, spustite počas inicializácie Yii nasledujúci kód:

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

Trieda MyNewExtensionUpdater musí byť podtriedou ExtensionUpdater.

Hlavná značka type v config.xml ('plugin', 'theme', ...) určuje, ktorý aktualizátor rozšírení sa pre dané rozšírenie použije. Systém zatiaľ nie je úplne prispôsobiteľný, pretože musíte pridať aj vlastný ExtensionInstaller, položky ponuky atď. Teoreticky a možno v budúcnosti by však malo byť možné týmto spôsobom pridať nový typ rozšírenia.

Inštalátor rozšírení

Knižnica inštalátora rozšírení pozostáva z dvoch abstraktných tried:

• ExtensionInstaller
• FileFetcher

ExtensionInstaller má podtriedu pre každý typ rozšírenia, napríklad PluginInstaller, QuestionThemeInstaller atď.

FileFetcher má podtriedu pre každý spôsob získavania súborov. V súčasnosti sú podporované iba nahrané súbory zip, ale v budúcnosti by mohol pribudnúť aj nástroj pre Github alebo LimeStore.

Návod

Tento návod krok za krokom ukazuje, ako vytvoriť doplnok, ktorý pri každom odoslaní odpovede na prieskum odošle požiadavku POST. Návod vám ukáže, ako vytvoriť a uložiť globálne nastavenia aj nastavenia pre jednotlivé prieskumy, ako registrovať udalosti a ďalšie.