Plugins - advanced/bg

Преглед

Започвайки от 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 е по подразбиране

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

Събития

Приставките се абонират за събития и могат да взаимодействат с 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>

Повече информация за конфигуриране на регистриране в Yii 1: Optional_settings#Logging_settings.

Актуализации на разширенията ^{(New in 4 )}

От LimeSurvey версия 4.0.0 има въведена система за справяне с плъгини и други актуализации на разширения. За да използвате тази система, вашето разширение config.xml файл трябва да включва конфигурация за актуализиране.

<updaters>
<updater>
<stable> 1</stable>
<type> Почивка</type>
<source> https://comfortupdate.limesurvey.org/index.php?r=limestorerest</source>
<manualUpdateUrl> https://somedownloadlink.com/maybegithub</manualUpdateUrl>
</updater>
</updaters>

(Изходният таг по-горе сочи към LimeStore REST API, който ще се използва за всички разширения, налични в нашия LimeStore.)

Описания на маркери за актуализиране

Маркирайте	Описание
стабилен	„1“, ако този източник ви дава само номера на стабилни версии; „0“, ако източникът ще предостави и нестабилни версии, като 0.3.3-beta .
тип	Засега се поддържа само тип rest . Лесно е да добавите нови типове програми за актуализиране (проверки на версиите), като git, wget и др.
източник	URL адресът за извличане на нови версии от.
manualUpdateUrl	URL адрес, на който потребителят може да отиде, за да актуализира най-новата версия на разширението.
automaticUpdateUrl	ЗАДАЧА

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

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

По този начин казвате на системата, че нарочно сте деактивирали системата за актуализиране и не сте забравили просто да я добавите.

Новият плъгин UpdateCheck - инсталиран и активиран по подразбиране - проверява за нови актуализации за всички инсталирани разширения, когато супер администратор влезе, асинхронно, максимум веднъж на всеки 24 часа. Ако бъдат намерени нови версии, се изпраща известие.

|Налични актуализации

Ако бъде намерена нова актуализация на защитата, известието ще се отвори автоматично и ще бъде стилизирано в клас „опасност“.

|Налични актуализации за сигурност

Можете ръчно да проверите за актуализации, като отидете в изгледа на мениджъра на приставките и кликнете върху „Проверка на актуализациите“. Обърнете внимание, че този бутон се вижда само ако е активиран плъгинът UpdateCheck.

|Ръчна проверка за актуализации

Под капака

Този раздел предоставя кратък преглед на внедряването на програмата за актуализиране на разширения.

Актуализаторът на разширението е част от библиотеката ExtensionInstaller. По-долу е UML диаграма за класовете, свързани с процеса на актуализиране.

|UML диаграма на програмата за актуализиране на разширение

Поток на програмата при стартиране на Yii:

Yii init
 VersionFetcherServiceLocator->init()
 Добавете програма за извличане на REST версия
 ExtensionUpdaterServiceLocator->init()
 Добавяне на PluginUpdater
 ЗАДАЧА: Добавете програма за актуализиране за всеки тип разширение (тема, шаблон на въпрос, ...)

Поток на програмата при стартиране на приставката UpdaterCheck:

!Н! Вземете всички актуализации от ExtensionUpdaterServiceLocator
 Цикъл на всеки актуализатор
 За всяка програма за актуализация преминете през програмите за извличане на версии, конфигурирани от<updater> XML
 За всяка версия за извличане, свържете се с отдалечен източник и получете информация за версията
 Композирайте всички версии в известие

Методът checkAll в плъгина UpdateCheck предоставя пример как да направите заявка за всички разширения за нови версии .

Добавяне на средства за извличане на нови версии

За да добавите нова персонализирана програма за извличане на версии, изпълнете това по време на инициализацията на Yii:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
 'myNewVersionFetcherType',
 функция (\SimpleXMLElement $updaterXml) {
 връща нов MyNewVersionFetcher( $updaterXml);
 }
);

Разбира се, класът MyNewVersionFetcher трябва да подкласи VersionFetcher .

За да използвате програмата за извличане на нови версии, конфигурирайте маркера type в XML на програмата за актуализиране да използва

myNewVersionFetcherType (вместо напр. rest ).

Добавяне на нови програми за актуализация на разширения

За да добавите нов инструмент за актуализиране на потребителско разширение, изпълнете това по време на инициализацията на Yii:

$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
 'myNewExtensionUpdater',
 функция () {
 return MyNewExtensionUpdater::createUpdaters() ;
 }
);

Класът MyNewExtensionUpdater трябва да бъде подклас ExtensionUpdater .

Най-горният type таг в config.xml ('plugin', 'theme', ...) ще контролира кой инструмент за актуализиране на разширение се използва за това разширение. Системата все още не може да се персонализира напълно, тъй като трябва да добавите персонализиран ExtensionInstaller, елементи от менюто и т.н. Но на теория и може би в бъдеще би трябвало да е възможно да добавите нов тип разширение по този начин.

Инсталатор на разширение

Библиотеката за инсталиране на разширение се състои от два абстрактни класа:

• ExtensionInstaller
• FileFetcher

ExtensionInstaller е подклас за всеки тип разширение, като PluginInstaller, QuestionThemeInstaller и т.н.

FileFetcher е подклас за всеки различен начин за извличане на файлове. Понастоящем се поддържат само качени zip файлове, но в бъдеще може да има и инструмент за извличане на Github или LimeStore.

Специални добавки

• Разработка на приставка за удостоверяване
• Разработка на приставка за експортиране

Налични добавки

• Добавки за удостоверяване
• Дневник за проверка
• CintLink
• Налични добавки на трети страни

Урок

Този урок стъпка по стъпка показва как да създадете приставка, която изпраща заявка за публикуване при всеки отговор на анкета подаване. Урокът ви показва как да създавате и запазвате глобални настройки и настройки за проучване, как да регистрирате събития и други.