Actions

Wtyczki - zaawansowane

From LimeSurvey Manual

Revision as of 09:37, 26 September 2023 by Maren.fritz (talk | contribs) (Created page with "<syntaxhighlight lang="php"> $this->log("Coś poszło nie tak!", CLogger::LEVEL_ERROR); </syntaxhighlight>")
Other languages:

Przegląd

Począwszy od LimeSurvey 2.05, LimeSurvey będzie oficjalnie wspierać wtyczki. Niektóre wtyczki będą obsługiwane przez zespół LimeSurvey i zostaną włączone do rdzenia. Niektórzy będą wspierani przez innych spoza zespołu LimeSurvey. Aby pomóc je znaleźć, sprawdź Dostępne wtyczki innych firm i dodaj do niej własną wtyczkę!

Wtyczki umożliwiają użytkownikom dostosowanie funkcjonalności ich instalacji, jednocześnie umożliwiając korzystanie z regularnych aktualizacji oprogramowania.

Niniejsza dokumentacja jest przeznaczona dla programistów, którzy rozszerzają LimeSurvey na własny użytek lub dla swoich klientów; ta dokumentacja nie pomoże użytkownikom końcowym.

Wtyczki muszą implementować interfejs iPlugin. Zalecamy rozszerzenie klasy wtyczki z klasy PluginBase.

Wtyczki są opracowywane w oparciu o mechanizm event.

Ustawienia wtyczki

Rozszerzając, zyskujesz wspólną funkcjonalność wymaganą przez wtyczki, które już dla Ciebie wdrożyliśmy. Jedną z takich funkcji jest implementacja funkcji getPluginSettings. Funkcja ta musi zwrócić tablicę opisującą opcje konfiguracyjne dla użytkownika.

Przykładowa wtyczka udostępnia tylko 1 konfigurowalne ustawienie, komunikat, który wyświetli. 

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

'message' => array(
 'type' => 'string',
 'label' => 'Wiadomość'
 )
);

Tablica zawiera nazwę każdego ustawienia jako klucz. Wartości to tablice zawierające wymagane metadane.

Obsługiwane typy to:

  • logo
  • int (liczba całkowita)
  • string (alfanumeryczny)
  • tekst
  • html
  • znaczenie
  • info
  • hasło
  • data
  • wybierz

Oprócz typu dostępnych jest wiele innych klawiszy:

  • label, definiuje etykietę
  • default, definiuje wartość wyświetlaną, jeśli nie określono żadnej wartości (tylko dla ustawień globalnych, nie dla ustawień ankiety)
  • current, definiuje aktualną wartość.
  • readOnly : pokazał ustawienia jako tylko do odczytu
  • htmlOptions, htmlOptions części wejściowej (zobacz podręcznik Yii [[1]])
  • pluginOptions, dla niektóre ustawienia (html lub wybierz): ustaw opcję widgetu
  • labelOptions : htmlOpcje etykiety
  • controlOptions : htmlOpcje opakowania etykiety i danych wejściowych

Przykład wtyczki wykorzystującej wszystkie aktualne ustawienia można znaleźć pod adresem exampleSettings

Odczyt i zapis ustawień wtyczki

Możliwe jest odczytywanie i zapisywanie ustawień wtyczki bezpośrednio z kodu wtyczki.

Przykład: 

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

Możesz uzyskać wartość domyślną, jeśli ustawienie ma wartość null: 

$mySetting = $this->get('mySetting', null, null, 10); // 10 jest wartością domyślną

Wydarzenia

Wtyczki subskrybują zdarzenia i mogą wchodzić w interakcję z LimeSurvey po uruchomieniu zdarzenia. Listę aktualnie dostępnych wydarzeń znajdziesz w Wydarzenia wtyczek.

API

Wtyczki powinny rozszerzać LimeSurvey wyłącznie poprzez jego „publiczne” API. Oznacza to, że bezpośrednie używanie klas znajdujących się w kodzie źródłowym jest złą praktyką. Chociaż nie możemy Cię do tego zmusić, ryzykujesz uszkodzeniem wtyczki przy każdej drobnej aktualizacji, którą przeprowadzamy.

W miarę możliwości korzystaj z LimeSurvey wyłącznie metodami opisanymi tutaj. Podobnie jak w przypadku wydarzeń.

Obiekt API jest dostępny poprzez $this->api podczas rozszerzania z PluginBase, w przeciwnym razie można go pobrać z instancji PluginManager, która jest przekazywana do konstruktora wtyczek.

Na życzenie do obiektu API można dodać nowe funkcje.

Rozszerzenie formularza (New in 6 )

Wprowadzenie

System rozszerzania formularzy to bardziej ogólny sposób rozszerzania formularzy w rdzeniu LimeSurvey bez dodawania nowego zdarzenia dla każdego formularza.

Składa się z następujących elementów:

  • Globalny moduł o nazwie „FormExtensionService”
  • Biblioteka „klas wejściowych”, które wtyczki mogą dodawać do powyższej inicjalizacji modułu
  • „Widżet” wraz z niestandardowe moduły renderujące, które są używane w plikach widoku LimeSurvey

Każdy formularz jest identyfikowany przez „ciąg pozycji”, np<form name><dot><tab name> . Przykład: globalsettings.general lub globalsettings.security .

Ideą systemu opartego na klasach bez HTML jest umożliwienie autorom wtyczek aktualizacji HTML, gdy zmienia się rdzeń HTML. Mimo to autor może w razie potrzeby użyć typu RawHtmlInput .

Jednej rzeczy, której nie można zrobić w tym systemie, to dodać „nowe karty formularzy”.

Przykład

Aby dodać nowe dane wejściowe do formularza z wtyczki, użyj następującego kodu z funkcji init() :

DO ZROBIENIA: Zapisz w ustawieniach wtyczki zamiast globalnie 

// Na górze pliku
użyj LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
użyj LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Wewnątrz init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'moje wejście', 
 'label' => 'Etykieta',
 'disabled' => true,
 'tooltip' => 'Muu moo moo',
 'help' => 'Tekst pomocy', 
 'save' => funkcja($żądanie, $połączenie) {
 $wartość = $żądanie->getPost('moje wejście');
 if ($wartość === 'jakaś niepoprawna wartość') {
 rzucaj nowy SaveFailedException("Nie można zapisać niestandardowego wejścia 'moje wejście'");
 } else {
 SettingGlobal::setSetting('moje wejście', $wartość);
 }
 } ,
 'load' => funkcja () {
 return getGlobalSetting('myinput');
 }
 ])
);

Walidacja

Walidacja danych wejściowych odbywa się w funkcji save (patrz przykład powyżej). Jeśli opublikowana wartość jest nieprawidłowa, zgłoś SaveFailedException , a użytkownikowi zostanie wyświetlony ostrzegawczy komunikat flash.

Obsługiwane formularze

Można rozszerzyć następujące formy:

  • globalsettings.general (New in 6.0.0 )

Jeśli chcesz dodać obsługę innego formularza podstawowego, musisz zastosować następującą zmianę w żądaniu ściągnięcia:

W pliku widoku dodaj: 

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

Być może będziesz musiał utworzyć nową klasę renderującą opartą na DefaultBaseRenderer , jeśli formularz HTML różni się od innych formularzy. Może być także konieczne rozszerzenie domyślnej klasy modułu renderującego o typy danych wejściowych, które nie zostały jeszcze dodane.

Drugą zmianą, którą musisz wykonać, jest dodanie wywołania klasy usługi rozszerzenia formularza w akcji kontrolera, która zapisuje formularz: 

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

Otóż to!

Lokalizacja (New in 3 )

Wtyczki mogą dodawać własne pliki regionalne. Używany format pliku to .mo, taki sam jak w przypadku podstawowych tłumaczeń. Pliki muszą być przechowywane w formacie 

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

Gdzie "<language> " to dwuliterowe słowo, takie jak "de" lub "fr".

Aby użyć określonego pliku ustawień regionalnych, użyj funkcji wtyczki gT: 

$this->gT("Tekst wtyczki do przetłumaczenia");

Jeśli podanego ciągu nie można znaleźć w pliku ustawień regionalnych wtyczki, funkcja przeszuka podstawowe pliki ustawień regionalnych. Można więc bezpiecznie używać ciągów takich jak „Anuluj”: 

$this->gT("Anuluj"); // Zostanie przetłumaczone, nawet jeśli w pliku ustawień regionalnych wtyczki nie ma opcji „Anuluj”

Jeśli używasz widoków razem ze swoją wtyczką, powinieneś użyć 

$plugin->gT("Przetłumacz mi");

aby w Twoim widoku wykonać tłumaczenie specyficzne dla wtyczki.

Możesz użyć pliku limesurvey.pot jako przykładu wyglądu pliku pot. Zostanie to zaimportowane do Twojego narzędzia do tłumaczenia.

Narzędzia

Jednym z narzędzi typu open source do edycji plików po i mo jest [2].

Rejestrowanie (New in 3 )

Jeśli chcesz zalogować coś ze swojej wtyczki, po prostu napisz 

$this->log("Twoja wiadomość");

Domyślny poziom rejestrowania to śledzenie, ale możesz podać inny poziom rejestrowania jako opcjonalny drugi argument: 

$this->log("Coś poszło nie tak!", CLogger::LEVEL_ERROR);

The log file can be found in folder 

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

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

More info about configuring logging in Yii 1: Optional_settings#Logging_settings.

Extension updates (New in 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. 

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

(The source tag above points to the LimeStore REST API, which will be used for all extensions available in our LimeStore.)

Updater tag descriptions
Tag Description
stable "1" if this source only gives you stable version numbers; "0" if the source will also provide unstable versions, like 0.3.3-beta.
type For now, only type rest is supported. It's easy to add new updater types (version checkers), like git, wget, etc.
source The URL to fetch new versions from.
manualUpdateUrl URL which the user can go to to update the latest version of the extension.
automaticUpdateUrl TODO

If you don't want to supply an updater, you should put the following text in your config XML file: 

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

This way, you tell the system that you purposefully disabled the update system, and didn't just forget to add it.

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.

Available updates

If a new security update is found, the notification will open automatically and be styled in "danger" class.

Available security updates

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.

Manually check for updates

Under the hood

This section provides a brief overview over the extension updater implementation.

The extension updater is part of the ExtensionInstaller library. Below is a UML diagram for the classes related to the updater process.

Extension updater UML diagram

Program flow when Yii starts: 

 Yii init
   VersionFetcherServiceLocator->init()
     Add REST version fetcher
   ExtensionUpdaterServiceLocator->init()
     Add PluginUpdater
     TODO: Add an updater for each extension type (theme, question template, ...)

Program flow when running the UpdaterCheck plugin: 

 Get all updaters from ExtensionUpdaterServiceLocator
 Loop each updater
   For each updater, loop through version fetchers configured by <updater> XML
     For each version fetcher, contact remote source and get version information
 Compose all versions into a notification

The checkAll method in the UpdateCheck plugin provides an example of how to query all extensions for new versions.

Adding new version fetchers

To add a new custom version fetcher, run this during Yii initialization: 

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

Of course, the class MyNewVersionFetcher has to subclass VersionFetcher.

To use your new version fetcher, configure the type tag in the updater XML to use myNewVersionFetcherType (instead of e.g. rest).

Adding new extension updaters

To add a new custom extension updater, run this during Yii initialization: 

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

Class MyNewExtensionUpdater has to subclass ExtensionUpdater.

The top type 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.

Extension installer

The extension installer library consists of two abstract classes:

  • ExtensionInstaller
  • FileFetcher

The ExtensionInstaller is subclassed for each extension type, like PluginInstaller, QuestionThemeInstaller, etc.

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.

Special plugins

Available plugins

Tutorial

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.

Retrieved from "http://manual.limesurvey.org/index.php?title=Plugins_-_advanced/pl&oldid=241343"