Plugins

Übersicht

LimeSurvey bietet die Möglichkeit, Funktionen durch Plugins zu erweitern. LimeSurvey wird bereits mit einer Vielzahl von Core-Plugins ausgeliefert. Schauen Sie sich auch unsere Liste Drittanbieter_Plugins an und fügen Sie vielleicht in Zukunft Ihr eigenes Plugin hinzu!

Mit Plugins können Benutzer die Funktionalität ihrer Installation anpassen und gleichzeitig von regelmäßigen Software-Updates profitieren.

Diese Dokumentation richtet sich an Entwickler, die LimeSurvey für den eigenen Gebrauch oder für ihre Kunden erweitern; Endbenutzern wird diese Dokumentation nicht weiterhelfen.

Plugins müssen die Schnittstelle iPlugin implementieren. Wir empfehlen, Ihre Plugin-Klasse von der Klasse PluginBase zu erweitern.

Plugins werden um einen event-Mechanismus herum entwickelt.

Plugin-Einstellungen

Durch die Erweiterung profitieren Sie von der allgemeinen Funktionalität, die von Plugins benötigt wird, die wir bereits für Sie implementiert haben. Eine dieser Funktionen ist die Implementierung der getPluginSettings-Funktion. Diese Funktion muss ein Array zurückgeben, das die Konfigurationsoptionen für den Benutzer beschreibt.

Das Beispiel-Plugin stellt nur eine konfigurierbare Einstellung bereit, nämlich die angezeigte Meldung.

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

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

Das Array enthält für jede Einstellung einen Namen als Schlüssel. Die Werte sind Arrays, die die erforderlichen Metadaten enthalten.

Unterstützte Typen sind:

• logo
• int (ganzzahlige Zahl)
• string (alphanumerisch)
• text
• html
• relevant
• info
• passwort
• datum! N!* auswählen

Neben dem Typ stehen noch eine Reihe weiterer Schlüssel zur Verfügung:

• label, definiert eine Beschriftung
• default, definiert einen Wert, der angezeigt wird, wenn kein Wert angegeben ist (nur für globale Einstellungen, nicht für Umfrageeinstellungen)
• current, definiert den aktuellen Wert.
• readOnly: Zeigt die Einstellungen schreibgeschützt an
• htmlOptions, die HTML-Optionen des Eingabefelds (siehe Yii-Handbuch [[1]])
• pluginOptions, für bestimmte Einstellungen (html oder select): Widget-Option festlegen
• labelOptions: HTML-Optionen der Beschriftung
• controlOptions: HTML-Optionen des Wrappers von Beschriftung und Eingabefeld
• localized: Wenn true, wird der Wert pro Sprache gespeichert. Die Eingabe wird als name[language] übermittelt, und current muss ein Array sein, indiziert durch den Sprachcode.
• language: Wird zusammen mit localized verwendet. Entweder ein einzelner Sprachcode oder ^{(New in XYZ )} ein Array von Sprachcodes, um eine Eingabe pro Sprache anzuzeigen (siehe Lokalisierte Plugin-Einstellungen)

Ein Plugin-Beispiel mit allen tatsächlichen Einstellungen finden Sie unter exampleSettings

Plugin-Einstellungen lesen und schreiben

Es ist möglich, Plugin-Einstellungen direkt aus Ihrem Plugin-Code zu lesen und zu schreiben.

Beispiel:

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

Sie können einen Standardwert erhalten, wenn die Einstellung zufällig null ist:

$mySetting = $this->get('mySetting', null, null, 10); // 10 ist Standard

Umfragespezifische Plugin-Einstellungen

Zwei Ereignisse werden verwendet, um umfragespezifische Plugin-Einstellungen zu erstellen:

• newSurveySettings
• beforeSurveySettings

Beispiel zum Deaktivieren eines Plugins für eine bestimmte Umfrage:

    public function init()
 {
 $this->subscribe('beforeSurveySettings');
 $this->subscribe('newSurveySettings');
 // Andere Ereignisse...
 }

    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' => 'Plugin für diese Umfrage aktivieren'
                    ],
                ]
            ]
        );
    }

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

Lokalisierte Plugin-Einstellungen ^{(New in 7.4 )}

Um für jede Umfragesprache in derselben Einstellung ein Eingabefeld anzuzeigen, setzen Sie localized auf `true` und übergeben Sie die Liste der Sprachen in language . Der Sprachname wird dann der Beschriftung jedes Eingabefelds hinzugefügt.

    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('Fehlertext'),
 'localized' => true,
 'language' => $survey->getAllLanguages(),
 // Array indiziert nach Sprachcode, z. B. ['en' => '...', 'de' => '...']
 'current' => $this->get('errorText', 'Umfrage', $surveyId, []),
 ],
 ]
 ]
 );
 }

Der übermittelte Wert ist ein Array, indiziert durch den Sprachcode. Die Funktion newSurveySettings aus dem obigen Beispiel speichert ihn daher unverändert. So lesen Sie den Text in der aktuellen Sprache:

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

Ereignisse

Plugins abonnieren Ereignisse und können mit LimeSurvey interagieren, wenn das Ereignis ausgelöst wird. Eine Liste der derzeit verfügbaren Ereignisse finden Sie unter Plugin-Ereignisse.

API

Plugins sollten LimeSurvey nur über seine „öffentliche“ API erweitern. Dies bedeutet, dass die direkte Verwendung von im Quellcode gefundenen Klassen eine schlechte Praxis ist. Obwohl wir Sie nicht zwingen können, dies nicht zu tun, riskieren Sie bei jedem kleineren Update, das wir durchführen, ein defektes Plugin.

Interagieren Sie mit LimeSurvey so weit wie möglich nur über die hier beschriebenen Methoden. Das Gleiche gilt für Events.

Das API-Objekt ist über $this->api verfügbar, wenn es von PluginBase erweitert wird. Andernfalls können Sie es von der PluginManager-Instanz abrufen, die an den Konstruktor Ihres Plugins übergeben wird.

Auf Anfrage können dem API-Objekt neue Funktionen hinzugefügt werden.

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

Formularerweiterung ^{(New in 6 )}

Einführung

Das Formularerweiterungssystem ist eine allgemeinere Möglichkeit, Formulare im Kern von LimeSurvey zu erweitern, ohne für jedes Formular ein neues Ereignis hinzuzufügen.

Es besteht aus folgenden Komponenten:

• Ein globales Modul namens 'FormExtensionService
• Eine Bibliothek von 'Eingabeklassen, die Plugins zur obigen Modulinitialisierung hinzufügen können
• Ein 'Widget, zusammen mit Benutzerdefinierte Renderer, die in den LimeSurvey-Ansichtsdateien verwendet werden

Jedes Formular wird durch eine „Positionszeichenfolge“ identifiziert, z<form name><dot><tab name> . Beispiel: globalsettings.general oder globalsettings.security .

Der Sinn eines klassenbasierten Systems ohne HTML besteht darin, die Plugin-Autoren von der Arbeit zu befreien, damit sie den HTML-Code aktualisieren können, wenn sich der Kern-HTML-Code ändert. Dennoch kann der Autor bei Bedarf den Typ RawHtmlInput verwenden.

Eine Sache, die Sie in diesem System nicht tun können, ist das Hinzufügen „neuer Formularregisterkarten“.

Beispiel

Um einem Formular über ein Plugin eine neue Eingabe hinzuzufügen, verwenden Sie den folgenden Code aus Ihrer init() Funktion:

TODO: In den Plugin-Einstellungen statt global speichern

// Am Anfang der Datei
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 muh muh',
 'help' => 'Einige Hilfetexte', 
 'save' => function($request, $connection) {
 $value = $request->getPost('myinput');
 if ($value === 'irgendein ungültiger Wert') {
 throw new SaveFailedException("Die benutzerdefinierte Eingabe 'myinput' konnte nicht gespeichert werden");
 } else {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'load' => function () {
 return getGlobalSetting('myinput');
 }
 ])
);

Validierung

Die Validierung der Eingabe erfolgt in der save (siehe Beispiel oben). Wenn der gepostete Wert ungültig ist, lösen Sie eine SaveFailedException aus und dem Benutzer wird eine Warnmeldung angezeigt.

Unterstützte Formulare

Folgende Formen können erweitert werden:

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

Wenn Sie Unterstützung für ein anderes Kernformular hinzufügen möchten, müssen Sie die folgende Änderung in einem Pull-Request anwenden:

Fügen Sie in der Ansichtsdatei Folgendes hinzu:

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

Möglicherweise müssen Sie eine neue Renderer-Klasse basierend auf DefaultBaseRenderer erstellen, wenn sich der HTML-Code des Formulars von anderen Formularen unterscheidet. Möglicherweise müssen Sie auch die Standard-Renderer-Klasse um Eingabetypen erweitern, die noch nicht hinzugefügt wurden.

Die zweite Änderung, die Sie vornehmen müssen, ist das Hinzufügen eines Aufrufs der Formularerweiterungsdienstklasse in der Controller-Aktion, die das Formular speichert:

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

Das ist es!

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

Lokalisierung ^{(New in 3 )}

Es ist für Plugins möglich, ihre eigenen Gebietsschemadateien hinzuzufügen. Das verwendete Dateiformat ist .mo, dasselbe wie bei Kernübersetzungen. Die Dateien müssen in gespeichert werden

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

Wo "<language> „ist ein aus zwei Buchstaben bestehendes Wort wie „de“ oder „fr“.

Um die spezifische Gebietsschemadatei zu verwenden, verwenden Sie die Plugin-Funktion gT:

$this->gT("Ein Plugin-Text, der übersetzt werden muss");

Wenn die angegebene Zeichenfolge in der Plugin-spezifischen Gebietsschemadatei nicht gefunden werden kann, sucht die Funktion in den Kerngebietsschemadateien. Daher ist es sicher, Zeichenfolgen wie „Abbrechen“ zu verwenden:

$this->gT("Abbrechen"); // Wird übersetzt, auch wenn „Abbrechen“ nicht in der Plugin-Gebietsschemadatei enthalten ist

Wenn Sie Ansichten zusammen mit Ihrem Plugin verwenden, sollten Sie verwenden

$plugin->gT("Übersetze mich");

um aus Ihrer Sicht eine Plugin-spezifische Übersetzung durchzuführen.

Sie können die Datei limesurvey.pot als Beispiel dafür verwenden, wie eine Pot-Datei aussehen kann. Dies wird in Ihr Übersetzungstool importiert.

Werkzeuge

Ein Open-Source-Tool zum Bearbeiten von Po- und Mo-Dateien ist [2].

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

Protokollierung ^{(New in 3 )}

Wenn Sie etwas von Ihrem Plugin protokollieren möchten, schreiben Sie einfach

$this->log("Ihre Nachricht");

Die Standardprotokollierungsstufe ist „trace“, Sie können jedoch eine andere Protokollierungsstufe als optionales zweites Argument angeben:

$this->log("Etwas ist schiefgelaufen!", CLogger::LEVEL_ERROR);

Die Protokolldatei finden Sie im Ordner

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

Ihr Plugin-Name wird automatisch als Kategorie verwendet. Eine gute Möglichkeit, nur die Fehler Ihres Plugins anzuzeigen, ist die Verwendung von grep (unter Linux):

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

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

Deaktivierung des Protokollierungs-Plugins aufgrund eines Fehlers ^{(New in 6.13.3 )}

Seit Version 5 von LimeSurvey: Ein Plugin kann im Falle eines PHP-Fehlers automatisch deaktiviert werden.

An den LimeSurvey-Administrator wurde automatisch eine E-Mail gesendet. Sie können das Protokollsystem verwenden, um eine Benachrichtigung an die anderen Serveradministratoren zu generieren.

Zum Beispiel: um eine Warnmeldung zu senden

 // Plugin-Fehler aufgetreten, Plugin wurde deaktiviert: E-Mail-Versand über CLogRoute
 'pluginError' => array(
 'class' => 'CEmailLogRoute', // https://www.yiiframework.com/doc/api/1.1/CEmailLogRoute
 'categories' => 'application.model.plugin.setLoadError', // Ein Plugin wurde deaktiviert
 'subject' => '[ERROR] Plugin deaktiviert',
 'emails' => ['webmaster@example.org'],
 'sentFrom' => 'noreply@example.org',
 'enabled' => 1, // hier aktiviert
 )

Weitere Informationen zum Konfigurieren der Protokollierung in Yii 1: Optional_settings/de#Logging_settings.

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

Erweiterungsaktualisierungen ^{(New in 4 )}

Seit LimeSurvey Version 4.0.0 gibt es ein System für den Umgang mit Plugin- und anderen Erweiterungsaktualisierungen. Um dieses System verwenden zu können, muss Ihre Erweiterungsdatei config.xml die Updater-Konfiguration enthalten.

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

(Das obige Quell-Tag verweist auf die LimeStore-REST-API, die für alle in unserem LimeStore verfügbaren Erweiterungen verwendet wird.)

Updater-Tag-Beschreibungen

Tag	Beschreibung
stabil	"1", wenn diese Quelle nur stabile Versionsnummern liefert; "0", wenn die Quelle auch instabile Versionen wie 0.3.3-beta bereitstellt.
Typ	Derzeit wird nur der Typ " rest unterstützt. Es ist einfach, neue Updater-Typen (Versionsprüfer) wie git, wget usw. hinzuzufügen.
Quelle	Die URL, von der neue Versionen abgerufen werden.
manuelleUpdate-URL	URL, die der Benutzer aufrufen kann, um die neueste Version der Erweiterung zu aktualisieren.
automatischeUpdate-URL	TODO

Wenn Sie keinen Updater bereitstellen möchten, sollten Sie den folgenden Text in Ihre Konfigurations-XML-Datei einfügen:

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

Auf diese Weise teilen Sie dem System mit, dass Sie das Update-System absichtlich deaktiviert und nicht einfach vergessen haben, es hinzuzufügen.

Das neue Plugin „UpdateCheck“ – standardmäßig installiert und aktiviert – sucht nach neuen Updates für „alle“ installierten Erweiterungen, wenn sich ein Superadministrator asynchron anmeldet, maximal einmal alle 24 Stunden. Wenn neue Versionen gefunden werden, wird eine Benachrichtigung gesendet.

Wenn ein neues Sicherheitsupdate gefunden wird, wird die Benachrichtigung automatisch geöffnet und in der Kategorie „Gefahr“ angezeigt.

Sie können manuell nach Updates suchen, indem Sie in der Plugin-Manager-Ansicht auf „Updates prüfen“ klicken. Beachten Sie, dass diese Schaltfläche nur sichtbar ist, wenn das UpdateCheck-Plugin aktiviert ist.

Unter der Haube

Dieser Abschnitt bietet einen kurzen Überblick über die Implementierung des Erweiterungs-Updaters.

Der Erweiterungs-Updater ist Teil der ExtensionInstaller-Bibliothek. Unten finden Sie ein UML-Diagramm für die Klassen, die sich auf den Updater-Prozess beziehen.

Programmablauf beim Start von Yii:

 Yii init
 VersionFetcherServiceLocator->init()
 REST-Versions-Fetcher hinzufügen
 ExtensionUpdaterServiceLocator->init()
 PluginUpdater!N hinzufügen! TODO: Für jeden Erweiterungstyp (Theme, Fragenvorlage, ...) einen Updater hinzufügen

Programmablauf beim Ausführen des UpdaterCheck-Plugins:

 Holen Sie sich alle Updater von ExtensionUpdaterServiceLocator
 Schleifen Sie jeden Updater
 Durchlaufen Sie für jeden Updater die von konfigurierten Versionsabrufer<updater> XML
 Wenden Sie sich für jeden Versionsabrufer an die Remote-Quelle und holen Sie sich Versionsinformationen
 Fassen Sie alle Versionen in einer Benachrichtigung zusammen

Die Methode checkAll im UpdateCheck-Plugin bietet ein Beispiel dafür, wie alle Erweiterungen nach neuen Versionen abgefragt werden .

Neue Versionsabrufer hinzufügen

Um einen neuen benutzerdefinierten Versionsabrufer hinzuzufügen, führen Sie Folgendes während der Yii-Initialisierung aus:

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

Natürlich muss die Klasse MyNewVersionFetcher eine Unterklasse VersionFetcher sein.

Um Ihren neuen Versionsabrufer zu verwenden, konfigurieren Sie das type Tag im Updater-XML so, dass es

verwendet. myNewVersionFetcherType (anstelle von zB rest ).

Neue Erweiterungs-Updater hinzufügen

Um einen neuen benutzerdefinierten Erweiterungs-Updater hinzuzufügen, führen Sie diesen während der Yii-Initialisierung aus:

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

Die Klasse MyNewExtensionUpdater muss eine Unterklasse ExtensionUpdater sein.

Das oberste type Tag in config.xml („plugin“, „theme“, ...) steuert, welcher Erweiterungs-Updater für diese Erweiterung verwendet wird. Das System ist noch nicht vollständig anpassbar, da Sie auch einen benutzerdefinierten ExtensionInstaller, Menüelemente usw. hinzufügen müssen. Theoretisch und möglicherweise in Zukunft sollte es jedoch möglich sein, auf diese Weise einen neuen Erweiterungstyp hinzuzufügen.

Erweiterungsinstallationsprogramm

Die Erweiterungsinstallationsbibliothek besteht aus zwei abstrakten Klassen:

• ExtensionInstaller
• FileFetcher

Der ExtensionInstaller ist für jeden Erweiterungstyp in Unterklassen unterteilt, z. B. PluginInstaller, QuestionThemeInstaller usw.

Der FileFetcher ist für jede unterschiedliche Art des Dateiabrufs in Unterklassen unterteilt. Derzeit werden nur hochgeladene ZIP-Dateien unterstützt, aber in Zukunft könnte es auch einen Github- oder LimeStore-Abrufer geben.

Tutorial

Dieses Schritt-für-Schritt-Tutorial zeigt, wie Sie ein Plugin erstellen, das bei jeder Umfrageantwort eine POST-Anfrage sendet. Das Tutorial erklärt, wie Sie globale und umfragespezifische Einstellungen erstellen und speichern, Ereignisse registrieren und vieles mehr.