Plugins - advanced/fr

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.

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!

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.

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.

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

Descriptions des balises du programme de mise à jour

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 exemple rest ).

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

• Développement de plugin d'authentification
• Développement de plugin d'exportation

Plugins disponibles

• Plugins d'authentification
• Journal d'audit
• CintLink
• Plugins tiers 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.