Wtyczki - zaawansowane

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ą

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

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.

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

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!

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

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

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

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.

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

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.

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

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.

Pod maską

Ta sekcja zawiera krótki przegląd implementacji aktualizatora rozszerzeń.

Aktualizator rozszerzeń jest częścią biblioteki ExtensionInstaller. Poniżej znajduje się diagram UML dla klas związanych z procesem aktualizacji.

Przebieg programu po uruchomieniu Yii:

 Yii init
 VersionFetcherServiceLocator->init()
 Dodaj moduł pobierania wersji REST
 ExtensionUpdaterServiceLocator->init()
 Dodaj PluginUpdater
 DO ZROBIENIA: Dodaj aktualizator dla każdego typu rozszerzenia (motyw, szablon pytania, ...)

Przebieg programu podczas uruchamiania wtyczki UpdaterCheck:

 Pobierz wszystkie aktualizacje z ExtensionUpdaterServiceLocator
 Zapętlaj każdy aktualizator
 Dla każdego aktualizatora przejrzyj moduły pobierania wersji skonfigurowane przez<updater> XML
 W przypadku każdego modułu pobierania wersji skontaktuj się ze zdalnym źródłem i uzyskaj informacje o wersji
 Skomponuj wszystkie wersje w powiadomienie

Metoda checkAll we wtyczce UpdateCheck stanowi przykład sprawdzania wszystkich rozszerzeń w celu uzyskania nowych wersji .

Dodawanie nowych modułów pobierania wersji

Aby dodać nowy, niestandardowy moduł pobierania wersji, uruchom to podczas inicjalizacji Yii:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
 'myNewVersionFetcherType',
 funkcja (\SimpleXMLElement $updaterXml) {
 zwróć nowy MyNewVersionFetcher( $updaterXml);
 }
);

Oczywiście klasa MyNewVersionFetcher musi być podklasą VersionFetcher .

Aby użyć modułu pobierania nowej wersji, skonfiguruj znacznik type w pliku XML aktualizatora tak, aby używał

myNewVersionFetcherType (zamiast np. rest ).

Dodawanie nowych aktualizacji rozszerzeń

Aby dodać nowy, niestandardowy aktualizator rozszerzeń, uruchom to podczas inicjalizacji Yii:

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

Klasa MyNewExtensionUpdater musi być podklasą ExtensionUpdater .

Znacznik najwyższego type w pliku config.xml („wtyczka”, „motyw”, ...) będzie kontrolował, który aktualizator rozszerzenia będzie używany dla tego rozszerzenia. System nie jest jeszcze w pełni konfigurowalny, ponieważ trzeba także dodać niestandardowy ExtensionInstaller, elementy menu itp. Jednak teoretycznie i być może w przyszłości powinno być możliwe dodanie w ten sposób nowego typu rozszerzenia.

Instalator rozszerzenia

Biblioteka instalatora rozszerzeń składa się z dwóch klas abstrakcyjnych:

• ExtensionInstaller
• FileFetcher

ExtensionInstaller jest podklasą dla każdego typu rozszerzenia, takiego jak PluginInstaller, questionThemeInstaller itp.

FileFetcher jest podklasą dla każdego innego sposobu pobierania plików. Obecnie obsługiwane są tylko przesłane pliki ZIP, ale w przyszłości może pojawić się także moduł pobierania Github lub LimeStore.

Specjalne wtyczki

• Rozwój wtyczki uwierzytelniającej
• Rozwój wtyczki eksportowej

Dostępne wtyczki

• Wtyczki uwierzytelniające
• Dziennik audytu
• CintLink
• Dostępne wtyczki innych firm

Samouczek

Ten samouczek krok po kroku pokazuje, jak utworzyć wtyczkę, która wysyła żądanie opublikowania każdej odpowiedzi w ankiecie przedłożona praca. W tym samouczku dowiesz się, jak tworzyć i zapisywać ustawienia globalne i dotyczące poszczególnych ankiet, jak rejestrować zdarzenia i nie tylko.