Zásuvné moduly

Přehled

LimeSurvey umožňuje rozšiřovat funkce pomocí zásuvných modulů. LimeSurvey již obsahuje velké množství základních zásuvných modulů. Podívejte se také na náš seznam zásuvných modulů třetích stran a třeba do něj v budoucnu přidejte i svůj vlastní zásuvný modul!

Zásuvné moduly umožňují uživatelům přizpůsobit funkce své instalace a přitom stále využívat pravidelné aktualizace softwaru.

Tato dokumentace je určena pro vývojáře, kteří rozšiřují LimeSurvey pro vlastní potřebu nebo pro své klienty; koncovým uživatelům tato dokumentace nepomůže.

Zásuvné moduly musí implementovat rozhraní iPlugin. Doporučujeme odvodit třídu svého zásuvného modulu od třídy PluginBase.

Zásuvné moduly jsou vyvíjeny na základě mechanismu událostí.

Nastavení zásuvného modulu

Díky rozšíření třídy získáte společné funkce, které zásuvné moduly potřebují a které jsme pro vás již implementovali. Jednou z těchto funkcí je implementace funkce getPluginSettings. Tato funkce musí vrátit pole popisující možnosti konfigurace pro uživatele.

Ukázkový zásuvný modul zpřístupňuje pouze jedno nastavení, a to zprávu, kterou zobrazí.

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

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

Pole obsahuje název každého nastavení jako klíč. Hodnoty jsou pole obsahující požadovaná metadata.

Podporované typy jsou:

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

Kromě typu je k dispozici řada dalších klíčů:

• label, definuje popisek
• default, definuje hodnotu, která se zobrazí, pokud není zadána žádná hodnota (pouze pro globální nastavení, nikoli pro nastavení průzkumu)
• current, definuje aktuální hodnotu.
• readOnly : zobrazí nastavení pouze pro čtení
• htmlOptions, htmlOptions vstupní části (viz příručka Yii [[1]])
• pluginOptions, u některých nastavení (html nebo select) : nastaví možnosti widgetu
• labelOptions : htmlOptions popisku
• controlOptions : htmlOptions obalu popisku a vstupního pole
• localized : pokud je true, hodnota se ukládá pro každý jazyk zvlášť. Vstup se odesílá jako name[language] a current musí být pole indexované kódem jazyka.
• language : používá se spolu s localized. Buď jeden kód jazyka, nebo ^{(New in X.Y.Z )} pole kódů jazyků pro zobrazení jednoho vstupu pro každý jazyk (viz Lokalizovaná nastavení zásuvného modulu)

Příklad zásuvného modulu využívajícího všechna aktuální nastavení najdete na exampleSettings

Čtení a zápis nastavení zásuvného modulu

Nastavení zásuvného modulu můžete číst a zapisovat přímo z kódu svého zásuvného modulu.

Příklad:

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

Pokud je nastavení null, můžete získat výchozí hodnotu:

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

Nastavení zásuvného modulu specifická pro průzkum

K vytvoření nastavení zásuvného modulu specifických pro průzkum se používají dvě události:

• newSurveySettings
• beforeSurveySettings

Příklad vypnutí zásuvného modulu pro konkrétní průzkum:

    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á nastavení zásuvného modulu ^{(New in 7.4 )}

Chcete-li zobrazit jedno vstupní pole pro každý jazyk průzkumu u stejného nastavení, nastavte localized na true a v language předejte seznam jazyků. Název jazyka se přidá k popisku každého vstupního pole.

    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ódem jazyka, např. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Odeslaná hodnota je pole indexované kódem jazyka, takže funkce newSurveySettings z předchozího příkladu ji uloží beze změny. Text pro aktuální jazyk načtete takto:

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

Události

Zásuvné moduly se přihlašují k odběru událostí a mohou komunikovat s LimeSurvey, když je událost spuštěna. Seznam aktuálně dostupných událostí najdete na stránce Události zásuvných modulů.

API

Zásuvné moduly by měly rozšiřovat LimeSurvey pouze prostřednictvím jeho „veřejného“ API. Přímé používání tříd ze zdrojového kódu je špatný postup. I když vám v tom nemůžeme zabránit, riskujete, že se váš zásuvný modul pokazí s každou drobnou aktualizací.

Pokud možno komunikujte s LimeSurvey pouze pomocí metod popsaných zde. Totéž platí pro události.

Objekt API je dostupný přes $this->api, pokud třídu odvozujete z PluginBase. Jinak jej můžete získat z instance PluginManager, která je předána konstruktoru vašeho zásuvného modulu.

Na požádání lze do objektu API přidat nové funkce.

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

Rozšíření formulářů ^{(New in 6 )}

Úvod

Systém rozšíření formulářů je obecnější způsob, jak rozšiřovat formuláře v jádru LimeSurvey, aniž by bylo nutné pro každý formulář přidávat novou událost.

Skládá se z následujících součástí:

• Globální modul nazvaný FormExtensionService
• Knihovna vstupních tříd, které mohou zásuvné moduly přidat při inicializaci výše uvedeného modulu
• Widget spolu s vlastními rendery, které se používají v souborech zobrazení LimeSurvey

Každý formulář je identifikován řetězcem pozice ve tvaru <form name><dot><tab name>. Příklad: globalsettings.general nebo globalsettings.security.

Smyslem systému založeného na třídách bez HTML je ušetřit autory zásuvných modulů práce s aktualizací HTML, když se změní HTML v jádru. Autor však může v případě potřeby použít typ RawHtmlInput.

Jediné, co v tomto systému nelze udělat, je přidat nové karty formuláře.

Příklad

Chcete-li ze zásuvného modulu přidat do formuláře nové vstupní pole, použijte následující kód ve své funkci init():

TODO: Save in plugin settings instead of global

// 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');
        }
    ])
);

Ověření

Ověření vstupu se provádí ve funkci save (viz příklad výše). Pokud je odeslaná hodnota neplatná, vyvolejte výjimku SaveFailedException a uživateli se zobrazí varovná flash zpráva.

Podporované formuláře

Rozšířit lze následující formuláře:

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

Pokud chcete přidat podporu pro další základní formulář, musíte v rámci pull requestu provést následující změnu:

Do souboru zobrazení (view) přidejte:

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

Pokud se HTML formuláře liší od ostatních formulářů, možná budete muset vytvořit novou třídu rendereru založenou na DefaultBaseRenderer. Případně můžete také rozšířit výchozí třídu rendereru o typy vstupů, které zatím nebyly přidány.

Druhou změnou je přidání volání třídy služby pro rozšíření formulářů v akci kontroleru, která formulář ukládá:

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

To je vše!

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

Lokalizace ^{(New in 3 )}

Zásuvné moduly mohou přidávat vlastní soubory lokalizace. Používá se formát .mo, stejný jako u základních překladů. Soubory musí být uloženy v

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

kde „<language>“ je dvoupísmenný kód, například „de“ nebo „fr“.

Chcete-li použít konkrétní soubor lokalizace, použijte funkci zásuvného modulu gT:

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

Pokud se zadaný řetězec nenajde v souboru lokalizace zásuvného modulu, funkce jej vyhledá v základních souborech lokalizace. Bezpečně tedy můžete používat řetězce jako „Cancel“ (Storno):

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

Pokud spolu se zásuvným modulem používáte zobrazení (views), měli byste použít

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

pro překlad specifický pro zásuvný modul ve vašem zobrazení.

Soubor limesurvey.pot můžete použít jako příklad toho, jak může soubor pot vypadat. Tento soubor se importuje do vašeho překladatelského nástroje.

Nástroje

Jedním z open-source nástrojů pro úpravu souborů po a mo je Poedit.

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

Logování ^{(New in 3 )}

Pokud chcete ze svého zásuvného modulu něco zalogovat, jednoduše napište

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

Výchozí úroveň logování je trace, ale jako volitelný druhý argument můžete zadat jinou úroveň:

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

Soubor logu najdete ve složce

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

Název vašeho zásuvného modulu se automaticky používá jako kategorie. Pěkný způsob, jak zobrazit pouze chyby vašeho zásuvného modulu, je použít grep (v Linuxu):

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

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

Logování deaktivace zásuvného modulu kvůli chybě ^{(New in 6.13.3 )}

Od verze 5 LimeSurvey může být zásuvný modul v případě chyby PHP automaticky deaktivován.

Administrátorovi LimeSurvey byl automaticky odeslán e-mail. Pomocí systému logování můžete vytvořit upozornění pro další administrátory serveru.

Například odeslání upozornění:

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

Další informace o konfiguraci logování v Yii 1: Optional_settings#Logging_settings.

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

Aktualizace rozšíření ^{(New in 4 )}

Od LimeSurvey verze 4.0.0 existuje systém pro správu aktualizací zásuvných modulů a dalších rozšíření. Chcete-li tento systém používat, musí soubor config.xml vašeho rozšíření obsahovat konfiguraci aktualizací.

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

(Výše uvedená značka source odkazuje na REST API služby LimeStore, které se používá pro všechna rozšíření dostupná v LimeStore.)

Popis značek updateru

Značka	Popis
stable	"1", pokud zdroj poskytuje pouze stabilní čísla verzí; "0", pokud zdroj poskytuje také nestabilní verze, například 0.3.3-beta.
type	Zatím je podporován pouze typ rest. Přidání nových typů updaterů (kontrol verzí), například git, wget atd., je snadné.
source	URL, ze které se načítají nové verze.
manualUpdateUrl	URL, na kterou může uživatel přejít a aktualizovat rozšíření na nejnovější verzi.
automaticUpdateUrl	TODO

Pokud nechcete poskytovat updater, vložte do konfiguračního souboru XML následující text:

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

Tímto systému sdělíte, že jste systém aktualizací záměrně vypnuli a že jste jej nezapomněli přidat.

Nový zásuvný modul UpdateCheck - který je ve výchozím nastavení nainstalován a aktivován - při přihlášení superadministrátora asynchronně kontroluje nové aktualizace pro všechna nainstalovaná rozšíření, nejvýše jednou za 24 hodin. Pokud jsou nalezeny nové verze, zobrazí se oznámení.

Pokud je nalezena nová bezpečnostní aktualizace, oznámení se otevře automaticky a bude zobrazeno ve stylu třídy "danger".

Aktualizace můžete zkontrolovat ručně tak, že přejdete do zobrazení správce zásuvných modulů a kliknete na "Check updates". Upozorňujeme, že toto tlačítko je viditelné pouze tehdy, je-li aktivován zásuvný modul UpdateCheck.

Pod pokličkou

Tato část poskytuje stručný přehled implementace updateru rozšíření.

Updater rozšíření je součástí knihovny ExtensionInstaller. Níže je diagram UML tříd souvisejících s procesem aktualizace.

Průběh programu při spuštění Yii:

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

Průběh programu při spuštění zásuvného modulu 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

Metoda checkAll v zásuvném modulu UpdateCheck poskytuje příklad, jak zjistit nové verze všech rozšíření.

Přidání nových nástrojů pro načítání verzí

Chcete-li přidat nový vlastní nástroj pro načítání verzí, spusťte při inicializaci Yii následující kód:

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

Třída MyNewVersionFetcher samozřejmě musí být potomkem třídy VersionFetcher.

Chcete-li použít svůj nový nástroj pro načítání verzí, nastavte značku type v XML updateru tak, aby používala myNewVersionFetcherType (místo např. rest).

Přidání nových updaterů rozšíření

Chcete-li přidat nový vlastní updater rozšíření, spusťte při inicializaci Yii následující kód:

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

Třída MyNewExtensionUpdater musí být potomkem třídy ExtensionUpdater.

Nejvyšší značka type v config.xml ('plugin', 'theme', ...) určuje, který updater rozšíření se pro dané rozšíření použije. Systém zatím není plně přizpůsobitelný, protože je třeba přidat také vlastní ExtensionInstaller, položky menu atd. Teoreticky, a možná v budoucnu, by však mělo být tímto způsobem možné přidat nový typ rozšíření.

Instalátor rozšíření

Knihovna instalátoru rozšíření se skládá ze dvou abstraktních tříd:

• ExtensionInstaller
• FileFetcher

Třída ExtensionInstaller má pro každý typ rozšíření vlastního potomka, například PluginInstaller, QuestionThemeInstaller atd.

Třída FileFetcher má vlastního potomka pro každý způsob získávání souborů. V současnosti jsou podporovány pouze nahrané soubory zip, ale v budoucnu by mohl přibýt také nástroj pro načítání z GitHubu nebo LimeStore.

Tutoriál

Tento podrobný tutoriál ukazuje, jak vytvořit zásuvný modul, který při každém odeslání odpovědi na průzkum odešle požadavek POST. Tutoriál vám ukáže, jak vytvořit a uložit globální nastavení i nastavení pro jednotlivé průzkumy, jak registrovat události a další.