Actions

Wtyczki - zaawansowane

From LimeSurvey Manual

Revision as of 09:38, 26 September 2023 by Maren.fritz (talk | contribs) (Created page with "=== Pod maską ===")
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);

Plik dziennika można znaleźć w folderze 

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

Nazwa Twojej wtyczki zostanie automatycznie użyta jako kategoria. Dobrym sposobem na wyświetlenie tylko błędów z wtyczki jest użycie grep (w systemie Linux): 

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

Więcej informacji na temat konfiguracji logowania w Yii 1: Optional_settings#Logging_settings.

Aktualizacje rozszerzeń (New in 4 )

Od wersji LimeSurvey 4.0.0 dostępny jest system obsługujący aktualizacje wtyczek i innych rozszerzeń. Aby móc korzystać z tego systemu, plik rozszerzenia config.xml musi zawierać konfigurację aktualizatora. 

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

(Powyższy tag źródłowy wskazuje na interfejs API REST LimeStore, który będzie używany we wszystkich rozszerzeniach dostępnych w naszym LimeStore.)

Opisy znaczników aktualizacji
Oznacz Opis
stabilny „1”, jeśli to źródło podaje tylko stabilne numery wersji; „0”, jeśli źródło będzie również dostarczać wersje niestabilne, np. 0.3.3-beta .
wpisz Na razie obsługiwany jest tylko typ rest . Dodawanie nowych typów aktualizacji (wersji sprawdzających), takich jak git, wget itp., jest łatwe
źródło Adres URL, z którego można pobrać nowe wersje.
manualUpdateUrl Adres URL, pod który użytkownik może przejść, aby zaktualizować najnowszą wersję rozszerzenia.
automatycznyUpdateUrl DO ZROBIENIA

Jeśli nie chcesz dostarczać aktualizatora, powinieneś umieścić następujący tekst w pliku konfiguracyjnym XML: 

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

W ten sposób informujesz system, że celowo wyłączyłeś system aktualizacji i nie zapomniałeś go dodać.

Nowa wtyczka „UpdateCheck” – domyślnie zainstalowana i aktywowana – sprawdza dostępność nowych aktualizacji dla „wszystkich” zainstalowanych rozszerzeń, gdy superadministrator loguje się asynchronicznie, maksymalnie raz na 24 godziny. Jeśli zostaną znalezione nowe wersje, zostanie wyświetlone powiadomienie.

Dostępne aktualizacje

Jeśli zostanie znaleziona nowa aktualizacja zabezpieczeń, powiadomienie zostanie otwarte automatycznie i będzie oznaczone klasą „niebezpieczeństwo”.

Dostępne aktualizacje zabezpieczeń

Możesz ręcznie sprawdzić dostępność aktualizacji, przechodząc do widoku menedżera wtyczek i klikając „Sprawdź aktualizacje”. Pamiętaj, że ten przycisk jest widoczny tylko wtedy, gdy wtyczka UpdateCheck jest aktywna.

Ręcznie sprawdź dostępność aktualizacji

Pod maską

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=241376"