Плагинууд

Тойм

LimeSurvey нь плагинуудаар дамжуулан функциональ чадвараа нэмэгдүүлэх боломжтой. LimeSurvey нь олон тооны үндсэн плагинуудтай хамт ирдэг. Мөн манай гуравдагч талын плагинуудын жагсаалтыг үзээрэй, ирээдүйд өөрийн плагинаа үүнд нэмээрэй!

Плагинууд нь хэрэглэгчдэд өөрсдийн суулгацын функциональ чадварыг өөрчлөх боломжийг олгохын зэрэгцээ програм хангамжийн тогтмол шинэчлэлтүүдийн давуу талыг ашиглах боломжийг хадгална.

Энэ баримт бичиг нь LimeSurvey-г өөрийн хэрэгцээнд эсвэл үйлчлүүлэгчдэдээ зориулан өргөтгөж буй хөгжүүлэгчдэд зориулагдсан бөгөөд эцсийн хэрэглэгчдэд тус болохгүй.

Плагинууд нь iPlugin интерфэйсийг хэрэгжүүлсэн байх ёстой. Өөрийн плагин классыг PluginBase классаас өргөтгөхийг зөвлөж байна.

Плагинууд нь үйл явдлын механизм дээр суурилан хөгжүүлэгддэг.

Плагины тохиргоо

Өргөтгөснөөр та бидний аль хэдийн хэрэгжүүлсэн плагинуудад шаардлагатай нийтлэг функциональ чадваруудыг ашиглах боломжтой болно. Эдгээр функцийн нэг нь getPluginSettings функцийн хэрэгжилт юм. Энэ функц нь хэрэглэгчид зориулсан тохиргооны сонголтуудыг тодорхойлсон хүснэгтийг буцаах ёстой.

Жишээ плагин нь зөвхөн нэг тохируулах боломжтой тохиргоог, өөрөөр хэлбэл харуулах мессежийг агуулдаг.

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

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

Хүснэгт нь тохиргоо тус бүрийн нэрийг түлхүүр болгон агуулна. Утгууд нь шаардлагатай мета өгөгдлийг агуулсан хүснэгтүүд байна.

Дэмжигдсэн төрлүүд:

• logo
• int (бүхэл тоо)
• string (үсэг тооны)
• text
• html
• relevance
• info
• password
• date
• select

type-аас гадна өөр хэд хэдэн түлхүүр боломжтой:

• label, шошгыг тодорхойлно
• default, утга заагаагүй үед харуулах утгыг тодорхойлно (зөвхөн ерөнхий тохиргоонд, судалгааны тохиргоонд биш)
• current, одоогийн утгыг тодорхойлно.
• readOnly : тохиргоог зөвхөн унших горимоор харуулна
• htmlOptions, оролтын хэсгийн htmlOptions ( Yii гарын авлагыг үзнэ үү [[1]])
• pluginOptions, зарим тохиргооны хувьд (html эсвэл select) : виджетийн сонголтыг тохируулна
• labelOptions : шошгоны htmlOptions
• controlOptions : шошго болон оролтыг хүрээлэх элементийн htmlOptions
• localized : true бол утга хэл тус бүрээр хадгалагдана. Оролт нь name[language] хэлбэрээр илгээгдэх бөгөөд current нь хэлний кодоор индекслэгдсэн хүснэгт байх ёстой.
• language : localized-тэй хамт ашиглагдана. Нэг хэлний код, эсвэл ^{(New in X.Y.Z )} хэл тус бүрт нэг оролт харуулах хэлний кодуудын хүснэгт (үзнэ үү Хэлээр локалчлагдсан плагины тохиргоо)

Бүх одоогийн тохиргоог ашигласан плагины жишээг exampleSettings хаягаас олж болно

Плагины тохиргоог унших болон бичих

Плагины тохиргоог плагиныхаа кодоос шууд унших болон бичих боломжтой.

Жишээ:

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

Хэрэв тохиргоо null байвал үндсэн утгыг авах боломжтой:

$mySetting = $this->get('mySetting', null, null, 10);  // 10 is default

Судалгаанд зориулсан плагины тохиргоо

Судалгаанд зориулсан плагины тохиргоог үүсгэхэд хоёр үйл явдлыг ашигладаг:

• newSurveySettings
• beforeSurveySettings

Тодорхой судалгаанд плагиныг идэвхгүй болгох жишээ:

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

Хэлээр локалчлагдсан плагины тохиргоо ^{(New in 7.4 )}

Нэг тохиргоонд судалгааны хэл тус бүрээр тусдаа оролт харуулахын тулд localized-ийг true болгож, language-д хэлнүүдийн жагсаалтыг дамжуулна уу. Оролт бүрийн шошгод хэлний нэр нэмэгдэнэ.

    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(),
                        // Хэлний кодоор индекслэгдсэн хүснэгт, жишээ нь ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Илгээсэн утга нь хэлний кодоор индекслэгдсэн хүснэгт байдаг тул дээрх жишээн дэх newSurveySettings функц үүнийг ямар ч өөрчлөлтгүйгээр хадгалдаг. Одоогийн хэлний текстийг унших бол:

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

Үйл явдлууд

Плагинууд үйл явдлуудад бүртгүүлж, үйл явдал өдөөгдөх үед LimeSurvey-тэй харилцан үйлчлэх боломжтой. Одоогоор боломжтой үйл явдлуудын жагсаалтыг Плагины үйл явдлууд хуудаснаас харна уу.

API

Плагинууд LimeSurvey-г зөвхөн "public" API-гаар дамжуулан өргөтгөх ёстой. Өөрөөр хэлбэл, эх кодод байгаа классуудыг шууд ашиглах нь буруу туршлага юм. Бид таныг ашиглахыг хориглож чадахгүй ч бидний гаргах жижиг шинэчлэл болгонд плагин тань эвдрэх эрсдэлтэй.

LimeSurvey-тэй аль болох энд тайлбарласан аргуудаар дамжуулан харилцаарай. Үйл явдлын хувьд мөн адил.

PluginBase-ээс өргөтгөх үед API объект $this->api-аар хүртээмжтэй байдаг. Бусад тохиолдолд плагины constructor-т дамжуулагдсан PluginManager instance-аас авч болно.

Хүсэлтээр API объектэд шинэ функц нэмж болно.

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

Маягтын өргөтгөл ^{(New in 6 )}

Танилцуулга

Маягтын өргөтгөлийн систем нь маягт бүрт шинэ үйл явдал нэмэлгүйгээр LimeSurvey-н үндсэн маягтуудыг өргөтгөх илүү ерөнхий арга юм.

Энэ нь дараах бүрэлдэхүүн хэсгүүдээс тогтоно:

• FormExtensionService нэртэй глобал модуль
• Плагинууд дээрх модулийн эхлүүлэлтэд нэмж болох оролтын классуудын сан
• LimeSurvey-ийн харагдацын (view) файлуудад ашиглагддаг, тусгай рендерүүдийн хамт виджет

Маягт бүрийг <form name><dot><tab name> хэлбэртэй байршлын мөрөөр тодорхойлно. Жишээ нь: globalsettings.general эсвэл globalsettings.security.

HTML-гүй, классад суурилсан системийн зорилго нь үндсэн HTML өөрчлөгдөх үед плагин зохиогчдыг HTML-ээ шинэчлэх ажлаас чөлөөлөх явдал юм. Гэсэн хэдий ч шаардлагатай бол зохиогч RawHtmlInput төрлийг ашиглаж болно.

Энэ системд хийж чадахгүй нэг зүйл бол маягтын шинэ табууд нэмэх явдал юм.

Жишээ

Плагинаас маягтад шинэ оролт нэмэхийн тулд өөрийн init() функцээс дараах кодыг ашиглана уу:

TODO: Глобал биш, плагины тохиргоонд хадгалах

// At top of file
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Inside init()
Yii::app()->formExtensionService->add(
    'globalsettings.general',
    new TextInput([
        'name' => 'myinput',
        'label' => 'Label',
        'disabled' => true,
        'tooltip' => 'Moo moo moo',
        'help' => 'Some help text',
        'save' => function($request, $connection) {
            $value = $request->getPost('myinput');
            if ($value === 'some invalid value') {
                throw new SaveFailedException("Could not save custom input 'myinput'");
            } else {
                SettingGlobal::setSetting('myinput', $value);
            }
        },
        'load' => function () {
            return getGlobalSetting('myinput');
        }
    ])
);

Баталгаажуулалт

Оролтын баталгаажуулалтыг save функцэд хийнэ (дээрх жишээг үзнэ үү). Илгээсэн утга буруу бол SaveFailedException шиднэ, ингэснээр хэрэглэгчид анхааруулах flash мессеж харагдана.

Дэмжигдсэн маягтууд

Дараах маягтуудыг өргөтгөж болно:

• globalsettings.general ^{(New in 6.0.0 )}

Хэрэв та өөр цөм формд дэмжлэг нэмэхийг хүсвэл pull-request-д дараах өөрчлөлтийг хийх шаардлагатай:

View файлд дараахыг нэмнэ:

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

Хэрэв формын HTML бусад формоос ялгаатай бол DefaultBaseRenderer дээр суурилсан шинэ renderer класс үүсгэх шаардлагатай байж магадгүй. Мөн үндсэн renderer классыг хараахан нэмэгдээгүй оролтын төрлүүдээр өргөтгөх шаардлагатай байж болно.

Хоёр дахь өөрчлөлт нь формыг хадгалдаг controller action-д form extension service классыг дуудах дуудлага нэмэх явдал юм:

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

Ингээд л боллоо!

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

Локалчлал ^{(New in 3 )}

Плагинууд өөрсдийн locale файлуудыг нэмэх боломжтой. Ашиглах файлын формат нь цөмийн орчуулгатай адил .mo юм. Файлуудыг дараах байршилд хадгалсан байх ёстой:

<plugin root folder>/locale/<language>/<language>.mo

энд "<language>" нь "de" эсвэл "fr" гэх мэт хоёр үсэгт код юм.

Тухайн locale файлыг ашиглахын тулд плагины gT функцийг ашиглана:

$this->gT("A plugin text that needs to be translated");

Хэрэв өгөгдсөн тэмдэгт мөр плагины locale файлаас олдохгүй бол функц цөмийн locale файлуудаас хайна. Иймээс "Cancel" (цуцлах) гэх мэт тэмдэгт мөрүүдийг аюулгүйгээр ашиглаж болно:

$this->gT("Cancel");  // Will be translated even if "Cancel" is not in the plugin locale file

Хэрэв та плагинтайгаа хамт view ашиглаж байгаа бол дараахыг ашиглах хэрэгтэй:

$plugin->gT("Translate me");

ингэснээр view доторх плагин-тусгай орчуулгыг хийнэ.

limesurvey.pot файлыг pot файл ямар харагддаг талаарх жишээ болгон ашиглаж болно. Үүнийг орчуулгын хэрэгсэлдээ импортолно.

Хэрэгслүүд

po болон mo файлуудыг засах нэг нээлттэй эхийн хэрэгсэл бол Poedit юм.

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

Лог бүртгэл ^{(New in 3 )}

Хэрэв та плагинаасаа ямар нэг зүйлийг лог руу бичихийг хүсвэл дараахыг бичээрэй

$this->log("Your message");

Лог бүртгэлийн үндсэн түвшин нь trace бөгөөд нэмэлт хоёр дахь аргументаар өөр логийн түвшинг зааж болно:

$this->log("Something went wrong!", CLogger::LEVEL_ERROR);

Лог файл дараах хавтсанд байрлана:

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

Таны плагины нэр категори болгон автоматаар ашиглагдана. Зөвхөн өөрийн плагины алдаануудыг харах хялбар арга бол (Linux дээр) grep ашиглах явдал юм:

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

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

Алдааны улмаас плагиныг идэвхгүй болгосныг лог бүртгэх ^{(New in 6.13.3 )}

LimeSurvey-ийн 5-р хувилбараас эхлэн PHP алдаа гарсан тохиолдолд плагин автоматаар идэвхгүй болж болно.

LimeSurvey админд цахим шуудан автоматаар илгээгдсэн. Та лог системийг ашиглан серверийн бусад админуудад сэрэмжлүүлэг үүсгэж болно.

Жишээ нь: сэрэмжлүүлэг мессеж илгээх

                // 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
                )

Yii 1 дэх лог бүртгэлийн тохиргооны талаарх дэлгэрэнгүй мэдээлэл: Optional_settings#Logging_settings.

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

Өргөтгөлийн шинэчлэлтүүд ^{(New in 4 )}

LimeSurvey 4.0.0 хувилбараас эхлэн плагин болон бусад өргөтгөлийн шинэчлэлтийг зохицуулах систем нэвтрүүлсэн. Энэ системийг ашиглахын тулд таны өргөтгөлийн config.xml файл шинэчлэгчийн (updater) тохиргоог агуулсан байх ёстой.

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

(Дээрх source tag нь LimeStore REST API руу заадаг бөгөөд манай LimeStore-д байгаа бүх өргөтгөлд ашиглагдана.)

Updater tag-уудын тодорхойлолт

Tag	Тодорхойлолт
stable	"1" бол энэ эх сурвалж зөвхөн тогтвортой хувилбарын дугаар өгнө; "0" бол 0.3.3-beta шиг тогтворгүй хувилбаруудыг мөн өгнө.
type	Одоогоор зөвхөн rest төрлийг дэмждэг. git, wget гэх мэт шинэ updater төрлийг (хувилбар шалгагч) нэмэхэд амархан.
source	Шинэ хувилбаруудыг татах URL.
manualUpdateUrl	Хэрэглэгч өргөтгөлийн сүүлийн хувилбарыг шинэчлэхийн тулд очиж болох URL.
automaticUpdateUrl	TODO

Хэрэв updater оруулахыг хүсэхгүй байвал config XML файлдаа дараах текстийг оруулна уу:

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

Ингэснээр та шинэчлэлийн системийг зориудаар идэвхгүй болгосон бөгөөд нэмэхээ мартаагүй гэдгээ системд мэдэгдэнэ.

Анхдагчаар суулгаж идэвхжүүлсэн шинэ плагин UpdateCheck нь супер админ нэвтрэх үед суулгасан бүх өргөтгөлийн шинэ шинэчлэлтийг асинхрон байдлаар, 24 цагт хамгийн ихдээ нэг удаа шалгана. Шинэ хувилбар олдвол мэдэгдэл илгээнэ.

Хэрэв шинэ аюулгүй байдлын шинэчлэлт олдвол мэдэгдэл автоматаар нээгдэж, "danger" класстай загвартай харагдана.

Плагин менежерийн хуудас руу орж "Check updates" дээр дарж шинэчлэлтийг гараар шалгаж болно. Энэ товч нь зөвхөн UpdateCheck плагин идэвхжсэн үед харагдахыг анхаарна уу.

Дотоод бүтэц

Энэ хэсэгт өргөтгөл шинэчлэгчийн хэрэгжилтийн товч тоймыг толилуулна.

Өргөтгөл шинэчлэгч нь ExtensionInstaller сангийн нэг хэсэг юм. Доорх нь шинэчлэлтийн процесстой холбоотой классуудын UML диаграм юм.

Yii эхлэх үеийн программын урсгал:

 Yii init
   VersionFetcherServiceLocator->init()
     Add REST version fetcher
   ExtensionUpdaterServiceLocator->init()
     Add PluginUpdater
     TODO: Add an updater for each extension type (theme, question template, ...)

UpdaterCheck плагин ажиллах үеийн программын урсгал:

 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

UpdateCheck плагин дахь checkAll метод нь бүх өргөтгөлөөс шинэ хувилбарыг хэрхэн лавлахыг үзүүлсэн жишээ болно.

Шинэ хувилбар шалгагч нэмэх

Шинэ тусгай хувилбар шалгагч нэмэхийн тулд Yii эхлэх үед үүнийг ажиллуулна уу:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
  'myNewVersionFetcherType',
  function (\SimpleXMLElement $updaterXml) {
    return new MyNewVersionFetcher($updaterXml);
  }
);

Мэдээж MyNewVersionFetcher класс нь VersionFetcher-ийн дэд класс байх ёстой.

Шинэ хувилбар шалгагчаа ашиглахын тулд updater XML доторх type tag-ийг myNewVersionFetcherType гэж тохируулна уу (жишээ нь rest-ийн оронд).

Шинэ өргөтгөл шинэчлэгч нэмэх

Шинэ тусгай өргөтгөл шинэчлэгч нэмэхийн тулд Yii эхлэх үед үүнийг ажиллуулна уу:

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

MyNewExtensionUpdater класс нь ExtensionUpdater-ийн дэд класс байх ёстой.

config.xml доторх дээд түвшний type tag ('plugin', 'theme', ...) нь тухайн өргөтгөлд аль өргөтгөл шинэчлэгчийг ашиглахыг тодорхойлно. Та мөн тусгай ExtensionInstaller, цэсийн зүйлс гэх мэтийг нэмэх шаардлагатай тул систем бүрэн тохируулагдах боломжгүй байна. Гэхдээ онолын хувьд, магадгүй ирээдүйд ийм аргаар шинэ төрлийн өргөтгөл нэмэх боломжтой болно.

Өргөтгөл суулгагч

Өргөтгөл суулгагч сан нь хоёр abstract классаас бүрдэнэ:

• ExtensionInstaller
• FileFetcher

ExtensionInstaller-ийг өргөтгөлийн төрөл бүрт дэд класс болгон үүсгэдэг, жишээ нь PluginInstaller, QuestionThemeInstaller гэх мэт.

FileFetcher-ийг файл татах арга бүрт дэд класс болгон үүсгэдэг. Одоогоор зөвхөн байршуулсан zip файлыг дэмждэг боловч ирээдүйд Github эсвэл LimeStore-оос татагч бас нэмэгдэж болно.

Заавар

Энэхүү алхам алхмаар заавар нь судалгааны хариулт бүрийг илгээх бүрд post хүсэлт илгээдэг плагиныг хэрхэн үүсгэхийг харуулна. Мөн глобал болон судалгаа тус бүрийн тохиргоог хэрхэн үүсгэж хадгалах, үйл явдлуудыг хэрхэн бүртгэх зэрэг бусад зүйлийг үзүүлнэ.