Plugins
From LimeSurvey Manual
Ü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.)
| 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.
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 zBrest).
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.
Datei: extensioninstalleruml.png
Spezielle Plugins
Verfügbare Plugins
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.