Wtyczki - zaawansowane

Przegląd

LimeSurvey umożliwia rozszerzanie funkcjonalności za pomocą wtyczek. LimeSurvey jest już dostarczany z dużą liczbą wtyczek podstawowych. Sprawdź także naszą listę wtyczek innych firm i być może w przyszłości 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ą tworzone w oparciu o mechanizm zdarzeń.

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 : wyświetla ustawienia jako tylko do odczytu
• htmlOptions, htmlOptions części wejściowej (zobacz podręcznik Yii [[1]])
• pluginOptions, dla niektórych ustawień (html lub select) : ustawia opcję widżetu
• labelOptions : htmlOptions etykiety
• controlOptions : htmlOptions kontenera etykiety i pola wejściowego
• localized : jeśli true, wartość jest przechowywana osobno dla każdego języka. Pole jest przesyłane jako name[language], a current musi być tabelą indeksowaną kodem języka.
• language : używane razem z localized. Albo pojedynczy kod języka, albo ^{(New in X.Y.Z )} tabela kodów języków, aby wyświetlić jedno pole dla każdego języka (zobacz Ustawienia wtyczki lokalizowane)

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ą

Ustawienia wtyczki specyficzne dla ankiety

Do tworzenia ustawień wtyczki specyficznych dla ankiety używane są dwa zdarzenia:

• newSurveySettings
• beforeSurveySettings

Przykład wyłączenia wtyczki dla konkretnej ankiety:

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

<span id="Localized_plugin_settings_ ^{(New in 7.4 )}">

Lokalizowane ustawienia wtyczki ^{(New in 7.4 )}

Aby wyświetlić jedno pole dla każdego języka ankiety dla tego samego ustawienia, ustaw localized na true i przekaż listę języków w language. Nazwa języka jest dodawana do etykiety każdego pola.

    public function beforeSurveySettings()
    {
        $event = $this->event;
        $surveyId = intval($event->get('survey'));
        $survey = Survey::model()->findByPk($surveyId);

        $event->set(
            "surveysettings.{$this->id}",
            [
                'name' => get_class($this),
                'settings' => [
                    'errorText' => [
                        'type' => 'text',
                        'label' => $this->gT('Error text'),
                        'localized' => true,
                        'language' => $survey->getAllLanguages(),
                        // Tabela indeksowana kodem języka, np. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Przesłana wartość jest tabelą indeksowaną kodem języka, więc funkcja newSurveySettings z powyższego przykładu zapisuje ją bez żadnych zmian. Aby odczytać tekst dla bieżącego języka:

$errorTexts = $this->get('errorText', 'Survey', $surveyId, []);
$errorText = $errorTexts[App()->getLanguage()] ?? '';

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 za pomocą metod opisanych tutaj. Podobnie jak w przypadku zdarzeń.

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>

<span id="Logging_plugin_deactivation_due_to_error_ ^{(New in 6.13.3 )}">

Rejestrowanie dezaktywacji wtyczki z powodu błędu ^{(New in 6.13.3 )}

Od wersji 5 LimeSurvey wtyczka może zostać automatycznie dezaktywowana w przypadku błędu PHP.

Do administratora LimeSurvey został automatycznie wysłany email. Możesz użyć systemu logowania, aby wygenerować alert dla pozostałych administratorów serwera.

Na przykład: aby wysłać wiadomość z alertem

                // Plugin error happen, plugin was disable : send email using CLogRoute
                'pluginError' => array(
                    'class' => 'CEmailLogRoute', // https://www.yiiframework.com/doc/api/1.1/CEmailLogRoute
                    'categories' => 'application.model.plugin.setLoadError', // A plugin was disable
                    'subject' => '[ERROR] Plugin deactivated',
                    'emails' => ['webmaster@example.org'],
                    'sentFrom' => 'noreply@example.org',
                    'enabled' => 1, // enabled here
                )

Więcej informacji na temat konfiguracji logowania w Yii 1: Optional_settings/pl#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

Znacznik	Opis
stable	„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.
type	Na razie obsługiwany jest tylko typ rest. Łatwo można dodać nowe typy aktualizatorów (sprawdzanie wersji), takie jak git, wget itp.
source	Adres URL, z którego pobierane są nowe wersje.
manualUpdateUrl	Adres URL, pod który użytkownik może przejść, aby zaktualizować rozszerzenie do najnowszej wersji.
automaticUpdateUrl	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.

Samouczek

Ten samouczek krok po kroku pokazuje, jak utworzyć wtyczkę, która wysyła żądanie POST przy każdym przesłaniu odpowiedzi w ankiecie. Samouczek pokazuje, jak utworzyć i zapisać ustawienia globalne oraz ustawienia dla poszczególnych ankiet, jak rejestrować zdarzenia i nie tylko.