Lisäosat

Yleiskatsaus

LimeSurveyn toimintoja voi laajentaa lisäosilla. LimeSurveyn mukana toimitetaan jo runsaasti ydinlisäosia. Tutustu myös kolmannen osapuolen lisäosien listaan, ja lisää ehkä tulevaisuudessa oma lisäosasi siihen!

Lisäosien avulla käyttäjät voivat mukauttaa asennuksensa toimintoja ja hyötyä silti säännöllisistä ohjelmistopäivityksistä.

Tämä dokumentaatio on tarkoitettu kehittäjille, jotka laajentavat LimeSurveyta omaan käyttöönsä tai asiakkaidensa tarpeisiin. Loppukäyttäjät eivät hyödy tästä dokumentaatiosta.

Lisäosien on toteutettava iPlugin-rajapinta. Suosittelemme periyttämään lisäosaluokan PluginBase-luokasta.

Lisäosat kehitetään tapahtumamekanismin ympärille.

Lisäosan asetukset

Periyttämällä saat käyttöösi lisäosien tarvitsemat yhteiset toiminnot, jotka olemme jo toteuttaneet puolestasi. Yksi näistä toiminnoista on getPluginSettings-funktion toteutus. Tämän funktion on palautettava taulukko, joka kuvaa käyttäjälle näytettävät asetukset.

Esimerkkilisäosassa on vain yksi muokattava asetus, eli näytettävä viesti.

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

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

Taulukossa jokaisen asetuksen nimi on avain. Arvot ovat taulukoita, jotka sisältävät tarvittavat metatiedot.

Tuetut tyypit ovat:

• logo
• int (kokonaisluku)
• string (aakkosnumeerinen)
• text
• html
• relevance
• info
• password
• date
• select

Tyypin lisäksi käytettävissä on useita muita avaimia:

• label, määrittää otsikon
• default, määrittää näytettävän arvon, jos arvoa ei ole annettu (vain yleisille asetuksille, ei kyselyn asetuksille)
• current, määrittää nykyisen arvon.
• readOnly : näyttää asetukset vain luku -tilassa
• htmlOptions, syöttökentän htmlOptions-asetukset (katso Yii-opas [[1]])
• pluginOptions, joillekin asetuksille (html tai select) : määrittää widgetin asetuksen
• labelOptions : otsikon htmlOptions-asetukset
• controlOptions : otsikon ja syöttökentän kääreen htmlOptions-asetukset
• localized : jos arvo on tosi, arvo tallennetaan kielikohtaisesti. Syöte lähetetään muodossa name[language] ja current-arvon on oltava taulukko, jonka indeksinä on kielikoodi.
• language : käytetään yhdessä localized-avaimen kanssa. Joko yksittäinen kielikoodi tai ^{(New in X.Y.Z )} kielikoodien taulukko, jolloin jokaiselle kielelle näytetään oma syöttökenttä (katso Kielikohtaiset lisäosan asetukset)

Lisäosaesimerkin, jossa käytetään kaikkia nykyisiä asetuksia, löydät osoitteesta exampleSettings

Lisäosan asetusten lukeminen ja kirjoittaminen

Lisäosan asetuksia voi lukea ja kirjoittaa suoraan lisäosan koodista.

Esimerkki:

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

Voit saada oletusarvon, jos asetuksen arvo on null:

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

Kyselykohtaiset lisäosan asetukset

Kyselykohtaisten lisäosan asetusten luomiseen käytetään kahta tapahtumaa:

• newSurveySettings
• beforeSurveySettings

Esimerkki lisäosan poistamisesta käytöstä tietyssä kyselyssä:

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

Lokalisoidut lisäosan asetukset ^{(New in 7.4 )}

Jos haluat näyttää yhden syöttökentän jokaista kyselykieltä kohden samalle asetukselle, aseta localized arvoon true ja anna kielten lista parametrissa language. Kentän nimiöön lisätään kielen nimi.

    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(),
                        // Kielikoodilla indeksoitu taulukko, esim. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Lähetetty arvo on kielikoodilla indeksoitu taulukko, joten yllä olevan esimerkin newSurveySettings-funktio tallentaa sen sellaisenaan. Voit lukea nykyisen kielen tekstin näin:

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

Tapahtumat

Lisäosat tilaavat tapahtumia ja voivat olla vuorovaikutuksessa LimeSurveyn kanssa, kun tapahtuma laukeaa. Luettelo tällä hetkellä käytettävissä olevista tapahtumista löytyy sivulta Lisäosan tapahtumat.

API

Lisäosien tulisi laajentaa LimeSurveytä vain sen "julkisen" API:n kautta. Tämä tarkoittaa, että lähdekoodista löytyvien luokkien suora käyttö on huono käytäntö. Emme voi estää sitä, mutta riskinä on, että lisäosasi lakkaa toimimasta jokaisen pienenkin päivityksen myötä.

Käytä LimeSurveytä mahdollisimman paljon vain täällä kuvattujen metodien kautta. Sama koskee tapahtumia.

API-olio on käytettävissä muodossa $this->api, kun laajennat PluginBase-luokkaa. Muuten sen saa PluginManager-instanssista, joka välitetään lisäosasi konstruktorille.

API-olioon voidaan lisätä uusia funktioita pyynnöstä.

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

Lomakelaajennus ^{(New in 6 )}

Johdanto

Lomakelaajennusjärjestelmä on yleisempi tapa laajentaa LimeSurveyn ytimen lomakkeita lisäämättä uutta tapahtumaa jokaista lomaketta varten.

Se koostuu seuraavista osista:

• Globaali moduuli nimeltä FormExtensionService
• Syöttöluokkien kirjasto, jonka lisäosat voivat lisätä yllä mainitun moduulin alustukseen
• Widget ja mukautetut renderöijät, joita käytetään LimeSurveyn näkymätiedostoissa

Jokainen lomake tunnistetaan sijaintimerkkijonolla, joka on muotoa <form name><dot><tab name>. Esimerkki: globalsettings.general tai globalsettings.security.

Luokkapohjaisen, HTML:stä vapaan järjestelmän tarkoituksena on vapauttaa lisäosien tekijät päivittämästä HTML-koodia, kun ytimen HTML muuttuu. Tekijä voi silti tarvittaessa käyttää RawHtmlInput-tyyppiä.

Yksi asia, jota tässä järjestelmässä ei voi tehdä, on uusien lomakevälilehtien lisääminen.

Esimerkki

Jos haluat lisätä lisäosasta uuden syöttökentän lomakkeeseen, käytä seuraavaa koodia init()-funktiossasi:

TODO: Tallenna lisäosan asetuksiin globaalien sijaan

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

Validointi

Syötteen validointi tehdään save-funktiossa (katso yllä oleva esimerkki). Jos lähetetty arvo on virheellinen, heitä SaveFailedException, jolloin käyttäjälle näytetään varoitusviesti.

Tuetut lomakkeet

Seuraavia lomakkeita voi laajentaa:

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

Jos haluat lisätä tuen toiselle ydinlomakkeelle, sinun on tehtävä pull requestissa seuraava muutos:

Lisää näkymätiedostoon:

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

Saatat joutua luomaan uuden renderöijäluokan, joka perustuu luokkaan DefaultBaseRenderer, jos lomakkeen HTML poikkeaa muista lomakkeista. Saatat myös joutua laajentamaan oletusrenderöijäluokkaa syöttötyypeillä, joita ei ole vielä lisätty.

Toinen tarvittava muutos on lisätä kutsu lomakelaajennuspalvelun luokkaan sen controller-toiminnon sisällä, joka tallentaa lomakkeen:

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

Siinä kaikki!

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

Lokalisointi ^{(New in 3 )}

Lisäosat voivat lisätä omia kielitiedostojaan. Käytettävä tiedostomuoto on .mo, sama kuin ydinosan käännöksissä. Tiedostot on tallennettava polkuun

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

jossa "<language>" on kaksikirjaiminen tunnus, kuten "de" tai "fr".

Käytä lisäosakohtaista kielitiedostoa lisäosan funktiolla gT:

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

Jos annettua merkkijonoa ei löydy lisäosakohtaisesta kielitiedostosta, funktio etsii sitä ydinosan kielitiedostoista. Siksi on turvallista käyttää merkkijonoja, kuten "Cancel":

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

Jos käytät lisäosasi kanssa näkymiä, käytä

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

suorittaaksesi lisäosakohtaisen käännöksen näkymässäsi.

Voit käyttää tiedostoa limesurvey.pot esimerkkinä siitä, millainen pot-tiedosto voi olla. Se tuodaan käännöstyökaluusi.

Työkalut

Yksi avoimen lähdekoodin työkalu po- ja mo-tiedostojen muokkaamiseen on Poedit.

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

Lokitus ^{(New in 3 )}

Jos haluat kirjata jotain lokiin lisäosastasi, kirjoita vain

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

Oletuslokitustaso on trace, mutta voit antaa toisen lokitustason valinnaisena toisena argumenttina:

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

Lokitiedosto löytyy kansiosta

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

Lisäosasi nimeä käytetään automaattisesti kategoriana. Hyvä tapa nähdä vain lisäosasi virheet on käyttää grep-komentoa (Linuxissa):

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

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

Lisäosan käytöstä poiston kirjaaminen virheen vuoksi ^{(New in 6.13.3 )}

LimeSurveyn version 5 jälkeen lisäosa voidaan poistaa käytöstä automaattisesti PHP-virheen sattuessa.

LimeSurveyn ylläpitäjälle lähetettiin automaattisesti sähköposti. Voit käyttää lokijärjestelmää hälytyksen luomiseen muille palvelimen ylläpitäjille.

Esimerkiksi hälytysviestin lähettäminen:

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

Lisätietoja lokituksen määrittämisestä Yii 1:ssä: Optional_settings#Logging_settings.

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

Laajennusten päivitykset ^{(New in 4 )}

LimeSurveyn version 4.0.0 alkaen käytössä on järjestelmä lisäosien ja muiden laajennusten päivitysten hallintaan. Jotta voit käyttää tätä järjestelmää, laajennuksesi config.xml-tiedostoon on sisällytettävä päivittäjän asetukset.

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

(Yllä oleva source-tunniste osoittaa LimeStoren REST-rajapintaan, jota käytetään kaikille LimeStoressa saatavilla oleville laajennuksille.)

Päivitystunnisteiden kuvaukset

Tunniste	Kuvaus
stable	"1", jos tämä lähde antaa vain vakaiden versioiden numerot; "0", jos lähde tarjoaa myös epävakaita versioita, kuten 0.3.3-beta.
type	Toistaiseksi tuettu on vain tyyppi rest. Uusia päivitystyyppejä (versiontarkistimia), kuten git, wget jne., on helppo lisätä.
source	URL-osoite, josta uudet versiot haetaan.
manualUpdateUrl	URL-osoite, jonka kautta käyttäjä voi päivittää laajennuksen uusimpaan versioon.
automaticUpdateUrl	TODO

Jos et halua tarjota päivitysmekanismia, lisää config XML -tiedostoosi seuraava teksti:

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

Näin kerrot järjestelmälle, että olet poistanut päivitysjärjestelmän käytöstä tarkoituksella etkä vain unohtanut lisätä sitä.

Uusi lisäosa UpdateCheck, joka on asennettu ja aktivoitu oletuksena, tarkistaa kaikkien asennettujen laajennusten uudet päivitykset, kun pääkäyttäjä kirjautuu sisään. Tarkistus tehdään asynkronisesti enintään kerran 24 tunnissa. Jos uusia versioita löytyy, käyttäjälle näytetään ilmoitus.

Jos löytyy uusi turvallisuuspäivitys, ilmoitus avautuu automaattisesti ja sen tyyli on "danger"-luokan mukainen.

Voit tarkistaa päivitykset manuaalisesti siirtymällä lisäosien hallintanäkymään ja napsauttamalla "Check updates". Huomaa, että tämä painike näkyy vain, jos UpdateCheck-lisäosa on aktivoitu.

Konepellin alla

Tässä osiossa on lyhyt yleiskatsaus laajennusten päivittäjän toteutukseen.

Laajennusten päivittäjä on osa ExtensionInstaller-kirjastoa. Alla on UML-kaavio päivitysprosessiin liittyvistä luokista.

Ohjelman kulku Yiin käynnistyessä:

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

Ohjelman kulku UpdaterCheck-lisäosaa suoritettaessa:

 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

UpdateCheck-lisäosan checkAll-metodi näyttää esimerkin siitä, miten kaikilta laajennuksilta kysytään uusia versioita.

Uusien versiontarkistimien lisääminen

Voit lisätä oman versiontarkistimen suorittamalla seuraavan Yiin alustuksen aikana:

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

Luokan MyNewVersionFetcher on tietenkin periydyttävä luokasta VersionFetcher.

Ota uusi versiontarkistin käyttöön asettamalla päivittäjän XML:ssä type-tunnisteen arvoksi myNewVersionFetcherType (esimerkiksi arvon rest sijaan).

Uusien laajennusten päivittäjien lisääminen

Voit lisätä oman laajennusten päivittäjän suorittamalla seuraavan Yiin alustuksen aikana:

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

Luokan MyNewExtensionUpdater on periydyttävä luokasta ExtensionUpdater.

Ylimmän tason type-tunniste tiedostossa config.xml ('plugin', 'theme', ...) määrittää, mitä laajennusten päivittäjää tälle laajennukselle käytetään. Järjestelmä ei ole vielä täysin mukautettavissa, koska tarvitaan myös oma ExtensionInstaller, valikkokohtia jne. Teoriassa ja ehkä tulevaisuudessa tällä tavalla pitäisi kuitenkin olla mahdollista lisätä uusi laajennustyyppi.

Laajennusten asennusohjelma

Laajennusten asennuskirjasto koostuu kahdesta abstraktista luokasta:

• ExtensionInstaller
• FileFetcher

ExtensionInstalleria periytetään jokaiselle laajennustyypille, kuten PluginInstaller, QuestionThemeInstaller jne.

FileFetcheria periytetään jokaiselle eri tavalle hakea tiedostoja. Tällä hetkellä tuettuja ovat vain ladatut zip-tiedostot, mutta tulevaisuudessa mukana voi olla myös Github- tai LimeStore-haku.

Opas

Tämä vaiheittainen opas näyttää, miten luodaan lisäosa, joka lähettää POST-pyynnön jokaisen kyselyn vastauksen lähetyksen yhteydessä. Opas näyttää, miten luodaan ja tallennetaan yleiset ja kyselykohtaiset asetukset, miten tapahtumia rekisteröidään ja paljon muuta.