Les greffons - avancé
From LimeSurvey Manual
Vue d'ensemble
À partir de LimeSurvey 2.05, LimeSurvey prendra officiellement en charge les plugins. Certains plugins seront supportés par l'équipe LimeSurvey et entreront dans le noyau. Certains seront soutenus par d'autres en dehors de l'équipe LimeSurvey. Pour vous aider à les trouver, consultez les Plugins tiers disponibles et ajoutez-y votre propre plugin !
Les plugins permettent aux utilisateurs de personnaliser les fonctionnalités de leur installation tout en bénéficiant de mises à jour logicielles régulières.
Cette documentation est destinée aux développeurs qui étendent LimeSurvey pour leur propre usage ou pour leurs clients ; les utilisateurs finaux ne seront pas aidés par cette documentation.
Les plugins doivent implémenter l'interface iPlugin. Nous vous recommandons d'étendre votre classe de plugin à partir de la classe PluginBase.
Les plugins sont développés autour d'un mécanisme event.
Paramètres du plugin
En étendant, vous bénéficiez des fonctionnalités communes requises par les plugins que nous avons déjà implémentés pour vous. L'une de ces fonctions est l'implémentation de la fonction getPluginSettings. Cette fonction doit renvoyer un tableau décrivant les options de configuration pour l'utilisateur.
L'exemple de plugin expose un seul paramètre configurable, le message qu'il affichera.
protected $settings = array(
'logo' => array(
'type' => 'logo',
'path' => 'assets/logo.png'
) ,
'message' => array(
'type' => 'string',
'label' => 'Message'
)
);
Le tableau contient un nom pour chaque paramètre sous forme de clé. Les valeurs sont des tableaux contenant les métadonnées requises.
Les types pris en charge sont :
- logo
- int (nombre entier)
- chaîne (alphanumérique)
- texte
- html
- pertinence
- info
- mot de passe
- date!
- sélectionner
Outre le type, un certain nombre d'autres clés sont disponibles :
- label, définit une étiquette
- par défaut, définit une valeur à afficher si aucune valeur n'est spécifiée (uniquement pour les paramètres globaux, pas pour les paramètres d'enquête)
- current, définit la valeur actuelle.
- readOnly : affiché les paramètres en lecture seule
- htmlOptions, les htmlOptions de la partie d'entrée (voir le manuel Yii [[1]])
- pluginOptions, pour quelques paramètres (html ou select) : définissez l'option du widget
- labelOptions : htmlOptions du label
- controlOptions : htmlOptions du wrapper de label et input
Vous pouvez trouver un exemple de plugin utilisant tous les paramètres réels sur exampleSettings
Lire et écrire les paramètres du plugin
Il est possible de lire et d'écrire les paramètres du plugin directement à partir du code de votre plugin.
Exemple:
$mySetting = $this->get('mySetting');
$this->set('mySetting', $mySetting + 1);
Vous pouvez obtenir une valeur par défaut si le paramètre est nul :
$mySetting = $this->get('mySetting', null, null, 10); // 10 est la valeur par défaut
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);
}
Événements
Les plugins s'abonnent aux événements et peuvent interagir avec LimeSurvey lorsque l'événement est déclenché. Pour une liste des événements actuellement disponibles, consultez Événements du plugin.
API
Les plugins ne doivent étendre LimeSurvey que via son API "publique". Cela signifie qu’utiliser directement les classes trouvées dans le code source est une mauvaise pratique. Bien que nous ne puissions pas vous y obliger, vous risquez d'avoir un plugin défectueux à chaque mise à jour mineure que nous effectuons.
Dans la mesure du possible, interagissez avec LimeSurvey uniquement via les méthodes décrites ici. Idem pour les événements.
L'objet API est disponible via $this->api lors de l'extension depuis PluginBase, sinon vous pouvez l'obtenir à partir de l'instance PluginManager qui est transmise au constructeur de vos plugins.
De nouvelles fonctions peuvent être ajoutées à l'objet API sur demande.
<span id="Form_extension (New in 6 )">
Extension de formulaire (New in 6 )
Présentation
Le système d'extension de formulaire est un moyen plus général d'étendre les formulaires dans le noyau de LimeSurvey sans ajouter de nouvel événement pour chaque formulaire.
Il se compose des éléments suivants :
- Un module global appelé FormExtensionService
- Une bibliothèque de classes d'entrée que les plugins peuvent ajouter à l'initialisation du module ci-dessus
- Un widget, ainsi que moteurs de rendu personnalisés, utilisés dans les fichiers de vue LimeSurvey
Chaque formulaire est identifié par une chaîne de position, comme<form name><dot><tab name> . Exemple : globalsettings.general ou globalsettings.security .
L'objectif d'un système basé sur des classes sans HTML est de libérer les auteurs de plugins de l'œuvre pour qu'ils mettent à jour le code HTML lorsque le code HTML principal change. Néanmoins, l'auteur peut utiliser le type RawHtmlInput si nécessaire.
Une chose que vous ne pouvez pas faire dans ce système est d'ajouter de « nouveaux onglets de formulaire ».
Exemple
Pour ajouter une nouvelle entrée à un formulaire à partir d'un plugin, utilisez le code suivant de votre fonction init() :
TODO : Enregistrer dans les paramètres du plugin au lieu de global
// En haut du fichier
utilisez LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
utilisez LimeSurvey\Libraries\FormExtension\SaveFailedException;
// À l'intérieur de init()
Yii::app()->formExtensionService->add(
'globalsettings.general',
new TextInput([
'name' => 'myinput',
'label' => 'Label',
'disabled' => true,
'tooltip' => 'Moo moo moo',
'help' => 'Un texte d'aide',
'save' => function($request, $connection) {
$value = $request->getPost('myinput');
if ($value === 'une valeur invalide') {
throw new SaveFailedException("Impossible d'enregistrer l'entrée personnalisée 'myinput'");
} else {
SettingGlobal::setSetting('myinput', $value);
}
} ,
'load' => function () {
return getGlobalSetting('myinput');
}
])
);
Validation
La validation de la saisie se fait dans la fonction save (voir exemple ci-dessus). Si la valeur publiée n'est pas valide, lancez une SaveFailedException et un message flash d'avertissement sera affiché à l'utilisateur.
Formulaires pris en charge
Les formulaires suivants peuvent être étendus :
- globalsettings.general (New in 6.0.0 )
Si vous souhaitez ajouter la prise en charge d'un autre formulaire principal, vous devez appliquer la modification suivante dans une pull-request :
Dans le fichier de vue, ajoutez :
<?php
use LimeSurvey\Libraries\FormExtension\FormExtensionWidget;
use LimeSurvey\Libraries\FormExtension\Inputs\DefaultBaseRenderer;
?>
... plus HTML
<?= FormExtensionWidget::render(
App()-> formExtensionService->getAll('globalsettings.security'),
nouveau DefaultBaseRenderer()
); ?>
Vous devrez peut-être créer une nouvelle classe de rendu basée sur DefaultBaseRenderer , si le formulaire HTML est différent des autres formulaires. Vous devrez peut-être également étendre la classe de rendu par défaut avec des types d'entrée non encore ajoutés.
La deuxième modification que vous devez effectuer est d'ajouter un appel à la classe de service d'extension de formulaire dans l'action du contrôleur qui enregistre le formulaire :
$request = App()->request;
Yii::app()->formExtensionService->applySave('globalsettings', $request);
C'est ça!
<span id="Localization_ (New in 3 )">
Localisation (New in 3 )
Il est possible pour les plugins d'ajouter leurs propres fichiers de paramètres régionaux. Le format de fichier utilisé est .mo, identique aux traductions principales. Les fichiers doivent être stockés dans
<plugin root folder>/lieu/<language> /<language> .mo
où "<language> " est un mot de deux lettres comme "de" ou "fr".
Pour utiliser le fichier de paramètres régionaux spécifique, utilisez la fonction plugin gT :
$this->gT("Un texte de plugin à traduire");
Si la chaîne donnée ne peut pas être trouvée dans le fichier de paramètres régionaux spécifique au plugin, la fonction recherchera dans les fichiers de paramètres régionaux principaux. Il est donc prudent d'utiliser des chaînes telles que « Annuler » :
$this->gT("Annuler"); // Sera traduit même si "Annuler" n'est pas dans le fichier de paramètres régionaux du plugin
Si vous utilisez des vues avec votre plugin, vous devez utiliser
$plugin->gT("Traduisez-moi");
pour faire une traduction spécifique au plugin à votre avis.
Vous pouvez utiliser le fichier limesurvey.pot comme exemple de ce à quoi peut ressembler un fichier pot. Celui-ci est importé dans votre outil de traduction.
Outils
Un outil open source pour éditer les fichiers po et mo est Poedit.
<span id="Logging_ (New in 3 )">
Journalisation (New in 3 )
Si vous souhaitez enregistrer quelque chose depuis votre plugin, écrivez simplement
$this->log("Votre message");
Le niveau de journalisation par défaut est trace, mais vous pouvez donner un autre niveau de journalisation comme deuxième argument facultatif :
$this->log("Quelque chose s'est mal passé !", CLogger::LEVEL_ERROR);
Le fichier journal se trouve dans le dossier
<limesurvey root folder>/tmp/runtime/plugin.log
Le nom de votre plugin est automatiquement utilisé comme catégorie. Une bonne façon de voir uniquement les erreurs de votre plugin consiste à utiliser grep (sous Linux) :
$ tail -f tmp/runtime/plugin.log | grep<your plugin name>
Plus d'informations sur la configuration de la journalisation dans Yii 1 : Optional_settings#Logging_settings.
<span id="Extension_updates_ (New in 4 )">
Mises à jour de l'extension (New in 4 )
Depuis la version 4.0.0 de LimeSurvey, un système est en place pour gérer les mises à jour des plugins et autres extensions. Pour utiliser ce système, votre fichier d'extension config.xml doit inclure la configuration du programme de mise à jour.
<updaters>
<updater>
<stable> 1</stable>
<type> repos</type>
<source> https://comfortupdate.limesurvey.org/index.php?r=limestorest</source>
<manualUpdateUrl> https://somedownloadlink.com/maybegithub</manualUpdateUrl>
</updater>
</updaters>
(La balise source ci-dessus pointe vers l'API REST LimeStore, qui sera utilisée pour toutes les extensions disponibles dans notre LimeStore.)
| Marquez | Description |
|---|---|
| stable | "1" si cette source ne vous donne que des numéros de version stables ; "0" si la source fournira également des versions instables, comme 0.3.3-beta .
|
| tapez | Pour l’instant, seul le type rest est pris en charge. Il est facile d'ajouter de nouveaux types de programmes de mise à jour (vérificateurs de versions), comme git, wget, etc.
|
| source | L'URL à partir de laquelle récupérer les nouvelles versions. |
| manualUpdateUrl | URL vers laquelle l'utilisateur peut accéder pour mettre à jour la dernière version de l'extension. |
| URL de mise à jour automatique | À FAIRE |
Si vous ne souhaitez pas fournir de programme de mise à jour, vous devez mettre le texte suivant dans votre fichier XML de configuration :
<updaters disabled="disabled">
</updaters>
De cette façon, vous indiquez au système que vous avez délibérément désactivé le système de mise à jour et que vous n'avez pas simplement oublié de l'ajouter.
Le nouveau plugin UpdateCheck - installé et activé par défaut - vérifie les nouvelles mises à jour pour toutes les extensions installées lorsqu'un super administrateur se connecte, de manière asynchrone, au maximum une fois toutes les 24 heures. Si de nouvelles versions sont trouvées, une notification est envoyée.
Si une nouvelle mise à jour de sécurité est trouvée, la notification s'ouvrira automatiquement et sera classée en classe « danger ».
Vous pouvez vérifier manuellement les mises à jour en accédant à la vue du gestionnaire de plugins et en cliquant sur « Vérifier les mises à jour ». Notez que ce bouton n'est visible que si le plugin UpdateCheck est activé.
Sous le capot
Cette section fournit un bref aperçu de l'implémentation du programme de mise à jour de l'extension.
Le programme de mise à jour de l'extension fait partie de la bibliothèque ExtensionInstaller. Vous trouverez ci-dessous un diagramme UML pour les classes liées au processus de mise à jour.
Déroulement du programme au démarrage de Yii :
Yii init VersionFetcherServiceLocator->init() Ajoutez un outil de récupération de version REST ExtensionUpdaterServiceLocator->init() Ajoutez PluginUpdater TODO : Ajouter un updater pour chaque type d'extension (thème, modèle de question, ...)
Déroulement du programme lors de l'exécution du plugin UpdaterCheck :
Obtenez toutes les mises à jour de ExtensionUpdaterServiceLocator Bouclez chaque programme de mise à jour Pour chaque programme de mise à jour, parcourez les récupérateurs de versions configurés par<updater> XML Pour chaque outil de récupération de version, contactez la source distante et obtenez des informations sur la version Composez toutes les versions dans une notification
La méthode checkAll du plugin UpdateCheck fournit un exemple de la façon d'interroger toutes les extensions pour les nouvelles versions.
Ajout de nouveaux récupérateurs de version
Pour ajouter un nouveau récupérateur de version personnalisé, exécutez ceci lors de l'initialisation de Yii :
$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
'myNewVersionFetcherType',
function (\SimpleXMLElement $updaterXml) {
return new MyNewVersionFetcher( $updaterXml);
}
);
Bien entendu, la classe MyNewVersionFetcher doit sous-classer VersionFetcher .
Pour utiliser votre nouveau récupérateur de version, configurez la balise type dans le XML du programme de mise à jour pour utiliser
myNewVersionFetcherType(au lieu par exemplerest).
Ajout de nouveaux programmes de mise à jour d'extension
Pour ajouter un nouveau programme de mise à jour d'extension personnalisé, exécutez ceci lors de l'initialisation de Yii :
$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
'myNewExtensionUpdater',
function () {
return MyNewExtensionUpdater::createUpdaters() ;
}
);
La classe MyNewExtensionUpdater doit sous-classer ExtensionUpdater .
La balise type supérieure dans config.xml (« plugin », « thème », ...) contrôlera quel programme de mise à jour d'extension est utilisé pour cette extension. Le système n'est pas encore entièrement personnalisable, puisque vous devez également ajouter un ExtensionInstaller personnalisé, des éléments de menu, etc. Mais en théorie, et peut-être dans le futur, il devrait être possible d'ajouter un nouveau type d'extension de cette façon.
Installateur d'extensions
La bibliothèque d'installation d'extension se compose de deux classes abstraites :
- ExtensionInstaller
- FileFetcher
ExtensionInstaller est une sous-classe pour chaque type d'extension, comme PluginInstaller, QuestionThemeInstaller, etc.
Le FileFetcher est sous-classé pour chaque manière différente de récupérer des fichiers. Actuellement, seuls les fichiers zip téléchargés sont pris en charge, mais à l'avenir, il pourrait également y avoir un outil de récupération Github ou LimeStore.
Plugins spéciaux
Plugins disponibles
Tutoriel
Ce tutoriel étape par étape montre comment créer un plugin qui envoie une demande de publication à chaque réponse à une enquête soumission. Le didacticiel vous montre comment créer et enregistrer des paramètres globaux et par enquête, comment enregistrer des événements et bien plus encore.