Plugins - advanced/de

Übersicht

Ab LimeSurvey 2.05 unterstützt LimeSurvey offiziell Plugins. Einige Plugins werden vom LimeSurvey-Team unterstützt und in den Kern integriert. Einige werden von anderen außerhalb des LimeSurvey-Teams unterstützt. Um sie leichter zu finden, sehen Sie sich die Verfügbare Plugins von Drittanbietern an und fügen Sie 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 rund um einen Event-Mechanismus 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 als schreibgeschützt an
• htmlOptions, die htmlOptions des Eingabeteils (siehe Yii-Handbuch [[1]])
• PluginOptions, für Einige Einstellungen (HTML oder Select): Legen Sie die Widget-Option fest
• labelOptions: htmlOptions des Labels
• controlOptions: htmlOptions des Wrappers von Label und Eingabe

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

Survey specific plugin settings

Two events are used to create survey specific plugin settings:

• newSurveySettings
• beforeSurveySettings

Example to disable a plugin for a specific survey:

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

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 beschriebenen Methoden hier. Gleiches wie bei Veranstaltungen.

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.

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!

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

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>

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

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 bereitstellt, wie 0.3.3-beta .
Geben Sie	ein 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 zum Abrufen neuer Versionen von.
manualUpdateUrl	URL, zu der der Benutzer gehen kann, um die neueste Version der Erweiterung zu aktualisieren.
AutomaticUpdateUrl	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.

|Verfügbare Updates

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

|Verfügbare Sicherheitsupdates

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.

Spezielle Plugins

• Entwicklung des Authentifizierungs-Plugins
• Entwicklung des Export-Plugins

Verfügbare Plugins

• Authentifizierungs-Plugins
• Audit-Protokoll
• CintLink
• Verfügbare Plugins von Drittanbietern

Tutorial

Dieses Schritt-für-Schritt-Tutorial zeigt, wie man ein Plugin erstellt, das bei jeder Umfrageantwort eine Post-Anfrage sendet Vorlage. Das Tutorial zeigt Ihnen, wie Sie globale und pro-Umfrage-Einstellungen erstellen und speichern, wie Sie Ereignisse registrieren und vieles mehr.