Plugins - avanceret

Oversigt

LimeSurvey har mulighed for at tilføje funktionalitet via plugins. LimeSurvey leveres allerede med et godt antal kerneplugins. Se også vores liste over tredjepartsplugins, og tilføj måske i fremtiden dit eget plugin til den!

Plugins giver brugerne mulighed for at tilpasse funktionaliteten af deres installation, mens de stadig kan drage fordel af regelmæssige softwareopdateringer.

Denne dokumentation er beregnet til udviklere, der udvider LimeSurvey til eget brug eller til deres kunder; slutbrugere vil ikke blive hjulpet af denne dokumentation.

Plugins skal implementere grænsefladen iPlugin. Vi anbefaler at udvide din plugin-klasse fra PluginBase-klassen.

Plugins er udviklet omkring en hændelses-mekanisme.

Plugin-indstillinger

Ved at udvide drager du fordel af den fælles funktionalitet, der kræves af plugins, som vi allerede har implementeret for dig. En af disse funktioner er implementeringen af funktionen getPluginSettings. Denne funktion skal returnere et array, der beskriver konfigurationsmulighederne for brugeren.

Eksemplet plugin afslører kun 1 konfigurerbar indstilling, meddelelsen det vil vise.

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

'message' => array(
 'type' => 'streng',
 'label' => 'Besked'
 )
);

Arrayet indeholder et navn for hver indstilling som en nøgle. Værdierne er arrays, der indeholder de nødvendige metadata.

Understøttede typer er:

• logo
• int (heltal)
• streng (alfanumerisk)
• tekst
• html
• relevans
• info
• adgangskode
• dato
• vælg

Udover type er en række andre nøgler tilgængelige:

• label, definerer en titel
• default, definerer en værdi, der vises, hvis der ikke er angivet nogen værdi (kun for globale indstillinger, ikke for undersøgelsesindstillinger)
• current, definerer den nuværende værdi.
• readOnly : viser indstillingen som skrivebeskyttet
• htmlOptions, htmlOptions for inputdelen (se Yii-manualen [[1]])
• pluginOptions, for nogle indstillinger (html eller select) : angiver widget-indstillingen
• labelOptions : htmlOptions for titlen
• controlOptions : htmlOptions for den omgivende container til titel og input
• localized : hvis true, gemmes værdien pr. sprog. Inputtet sendes som name[language], og current skal være en matrix indekseret efter sprogkode.
• language : bruges sammen med localized. Enten en enkelt sprogkode eller ^{(New in X.Y.Z )} en matrix af sprogkoder, så der vises ét input pr. sprog (se Lokaliserede plugin-indstillinger)

Du kan finde et plugin-eksempel ved at bruge alle faktiske indstillinger på exampleSettings

Læs og skriv plugin-indstillinger

Det er muligt at læse og skrive plugin-indstillinger direkte fra din plugin-kode.

Eksempel:

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

Du kan få en standardværdi, hvis indstillingen tilfældigvis er null:

$mySetting = $this->get('mySetting', null, null, 10); // 10 er standard

Undersøgelsesspecifikke plugin-indstillinger

To hændelser bruges til at oprette undersøgelsesspecifikke plugin-indstillinger:

• newSurveySettings
• beforeSurveySettings

Eksempel på, hvordan man deaktiverer et plugin for en bestemt undersøgelse:

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

Lokaliserede plugin-indstillinger ^{(New in 7.4 )}

For at vise ét input pr. undersøgelsessprog for den samme indstilling skal du sætte localized til true og angive listen over sprog i language. Sprogets navn føjes til titlen på hvert input.

    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(),
                        // Matrix indekseret efter sprogkode, f.eks. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Den indsendte værdi er en matrix indekseret efter sprogkode, så funktionen newSurveySettings fra eksemplet ovenfor gemmer den uden ændringer. Sådan læser du teksten for det aktuelle sprog:

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

Begivenheder

Plugins abonnerer på begivenheder og kan interagere med LimeSurvey, når begivenheden udløses. Se Plugin-begivenheder for en liste over tilgængelige begivenheder.

API

Plugins bør kun udvide LimeSurvey via dets "offentlige" API. Det betyder, at direkte brug af klasser fundet i kildekoden er en dårlig praksis. Selvom vi ikke kan tvinge dig til at lade være, risikerer du at have et ødelagt plugin med hver mindre opdatering, vi laver.

Interager så vidt muligt kun med LimeSurvey via de metoder, der er beskrevet her. Det samme gælder for hændelser.

API-objektet er tilgængeligt via $this->api , når det udvides fra PluginBase, ellers kan du hente det fra PluginManager-instansen, der sendes til dine plugins' konstruktør.

Nye funktioner kan tilføjes til API-objektet efter anmodning.

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

Formularudvidelse ^{(New in 6 )}

Introduktion

Formudvidelsessystemet er en mere generel måde at udvide formularer i kerne LimeSurvey uden at tilføje en ny begivenhed for hver formular.

Den består af følgende komponenter:

• Et globalt modul kaldet FormExtensionService
• Et bibliotek af inputklasser, som plugins kan tilføje til ovenstående modulinitialisering
• En widget sammen med brugerdefinerede renderere, der bruges i LimeSurvey-visningsfilerne

Hver form er identificeret med en positionsstreng, f.eks<form name><dot><tab name> . Eksempel: globalsettings.general eller globalsettings.security .

Pointen bag et klassebaseret system uden HTML er at frigøre plugin-forfatterne af arbejdet til at opdatere HTML'en, når kerne-HTML'en ændres. Alligevel kan forfatteren bruge RawHtmlInput typen, hvis det er nødvendigt.

En ting, du ikke kan gøre i dette system, er at tilføje nye formularfaner.

Eksempel

For at tilføje et nyt input til en formular fra et plugin skal du bruge følgende kode fra din init() funktion:

TODO: Gem i plugin-indstillinger i stedet for globalt

// Øverst i filen
brug LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
brug LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Inside init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'myinput', 
 'label' => 'Etiket',
 'disabled' => sand,
 'tooltip' => 'Moo moo moo',
 'help' => 'Noget hjælpetekst', 
 'save' => funktion($request, $connection) {
 $value = $request->getPost('myinput');
 if ($value === 'en eller anden ugyldig værdi') {
 throw new SaveFailedException("Kunne ikke gemme brugerdefineret input 'myinput'");
 } ellers {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'load' => funktion () {
 return getGlobalSetting('myinput');
 }
 ])
);

Validering

Validering af input udføres i save funktionen (se eksemplet ovenfor). Hvis den bogførte værdi er ugyldig, smid en SaveFailedException , og en advarselsmeddelelse vil blive vist til brugeren.

Understøttede formularer

Følgende formularer kan udvides:

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

Hvis du vil tilføje support til en anden kerneformular, skal du anvende følgende ændring i en pull-anmodning:

Tilføj i visningsfilen:

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

Du skal muligvis oprette en ny gengivelsesklasse baseret på DefaultBaseRenderer , hvis formen HTML er anderledes end andre formularer. Du skal muligvis også udvide standardrendererklassen med inputtyper, der endnu ikke er tilføjet.

Den anden ændring, du skal gøre, er at tilføje et opkald til formularudvidelsesserviceklassen i controllerhandlingen, der gemmer formularen:

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

Det er det!

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

Lokalisering ^{(New in 3 )}

Det er muligt for plugins at tilføje deres egne lokalitetsfiler. Det anvendte filformat er .mo, det samme som kerneoversættelser. Filerne skal gemmes i

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

hvor "<language> " er et ord på to bogstaver som "de" eller "fr".

For at bruge den specifikke lokalitetsfil, brug plugin-funktionen gT:

$this->gT("En plugin-tekst, der skal oversættes");

Hvis den givne streng ikke kan findes i den plugin-specifikke lokalitetsfil, vil funktionen se i de centrale lokalitetsfiler. Så det er sikkert at bruge strenge som "Annuller":

$this->gT("Annuller"); // Vil blive oversat, selvom "Annuller" ikke er i plugin-lokalitetsfilen

Hvis du bruger visninger sammen med dit plugin, skal du bruge

$plugin->gT("Oversæt mig");

at lave plugin-specifik oversættelse i din visning.

Du kan bruge filen limesurvey.pot som et eksempel på, hvordan en pot-fil kan se ud. Dette importeres til dit oversættelsesværktøj.

Værktøj

Et open source-værktøj til at redigere po- og mo-filer er Poedit.

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

Logger ^{(New in 3 )}

Hvis du vil logge noget fra dit plugin, skal du bare skrive

$this->log("Din besked");

Standardlogningsniveauet er sporing, men du kan give et andet logniveau som et valgfrit andet argument:

$this->log("Noget gik galt!", CLogger::LEVEL_ERROR);

Logfilen kan findes i mappen

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

Dit plugin-navn bruges automatisk som kategori. En god måde kun at se fejlene fra dit plugin er at bruge grep (på Linux):

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

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

Logning af deaktivering af plugin på grund af fejl ^{(New in 6.13.3 )}

Siden version 5 af LimeSurvey kan et plugin automatisk deaktiveres i tilfælde af en PHP-fejl.

Der sendes automatisk en e-mail til LimeSurvey-administratoren. Du kan bruge logsystemet til at generere en advarsel til de øvrige serveradministratorer.

Eksempel: sådan sender du en advarselsbesked

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

Mere info om konfiguration af logning i Yii 1: Optional_settings/da#Logging_settings.

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

Udvidelsesopdateringer ^{(New in 4 )}

Siden LimeSurvey version 4.0.0, er der et system på plads til at håndtere plugin og andre udvidelsesopdateringer. For at bruge dette system skal din filtypenavn config.xml inkludere opdateringskonfiguration.

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

(Kildetagget ovenfor peger på LimeStore REST API, som vil blive brugt til alle tilgængelige udvidelser i vores LimeStore.)

Beskrivelser af opdateringstags

Tag	Beskrivelse
stable	"1", hvis denne kilde kun giver dig stabile versionsnumre; "0", hvis kilden også leverer ustabile versioner, såsom 0.3.3-beta.
type	Indtil videre understøttes kun typen rest. Det er nemt at tilføje nye opdateringstyper (versionskontrol), som git, wget osv.
source	URL'en, som nye versioner hentes fra.
manualUpdateUrl	URL, som brugeren kan gå til for at opdatere til den seneste version af udvidelsen.
automaticUpdateUrl	TODO

Hvis du ikke ønsker at levere et opdateringsprogram, skal du indsætte følgende tekst i din config XML-fil:

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

På denne måde fortæller du systemet, at du målrettet har deaktiveret opdateringssystemet og ikke bare har glemt at tilføje det.

Det nye plugin UpdateCheck - installeret og aktiveret som standard - søger efter nye opdateringer til alle installerede udvidelser, når en superadministrator logger på, asynkront, maks. én gang hver 24. time. Hvis der findes nye versioner, sendes en meddelelse.

Hvis der findes en ny sikkerhedsopdatering, åbnes meddelelsen automatisk og stiles i "fare"-klassen.

Du kan manuelt søge efter opdateringer ved at gå til plugin-managervisningen og klikke på "Kontroller opdateringer". Bemærk, at denne knap kun er synlig, hvis UpdateCheck-pluginnet er aktiveret.

Under hætten

Dette afsnit giver et kort overblik over implementeringen af udvidelsesopdateringen.

Udvidelsesopdateringen er en del af ExtensionInstaller-biblioteket. Nedenfor er et UML-diagram for klasserne relateret til opdateringsprocessen.

Programflow, når Yii starter:

 Yii init
 VersionFetcherServiceLocator->init()
 Tilføj REST version fetcher
 ExtensionUpdaterServiceLocator->init()
 Tilføj PluginUpdater
 TODO: Tilføj en opdatering til hver udvidelsestype (tema, spørgsmålskabelon, ...)

Programflow, når du kører UpdaterCheck-pluginnet:

 Hent alle opdateringer fra ExtensionUpdaterServiceLocator
 Loop hver opdatering
 For hver opdatering skal du gå gennem versionshentere konfigureret af<updater> XML
 For hver versionshenter skal du kontakte fjernkilden og få versionsoplysninger
 Komponer alle versioner til en notifikation

Metoden checkAll i UpdateCheck-pluginnet giver et eksempel på, hvordan man forespørger alle udvidelser for nye versioner .

Tilføjelse af nye versionshentere

For at tilføje en ny brugerdefineret versionshenter skal du køre dette under Yii-initialisering:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
 'myNewVersionFetcherType',
 funktion (\SimpleXMLElement $updaterXml) {
 returner ny MyNewVersionFetcher( $updaterXml);
 }
);

Selvfølgelig skal klassen MyNewVersionFetcher underklasse VersionFetcher .

For at bruge din nye versionshenter skal du konfigurere type i opdateringsprogrammet XML til at bruge

myNewVersionFetcherType (i stedet for f.eks. rest ).

Tilføjelse af nye udvidelsesopdateringer

For at tilføje en ny brugerdefineret udvidelsesopdatering skal du køre denne under Yii-initialisering:

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

Class MyNewExtensionUpdater skal underklasse ExtensionUpdater .

Den øverste type tag i config.xml ('plugin', 'theme', ...) vil kontrollere, hvilken udvidelsesopdatering der bruges til denne udvidelse. Systemet er endnu ikke helt tilpasseligt, da du også skal tilføje en tilpasset ExtensionInstaller, menupunkter osv. Men i teorien, og måske i fremtiden, skulle det være muligt at tilføje en ny type udvidelse på denne måde.

Udvidelsesinstallationsprogram

Udvidelsesinstallationsbiblioteket består af to abstrakte klasser:

• ExtensionInstaller
• FileFetcher

ExtensionInstaller er underklassificeret for hver udvidelsestype, såsom PluginInstaller, QuestionThemeInstaller osv.

FileFetcher er underklassificeret for hver anden måde at hente filer på. I øjeblikket understøttes kun uploadede zip-filer, men i fremtiden kan der også være en Github- eller LimeStore-henter.

Vejledning

Denne trin-for-trin-vejledning viser, hvordan du opretter et plugin, der sender en post-forespørgsel ved hver indsendt undersøgelsesbesvarelse. Vejledningen viser, hvordan du opretter og gemmer globale indstillinger og indstillinger pr. undersøgelse, hvordan du registrerer hændelser med mere.