Плъгини - напреднали

Other languages:

Преглед

Започвайки от LimeSurvey 2.05, LimeSurvey официално ще поддържа плъгини. Някои плъгини ще бъдат поддържани от екипа на LimeSurvey и ще бъдат включени в ядрото. Някои ще бъдат подкрепени от други извън екипа на LimeSurvey. За да ги намерите, вижте Налични приставки на трети страни и добавете своя собствена приставка към тях!

Приставките позволяват на потребителите да персонализират функционалността на своята инсталация, като същевременно могат да се възползват от редовните софтуерни актуализации.

Тази документация е предназначена за разработчици, които разширяват LimeSurvey за собствена употреба или за свои клиенти; крайните потребители няма да бъдат подпомогнати от тази документация.

Добавките трябва да имплементират iPlugin интерфейс. Препоръчваме да разширите класа на вашия плъгин от класа PluginBase.

Добавките са разработени около събитие механизъм.

Настройки на плъгина

Чрез разширяването вие се възползвате от общата функционалност, изисквана от добавките, които вече сме внедрили за вас. Една от тези функции е внедряването на функцията getPluginSettings. Тази функция трябва да върне масив, описващ опциите за конфигурация за потребителя.

Примерният плъгин показва само 1 конфигурируема настройка, съобщението, което ще покаже.

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

'message' => array(
 'type' => 'string',
 'label' => 'Message'
 )
);

Масивът съдържа име за всяка настройка като ключ. Стойностите са масиви, съдържащи необходимите метаданни.

Поддържаните типове са:

лого
int (цяло число)
низ (буквено-цифров)
текст
html
релевантност
информация
парола
дата
изберете

Освен тип са налични редица други ключове:

етикет, дефинира етикет
по подразбиране, дефинира стойност, която да се показва, ако не е указана стойност (само за глобални настройки, не за настройки на проучване)
текуща, дефинира текущата стойност.
readOnly: показва настройките като само за четене
htmlOptions, htmlOptions на входната част (вижте ръководството на Yii [[1]])
pluginOptions, за някои настройки (html или изберете) : задайте опцията за джаджа
labelOptions : htmlОпции на етикета
controlOptions : htmlОпции на обвивката на етикета и въвеждане

Можете да намерите пример за приставка, като използвате всички действителни настройки на exampleSettings

Четете и записвайте настройките на приставката

Възможно е да четете и записвате настройките на приставката директно от кода на приставката.

Пример:

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

Можете да получите стойност по подразбиране, ако настройката се окаже нулева:

$mySetting = $this->get('mySetting', null, null, 10); // 10 е по подразбиране

Събития

Приставките се абонират за събития и могат да взаимодействат с LimeSurvey, когато събитието бъде задействано. За списък с налични в момента събития проверете Plugin events.

API

Приставките трябва да разширяват LimeSurvey само чрез неговия „обществен“ API. Това означава, че директното използване на класове, намерени в изходния код, е лоша практика. Въпреки че не можем да ви принудим да не го правите, вие рискувате да имате повреден плъгин с всяка незначителна актуализация, която правим.

Доколкото е възможно, взаимодействайте с LimeSurvey само чрез методите, описани тук. Същото като за събития.

API обектът е достъпен чрез $this->api при разширяване от PluginBase, в противен случай можете да го получите от екземпляра на PluginManager, който се предава на конструктора на вашите добавки.

Нови функции могат да бъдат добавени към API обекта при поискване.

Разширение на формуляра^{(New in 6 )}

Въведение

Системата за разширение на формуляри е по-общ начин за разширяване на формуляри в основния LimeSurvey без добавяне на ново събитие за всеки формуляр.

Състои се от следните компоненти:

Глобален модул, наречен FormExtensionService
Библиотека от входни класове, които добавките могат да добавят към горната инициализация на модула
джаджа, заедно с потребителски рендери, които се използват във файловете за преглед на LimeSurvey

Всяка форма се идентифицира с позиционен низ, като<form name><dot><tab name> . Пример: globalsettings.general или globalsettings.security .

Смисълът зад система, базирана на класове без HTML, е да освободи авторите на плъгина на работата да актуализират HTML, когато основният HTML се промени. Все пак авторът може да използва типа RawHtmlInput , ако е необходимо.

Едно нещо, което не можете да направите в тази система, е да добавите „нови раздели на формуляра“.

Пример

За да добавите нов вход към формуляр от плъгин, използвайте следния код от вашата функция init() :

ЗАДАЧА: Запазете в настройките на плъгина вместо глобално

// В горната част на файла
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// В init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'myinput', 
 'label' => 'Етикет',
 'disabled' => true,
 'tooltip' => 'Moo moo moo',
 'help' => 'Мало помощен текст', 
 'save' => function($request, $connection) {
 $value = $request->getPost('myinput');
 if ($value === 'някоя невалидна стойност') {
 throw new SaveFailedException("Could not save custom input 'myinput'");
 } else {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'load' => function () {
 return getGlobalSetting('myinput');
 }
 ])
);

Валидиране

Валидирането на въведеното се извършва във функцията save (вижте примера по-горе). Ако публикуваната стойност е невалидна, хвърлете SaveFailedException и на потребителя ще се покаже предупредително флаш съобщение.

Поддържани форми

Следните форми могат да бъдат разширени:

globalsettings.general^{(New in 6.0.0 )}

Ако искате да добавите поддръжка за друга основна форма, трябва да приложите следната промяна в заявка за изтегляне:

Във файла за преглед добавете:

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

Може да се наложи да създадете нов клас за изобразяване, базиран на DefaultBaseRenderer , ако формулярът HTML е различен от другите формуляри. Може също така да се наложи да разширите класа за изобразяване по подразбиране с все още недобавени типове вход.

Втората промяна, която трябва да направите, е да добавите извикване към сервизния клас за разширение на формуляр в действието на контролера, което записва формуляра:

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

Това е!

Локализация ^{(New in 3 )}

Възможно е приставките да добавят свои собствени локални файлове. Използваният файлов формат е .mo, същият като основния превод. Файловете трябва да се съхраняват в

<plugin root folder>/локал/<language> /<language> .mo

където "<language> " е дума от две букви като "de" или "fr".

За да използвате конкретния локален файл, използвайте функцията на плъгина gT:

$this->gT("Текст на плъгин, който трябва да бъде преведен");

Ако даденият низ не може да бъде намерен в локалния файл за конкретния плъгин, функцията ще търси в основните локални файлове. Така че е безопасно да използвате низове като "Отказ":

$this->gT("Отказ"); // Ще бъде преведено, дори ако "Отказ" не е във файла с локал на приставката

Ако използвате изгледи заедно с вашия плъгин, трябва да използвате

$plugin->gT("Преведи ме");

за да направите специфичен за плъгина превод по ваш изглед.

Можете да използвате файла limesurvey.pot като пример за това как може да изглежда един pot файл. Това се импортира във вашия инструмент за превод.

Инструменти

Един инструмент с отворен код за редактиране на po- и mo-файлове е Poedit.

Регистриране ^{(New in 3 )}

Ако искате да регистрирате нещо от вашия плъгин, просто пишете

$this->log("Вашето съобщение");

Нивото на регистриране по подразбиране е проследяване, но можете да зададете друго ниво на регистриране като незадължителен втори аргумент:

$this->log("Нещо се обърка!", CLogger::LEVEL_ERROR);

Регистрационният файл може да бъде намерен в папка

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

Името на вашия плъгин автоматично се използва като категория. Добър начин да видите само грешките от вашия плъгин е използването на grep (на Linux):

$ опашка -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.

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

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.

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.

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.

Плъгини - напреднали

From LimeSurvey Manual

Contents

Преглед

Настройки на плъгина

Четете и записвайте настройките на приставката

Събития

API

Разширение на формуляра^{(New in 6 )}

Въведение

Пример

Валидиране

Поддържани форми

Локализация ^{(New in 3 )}

Инструменти

Регистриране ^{(New in 3 )}

Extension updates ^{(New in 4 )}

Under the hood

Adding new version fetchers

Adding new extension updaters

Extension installer

Special plugins

Available plugins

Tutorial

Плъгини - напреднали

From LimeSurvey Manual

Преглед

Настройки на плъгина

Четете и записвайте настройките на приставката

Събития

API

Разширение на формуляра (New in 6 )

Въведение

Пример

Валидиране

Поддържани форми

Локализация (New in 3 )

Инструменти

Регистриране (New in 3 )

Extension updates (New in 4 )

Under the hood

Adding new version fetchers

Adding new extension updaters

Extension installer

Special plugins

Available plugins

Tutorial

Разширение на формуляра^{(New in 6 )}

Локализация ^{(New in 3 )}

Регистриране ^{(New in 3 )}

Extension updates ^{(New in 4 )}