Actions

Plugins - advanced/it: Difference between revisions

From LimeSurvey Manual

Maren.fritz (talk | contribs)
Created page with "Puoi utilizzare il file [https://github.com/LimeSurvey/LimeSurvey/blob/master/locale/_template/limesurvey.pot limesurvey.pot] come esempio di come può apparire un file pot. Q..."
m Text replacement - "http://manual.limesurvey.org" to "https://manual.limesurvey.org"
 
(50 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<languages />
<languages />
<span id="Overview"></span>
== Panoramica ==
== Panoramica ==


Line 10: Line 11:
I plugin devono implementare l'interfaccia [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin]. Ti consigliamo di estendere la tua classe di plugin dalla classe [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase].  
I plugin devono implementare l'interfaccia [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin]. Ti consigliamo di estendere la tua classe di plugin dalla classe [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase].  


I plugin sono sviluppati attorno a un meccanismo [http://manual.limesurvey.org/Plugin_events].
I plugin sono sviluppati attorno a un meccanismo [https://manual.limesurvey.org/Plugin_events].


<span id="Plugin_settings"></span>
== Impostazioni plugin ==
== Impostazioni plugin ==


Line 75: Line 77:
</syntaxhighlight>
</syntaxhighlight>


=== 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:
<syntaxhighlight lang="php">
 
    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);
    }
</syntaxhighlight>
<span id="Events"></span>
== Eventi ==
== Eventi ==


Line 89: Line 146:
Nuove funzioni possono essere aggiunte all'oggetto API su richiesta.
Nuove funzioni possono essere aggiunte all'oggetto API su richiesta.


<span id="Form_extension{{NewIn|v=6}}"></span>
== Estensione modulo{{NewIn|v=6}} ==
== Estensione modulo{{NewIn|v=6}} ==


<span id="Introduction"></span>
=== Introduzione ===
=== Introduzione ===


Line 107: Line 166:
Una cosa che non puoi fare in questo sistema è aggiungere ''nuove schede modulo''.
Una cosa che non puoi fare in questo sistema è aggiungere ''nuove schede modulo''.


<span id="Example"></span>
=== Esempio ===
=== Esempio ===


Line 142: Line 202:
</syntaxhighlight>
</syntaxhighlight>


<span id="Validation"></span>
=== Convalida ===
=== Convalida ===


La convalida dell'input viene eseguita nella funzione <code>save</code> (vedere l'esempio sopra). Se il valore pubblicato non è valido, lancia un'eccezione <code>SaveFailedException</code> e all'utente verrà mostrato un messaggio flash di avviso.
La convalida dell'input viene eseguita nella funzione <code>save</code> (vedere l'esempio sopra). Se il valore pubblicato non è valido, lancia un'eccezione <code>SaveFailedException</code> e all'utente verrà mostrato un messaggio flash di avviso.


<span id="Supported_forms"></span>
=== Moduli supportati ===
=== Moduli supportati ===


Line 179: Line 241:
Questo è tutto!
Questo è tutto!


<span id="Localization_{{NewIn|v=3}}"></span>
== Localizzazione {{NewIn|v=3}} ==
== Localizzazione {{NewIn|v=3}} ==


Line 209: Line 272:
Puoi utilizzare il file [https://github.com/LimeSurvey/LimeSurvey/blob/master/locale/_template/limesurvey.pot limesurvey.pot] come esempio di come può apparire un file pot. Questo viene importato nel tuo strumento di traduzione.
Puoi utilizzare il file [https://github.com/LimeSurvey/LimeSurvey/blob/master/locale/_template/limesurvey.pot limesurvey.pot] come esempio di come può apparire un file pot. Questo viene importato nel tuo strumento di traduzione.


=== Tools ===
<span id="Tools"></span>
=== Strumenti ===


One open-source tool to edit po- and mo-files is [https://poedit.net/ Poedit].
Uno strumento open source per modificare i file po e mo è [https://poedit.net/Poedit].


== Logging {{NewIn|v=3}} ==
<span id="Logging_{{NewIn|v=3}}"></span>
== Registrazione {{NewIn|v=3}} ==


If you want to log something from your plugin, just write
Se vuoi registrare qualcosa dal tuo plugin, basta scrivere


<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
$this->log("Your message");
$this->log("Il tuo messaggio");
</syntaxhighlight>
</syntaxhighlight>


The default logging level is trace, but you can give another log level as an optional second argument:
Il livello di registrazione predefinito è trace, ma puoi fornire un altro livello di registrazione come secondo argomento facoltativo:


<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
$this->log("Something went wrong!", CLogger::LEVEL_ERROR);
$this->log("Qualcosa è andato storto!", CLogger::LEVEL_ERROR);
</syntaxhighlight>
</syntaxhighlight>


The log file can be found in folder
Il file di registro può essere trovato nella cartella


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


Your plugin name is automatically used as category. A nice way to see only the errors from your plugin is using grep (on Linux):
Il nome del tuo plugin viene automaticamente utilizzato come categoria. Un bel modo per vedere solo gli errori del tuo plugin è usare grep (su Linux):


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


More info about configuring logging in Yii 1: [[Optional_settings#Logging_settings]].
Maggiori informazioni sulla configurazione della registrazione in Yii 1: [[Optional_settings#Logging_settings]].


== Extension updates {{NewIn|v=4}} ==
<span id="Extension_updates_{{NewIn|v=4}}"></span>
== Aggiornamenti estensione {{NewIn|v=4}} ==


Since LimeSurvey version 4.0.0, there's a system in place to deal with plugin and other extension updates. To use this system, your extension config.xml file needs to include updater configuration.
A partire dalla versione 4.0.0 di LimeSurvey, esiste un sistema per gestire gli aggiornamenti dei plug-in e di altre estensioni. Per utilizzare questo sistema, il file config.xml dell'estensione deve includere la configurazione del programma di aggiornamento.


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<updaters>
<updaters>  
    <updater>
<updater>  
        <stable>1</stable>
<stable> 1</stable>  
        <type>rest</type>
<type> riposo</type>  
        <source>https://comfortupdate.limesurvey.org/index.php?r=limestorerest</source>
<source> https://comfortupdate.limesurvey.org/index.php?r=limestorerest</source>  
        <manualUpdateUrl>https://somedownloadlink.com/maybegithub</manualUpdateUrl>
<manualUpdateUrl> https://somedownloadlink.com/maybegithub</manualUpdateUrl>  
    </updater>
</updater>  
</updaters>
</updaters>  
</syntaxhighlight>
</syntaxhighlight>


(The source tag above points to the LimeStore REST API, which will be used for all extensions available in our LimeStore.)
(Il tag sorgente sopra punta all'API REST di LimeStore, che verrà utilizzata per tutte le estensioni disponibili nel nostro LimeStore.)


{| class="wikitable"
{| class="wikitable"
|+ Updater tag descriptions
|+ Descrizioni dei tag di aggiornamento
|-
|-
! Tag
! Etichetta
! Description
! Descrizione
|-
|-
| stable
| stabile
| "1" if this source only gives you stable version numbers; "0" if the source will also provide unstable versions, like <code>0.3.3-beta</code>.
| "1" se questa fonte fornisce solo numeri di versione stabili; "0" se la fonte fornirà anche versioni instabili, come <code>0.3.3-beta</code> .
|-
|-
| type
| digitare
| For now, only type <code>rest</code> is supported. It's easy to add new updater types (version checkers), like git, wget, etc.
| Per ora, è supportato solo <code>rest</code> di tipo. È facile aggiungere nuovi tipi di aggiornamento (controllori di versione), come git, wget, ecc.
|-
|-
| source
| fonte
| The URL to fetch new versions from.
| L'URL da cui recuperare le nuove versioni.
|-
|-
| manualUpdateUrl  
| manualUpdateUrl  
| URL which the user can go to to update the latest version of the extension.
| URL a cui l'utente può accedere per aggiornare l'ultima versione dell'estensione.
|-
|-
| automaticUpdateUrl  
| automaticUpdateUrl  
| TODO
| DA FARE
|}
|}


If you don't want to supply an updater, you should put the following text in your config XML file:
Se non vuoi fornire un aggiornamento, dovresti inserire il seguente testo nel tuo file XML di configurazione:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<updaters disabled="disabled">
<updaters disabled="disabled">  
</updaters>
</updaters>  
</syntaxhighlight>
</syntaxhighlight>


This way, you tell the system that you purposefully disabled the update system, and didn't just forget to add it.
In questo modo, dici al sistema che hai disabilitato intenzionalmente il sistema di aggiornamento e non ti sei semplicemente dimenticato di aggiungerlo.


The new plugin '''UpdateCheck''' - installed and activated by default - checks for new updates for ''all'' installed extensions when a super admin logs in, asynchronously, max one time every 24 hours. If any new versions are found, a notification is pushed.
Il nuovo plugin '''UpdateCheck''' - installato e attivato per impostazione predefinita - verifica la presenza di nuovi aggiornamenti per ''tutte'' le estensioni installate quando un super amministratore accede, in modo asincrono, al massimo una volta ogni 24 ore. Se vengono rilevate nuove versioni, viene inviata una notifica.


[[File:availableupdates.png||Available updates]]
[[File:availableupdates.png||Aggiornamenti disponibili]]


If a new security update is found, the notification will open automatically and be styled in "danger" class.
Se viene trovato un nuovo aggiornamento di sicurezza, la notifica si aprirà automaticamente e sarà inserita nella classe "pericolo".


[[File:availablesecurityupdates.png||Available security updates]]
[[File:availablesecurityupdates.png||Aggiornamenti di sicurezza disponibili]]


You can manually check for updates by going to the plugin manager view and click on "Check updates". Note that this button is only visible if the UpdateCheck plugin is activated.
Puoi verificare manualmente la presenza di aggiornamenti andando alla vista del gestore dei plug-in e facendo clic su "Controlla aggiornamenti". Si noti che questo pulsante è visibile solo se il plug-in UpdateCheck è attivato.


[[File:manuallycheckforupdates.png||Manually check for updates]]
[[File:manuallycheckforupdates.png||Verifica manualmente la presenza di aggiornamenti]]


=== Under the hood ===
<span id="Under_the_hood"></span>
=== Sotto il cofano ===


This section provides a brief overview over the extension updater implementation.
Questa sezione fornisce una breve panoramica sull'implementazione dell'estensione di aggiornamento.


The extension updater is part of the ExtensionInstaller library. Below is a UML diagram for the classes related to the updater process.
L'estensione di aggiornamento fa parte della libreria ExtensionInstaller. Di seguito è riportato un diagramma UML per le classi relative al processo di aggiornamento.


[[File:extensionupdateruml.png||Extension updater UML diagram]]
[[File:extensionupdateruml.png||Diagramma UML di aggiornamento dell'estensione]]


Program flow when Yii starts:
Flusso del programma all'avvio di Yii:


<pre>
<pre>
  Yii init
  Yii init
  VersionFetcherServiceLocator->init()
VersionFetcherServiceLocator->init()
    Add REST version fetcher
Aggiungi il fetcher della versione REST
  ExtensionUpdaterServiceLocator->init()
ExtensionUpdaterServiceLocator->init()
    Add PluginUpdater
Aggiungi PluginUpdater
    TODO: Add an updater for each extension type (theme, question template, ...)
TODO: aggiungi un programma di aggiornamento per ogni tipo di estensione (tema, modello di domanda, ...)
</pre>
</pre>


Program flow when running the UpdaterCheck plugin:
Flusso del programma durante l'esecuzione del plug-in UpdaterCheck:


<pre>
<pre>
  Get all updaters from ExtensionUpdaterServiceLocator
  Ottieni tutti gli aggiornamenti da ExtensionUpdaterServiceLocator
  Loop each updater
  Loop ogni programma di aggiornamento
  For each updater, loop through version fetchers configured by <updater> XML
Per ogni programma di aggiornamento, eseguire il loop dei fetcher di versione configurati da<updater> XML
    For each version fetcher, contact remote source and get version information
Per ogni versione fetcher, contatta la fonte remota e ottieni informazioni sulla versione
  Compose all versions into a notification
  Componi tutte le versioni in una notifica
</pre>
</pre>


The [https://github.com/LimeSurvey/LimeSurvey/blob/develop/application/core/plugins/UpdateCheck/UpdateCheck.php#L130 checkAll] method in the UpdateCheck plugin provides an example of how to query all extensions for new versions.
Il metodo [https://github.com/LimeSurvey/LimeSurvey/blob/develop/application/core/plugins/UpdateCheck/UpdateCheck.php#L130 checkAll] nel plugin UpdateCheck fornisce un esempio di come interrogare tutte le estensioni per le nuove versioni .


==== Adding new version fetchers ====
<span id="Adding_new_version_fetchers"></span>
==== Aggiunta di nuovi fetcher di versione ====


To add a new custom version fetcher, run this during Yii initialization:
Per aggiungere un nuovo fetcher di versione personalizzato, eseguilo durante l'inizializzazione di Yii:


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


Of course, the class <code>MyNewVersionFetcher</code> has to subclass <code>VersionFetcher</code>.
Ovviamente, la classe <code>MyNewVersionFetcher</code> deve creare una sottoclasse <code>VersionFetcher</code> .


To use your new version fetcher, configure the <code>type</code> tag in the updater XML to use
Per utilizzare il tuo nuovo fetcher di versione, configura il tag <code>type</code> nell'XML di aggiornamento per utilizzare
<code>myNewVersionFetcherType</code> (instead of e.g. <code>rest</code>).
<code>myNewVersionFetcherType</code> (invece di es. <code>rest</code> ).


==== Adding new extension updaters ====
<span id="Adding_new_extension_updaters"></span>
==== Aggiunta di nuovi programmi di aggiornamento delle estensioni ====


To add a new custom extension updater, run this during Yii initialization:
Per aggiungere un nuovo programma di aggiornamento dell'estensione personalizzato, eseguilo durante l'inizializzazione di Yii:


<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
$service = \Yii::app()->extensionUpdaterServiceLocator;
$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
$service->addUpdaterType(
  'myNewExtensionUpdater',
'myNewExtensionUpdater',
  function () {
function () {
    return MyNewExtensionUpdater::createUpdaters();
return MioNewExtensionUpdater::createUpdaters() ;
  }
}
);
);
</syntaxhighlight>
</syntaxhighlight>


Class <code>MyNewExtensionUpdater</code> has to subclass <code>ExtensionUpdater</code>.
La classe <code>MyNewExtensionUpdater</code> deve sottoclasse <code>ExtensionUpdater</code> .


The top <code>type</code> tag in config.xml ('plugin', 'theme', ...) will control which extension updater are used for this extension. The system is not fully customizable  yet, since you also need to add a custom ExtensionInstaller, menu items, etc. But in theory, and maybe in the future, it should be possible to add a new type of extension this way.
Il tag <code>type</code> superiore in config.xml ('plugin', 'theme', ...) controllerà quale programma di aggiornamento dell'estensione viene utilizzato per questa estensione. Il sistema non è ancora completamente personalizzabile, poiché è necessario aggiungere anche un ExtensionInstaller personalizzato, voci di menu, ecc. Ma in teoria, e forse in futuro, dovrebbe essere possibile aggiungere un nuovo tipo di estensione in questo modo.


== Extension installer ==
<span id="Extension_installer"></span>
== Programma di installazione dell'estensione ==


The extension installer library consists of two abstract classes:
La libreria del programma di installazione delle estensioni è composta da due classi astratte:


* ExtensionInstaller
* ExtensionInstaller
* FileFetcher
* FileFetcher


The ExtensionInstaller is subclassed for each extension type, like PluginInstaller, QuestionThemeInstaller, etc.
ExtensionInstaller è sottoclasse per ogni tipo di estensione, come PluginInstaller, QuestionThemeInstaller, ecc.


The FileFetcher is subclassed for each different way to fetch files. Currently, only uploaded zip files are supported, but in the future, there could be a Github or LimeStore fetcher too.
Il FileFetcher è sottoclasse per ogni modo diverso di recuperare i file. Attualmente sono supportati solo i file zip caricati, ma in futuro potrebbe esserci anche un fetcher Github o LimeStore.


[[File: extensioninstalleruml.png]]
[[File: extensioninstalleruml.png]]


== Special plugins ==
<span id="Special_plugins"></span>
== Plugin speciali ==


* [[Authentication plugin development]]
* [[Sviluppo plug-in di autenticazione]]
* [[Export plugin development]]
* [[Sviluppo plug-in di esportazione]]


== Available plugins ==
<div class="mw-translate-fuzzy">
* [[Authentication plugins]]
== Plugin disponibili ==
* [[Audit log]]
* [[Plugin di autenticazione]]
* [[Registro di controllo]]
* [[CintLink]]
* [[CintLink]]
* [[Available third party plugins]]
* [[Plugin di terze parti disponibili]]
</div>


== Tutorial ==
== Tutorial ==
[https://medium.com/@evently/creating-limesurvey-plugins-adcdf8d7e334 This] step-by-step tutorial shows how to create a plugin that sends a post request on every survey response submission. The tutorial shows you how to create and save global and per-survey settings, how to register events and more.
[https://medium.com/@evently/creating-limesurvey-plugins-adcdf8d7e334 Questo] tutorial passo-passo mostra come creare un plug-in che invia una richiesta di pubblicazione a ogni risposta al sondaggio sottomissione. Il tutorial mostra come creare e salvare le impostazioni globali e per sondaggio, come registrare eventi e altro ancora.


[[Category:Development]]
[[Categoria:Sviluppo]]
[[Category:Plugins]]
[[Categoria:Plugin]]

Latest revision as of 09:16, 15 October 2024

Panoramica

A partire da LimeSurvey 2.05, LimeSurvey supporterà ufficialmente i plugin. Alcuni plugin saranno supportati dal team di LimeSurvey e entreranno nel core. Alcuni saranno supportati da altri al di fuori del team di LimeSurvey. Per aiutarti a trovarli, dai un'occhiata ai Plugin di terze parti disponibili e aggiungi il tuo plug-in!

I plug-in consentono agli utenti di personalizzare la funzionalità della loro installazione pur potendo beneficiare di regolari aggiornamenti software.

Questa documentazione è pensata per gli sviluppatori che stanno estendendo LimeSurvey per uso proprio o per i propri clienti; gli utenti finali non saranno aiutati da questa documentazione.

I plugin devono implementare l'interfaccia iPlugin. Ti consigliamo di estendere la tua classe di plugin dalla classe PluginBase.

I plugin sono sviluppati attorno a un meccanismo [1].

Impostazioni plugin

Estendendo, beneficerai delle funzionalità comuni richieste dai plug-in che abbiamo già implementato per te. Una di queste funzioni è l'implementazione della funzione getPluginSettings. Questa funzione deve restituire un array che descrive le opzioni di configurazione per l'utente.

Il plugin di esempio espone solo 1 impostazione configurabile, il messaggio che mostrerà.

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

'messaggio' => array(
 'tipo' => 'stringa',
 'etichetta' => 'Messaggio'
 )
);

L'array contiene un nome per ogni impostazione come chiave. I valori sono matrici contenenti i metadati richiesti.

I tipi supportati sono:

  • logo
  • int (numero intero)
  • stringa (alfanumerica)
  • testo
  • html
  • rilevanza
  • info
  • password
  • data! N!* selezionare

Oltre al tipo sono disponibili numerose altre chiavi:

  • label, definisce un'etichetta
  • default, definisce un valore da mostrare se non viene specificato alcun valore (solo per le impostazioni globali, non per le impostazioni del sondaggio)
  • current, definisce il valore corrente.
  • readOnly : mostrato le impostazioni come readonly
  • htmlOptions, le htmlOptions della parte di input (vedi il manuale di Yii [[2]])
  • pluginOptions, per alcune impostazioni (html o select): impostare l'opzione del widget
  • labelOptions: htmlOpzioni dell'etichetta
  • controlOptions: htmlOpzioni del wrapper di etichetta e input

Puoi trovare un esempio di plug-in utilizzando tutte le impostazioni effettive su exampleSettings

Leggi e scrivi le impostazioni del plug-in

È possibile leggere e scrivere le impostazioni del plugin direttamente dal codice del plugin.

Esempio:

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

È possibile ottenere un valore predefinito se l'impostazione risulta essere nulla:

$mySetting = $this->get('mySetting', null, null, 10); // 10 è il valore predefinito

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

Eventi

I plugin si iscrivono agli eventi e possono interagire con LimeSurvey quando l'evento viene attivato. Per un elenco degli eventi attualmente disponibili, controlla Plugin events.

API

I plugin dovrebbero estendere LimeSurvey solo tramite la sua API "pubblica". Ciò significa che utilizzare direttamente le classi trovate nel codice sorgente è una cattiva pratica. Anche se non possiamo costringerti a non farlo, rischi di avere un plug-in rotto con ogni aggiornamento minore che facciamo.

Interagisci il più possibile con LimeSurvey solo tramite i metodi descritti qui. Come per gli eventi.

L'oggetto API è disponibile tramite $this->api durante l'estensione da PluginBase, altrimenti puoi ottenerlo dall'istanza PluginManager che viene passata al costruttore dei tuoi plugin.

Nuove funzioni possono essere aggiunte all'oggetto API su richiesta.

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

Estensione modulo (New in 6 )

Introduzione

Il sistema di estensione dei moduli è un modo più generale per estendere i moduli nel core di LimeSurvey senza aggiungere un nuovo evento per ciascun modulo.

Consiste dei seguenti componenti:

  • Un modulo globale chiamato FormExtensionService
  • Una libreria di classi di input che i plugin possono aggiungere all'inizializzazione del modulo precedente
  • Un widget, insieme a renderer personalizzati, utilizzati nei file di visualizzazione di LimeSurvey

Ogni forma è identificata da una stringa di posizione, come<form name><dot><tab name> . Esempio: globalsettings.general o globalsettings.security .

Il punto dietro un sistema basato su classi senza HTML è liberare gli autori del plugin dal lavoro per aggiornare l'HTML quando l'HTML principale cambia. Tuttavia, l'autore può usare il tipo RawHtmlInput se necessario.

Una cosa che non puoi fare in questo sistema è aggiungere nuove schede modulo.

Esempio

Per aggiungere un nuovo input a un form da un plugin, usa il seguente codice dalla tua funzione init() :

TODO: Salva nelle impostazioni del plugin invece che a livello globale

// All'inizio del file
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Dentro init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'myinput', 
 'label' => 'Etichetta',
 'disabled' => true,
 'tooltip' => 'Moo moo moo',
 'help' => 'Alcuni testi di aiuto', 
 'save' => function($request, $connection) {
 $value = $request->getPost('myinput');
 if ($value === 'qualche valore non valido') {
 throw new SaveFailedException("Impossibile salvare l'input personalizzato 'myinput'");
 } else {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'load' => function () {
 return getGlobalSetting('myinput');
 }
 ])
);

Convalida

La convalida dell'input viene eseguita nella funzione save (vedere l'esempio sopra). Se il valore pubblicato non è valido, lancia un'eccezione SaveFailedException e all'utente verrà mostrato un messaggio flash di avviso.

Moduli supportati

Possono essere prorogate le seguenti forme:

  • globalsettings.general (New in 6.0.0 )

Se desideri aggiungere il supporto per un altro modulo principale, devi applicare la seguente modifica in una richiesta pull:

Nel file di visualizzazione, aggiungi:

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

Potrebbe essere necessario creare una nuova classe renderer basata su DefaultBaseRenderer , se il modulo HTML è diverso da altri moduli. Potrebbe anche essere necessario estendere la classe renderer predefinita con tipi di input non ancora aggiunti.

La seconda modifica che devi fare è aggiungere una chiamata alla classe del servizio di estensione del modulo nell'azione del controller che salva il modulo:

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

Questo è tutto!

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

Localizzazione (New in 3 )

È possibile che i plug-in aggiungano i propri file locali. Il formato file utilizzato è .mo, come le traduzioni principali. I file devono essere archiviati in

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

Dove "<language> " è una parola di due lettere come "de" o "fr".

Per utilizzare il file locale specifico, utilizzare la funzione plugin gT:

$this->gT("Un testo plugin che deve essere tradotto");

Se la stringa data non può essere trovata nel file locale specifico del plugin, la funzione cercherà nei file locali principali. Quindi è sicuro usare stringhe come "Annulla":

$this->gT("Annulla"); // Verrà tradotto anche se "Annulla" non è nel file locale del plugin

Se stai usando views insieme al tuo plugin, dovresti usare

$plugin->gT("Traducimi");

per eseguire la traduzione specifica del plug-in a tuo avviso.

Puoi utilizzare il file limesurvey.pot come esempio di come può apparire un file pot. Questo viene importato nel tuo strumento di traduzione.

Strumenti

Uno strumento open source per modificare i file po e mo è [3].

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

Registrazione (New in 3 )

Se vuoi registrare qualcosa dal tuo plugin, basta scrivere

$this->log("Il tuo messaggio");

Il livello di registrazione predefinito è trace, ma puoi fornire un altro livello di registrazione come secondo argomento facoltativo:

$this->log("Qualcosa è andato storto!", CLogger::LEVEL_ERROR);

Il file di registro può essere trovato nella cartella

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

Il nome del tuo plugin viene automaticamente utilizzato come categoria. Un bel modo per vedere solo gli errori del tuo plugin è usare grep (su Linux):

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

Maggiori informazioni sulla configurazione della registrazione in Yii 1: Optional_settings#Logging_settings.

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

Aggiornamenti estensione (New in 4 )

A partire dalla versione 4.0.0 di LimeSurvey, esiste un sistema per gestire gli aggiornamenti dei plug-in e di altre estensioni. Per utilizzare questo sistema, il file config.xml dell'estensione deve includere la configurazione del programma di aggiornamento.

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

(Il tag sorgente sopra punta all'API REST di LimeStore, che verrà utilizzata per tutte le estensioni disponibili nel nostro LimeStore.)

Descrizioni dei tag di aggiornamento
Etichetta Descrizione
stabile "1" se questa fonte fornisce solo numeri di versione stabili; "0" se la fonte fornirà anche versioni instabili, come 0.3.3-beta .
digitare Per ora, è supportato solo rest di tipo. È facile aggiungere nuovi tipi di aggiornamento (controllori di versione), come git, wget, ecc.
fonte L'URL da cui recuperare le nuove versioni.
manualUpdateUrl URL a cui l'utente può accedere per aggiornare l'ultima versione dell'estensione.
automaticUpdateUrl DA FARE

Se non vuoi fornire un aggiornamento, dovresti inserire il seguente testo nel tuo file XML di configurazione:

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

In questo modo, dici al sistema che hai disabilitato intenzionalmente il sistema di aggiornamento e non ti sei semplicemente dimenticato di aggiungerlo.

Il nuovo plugin UpdateCheck - installato e attivato per impostazione predefinita - verifica la presenza di nuovi aggiornamenti per tutte le estensioni installate quando un super amministratore accede, in modo asincrono, al massimo una volta ogni 24 ore. Se vengono rilevate nuove versioni, viene inviata una notifica.

Aggiornamenti disponibili

Se viene trovato un nuovo aggiornamento di sicurezza, la notifica si aprirà automaticamente e sarà inserita nella classe "pericolo".

Aggiornamenti di sicurezza disponibili

Puoi verificare manualmente la presenza di aggiornamenti andando alla vista del gestore dei plug-in e facendo clic su "Controlla aggiornamenti". Si noti che questo pulsante è visibile solo se il plug-in UpdateCheck è attivato.

Verifica manualmente la presenza di aggiornamenti

Sotto il cofano

Questa sezione fornisce una breve panoramica sull'implementazione dell'estensione di aggiornamento.

L'estensione di aggiornamento fa parte della libreria ExtensionInstaller. Di seguito è riportato un diagramma UML per le classi relative al processo di aggiornamento.

Diagramma UML di aggiornamento dell'estensione

Flusso del programma all'avvio di Yii:

 Yii init
 VersionFetcherServiceLocator->init()
 Aggiungi il fetcher della versione REST
 ExtensionUpdaterServiceLocator->init()
 Aggiungi PluginUpdater
 TODO: aggiungi un programma di aggiornamento per ogni tipo di estensione (tema, modello di domanda, ...)

Flusso del programma durante l'esecuzione del plug-in UpdaterCheck:

 Ottieni tutti gli aggiornamenti da ExtensionUpdaterServiceLocator
 Loop ogni programma di aggiornamento
 Per ogni programma di aggiornamento, eseguire il loop dei fetcher di versione configurati da<updater> XML
 Per ogni versione fetcher, contatta la fonte remota e ottieni informazioni sulla versione
 Componi tutte le versioni in una notifica

Il metodo checkAll nel plugin UpdateCheck fornisce un esempio di come interrogare tutte le estensioni per le nuove versioni .

Aggiunta di nuovi fetcher di versione

Per aggiungere un nuovo fetcher di versione personalizzato, eseguilo durante l'inizializzazione di Yii:

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

Ovviamente, la classe MyNewVersionFetcher deve creare una sottoclasse VersionFetcher .

Per utilizzare il tuo nuovo fetcher di versione, configura il tag type nell'XML di aggiornamento per utilizzare

myNewVersionFetcherType (invece di es. rest ).

Aggiunta di nuovi programmi di aggiornamento delle estensioni

Per aggiungere un nuovo programma di aggiornamento dell'estensione personalizzato, eseguilo durante l'inizializzazione di Yii:

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

La classe MyNewExtensionUpdater deve sottoclasse ExtensionUpdater .

Il tag type superiore in config.xml ('plugin', 'theme', ...) controllerà quale programma di aggiornamento dell'estensione viene utilizzato per questa estensione. Il sistema non è ancora completamente personalizzabile, poiché è necessario aggiungere anche un ExtensionInstaller personalizzato, voci di menu, ecc. Ma in teoria, e forse in futuro, dovrebbe essere possibile aggiungere un nuovo tipo di estensione in questo modo.

Programma di installazione dell'estensione

La libreria del programma di installazione delle estensioni è composta da due classi astratte:

  • ExtensionInstaller
  • FileFetcher

ExtensionInstaller è sottoclasse per ogni tipo di estensione, come PluginInstaller, QuestionThemeInstaller, ecc.

Il FileFetcher è sottoclasse per ogni modo diverso di recuperare i file. Attualmente sono supportati solo i file zip caricati, ma in futuro potrebbe esserci anche un fetcher Github o LimeStore.

Plugin speciali

Tutorial

Questo tutorial passo-passo mostra come creare un plug-in che invia una richiesta di pubblicazione a ogni risposta al sondaggio sottomissione. Il tutorial mostra come creare e salvare le impostazioni globali e per sondaggio, come registrare eventi e altro ancora.

Categoria:Sviluppo Categoria:Plugin