Plugins

Overview

May kakayahan ang LimeSurvey na magdagdag ng functionality sa pamamagitan ng mga plugin. Kasama na sa LimeSurvey ang maraming core plugin. Tingnan din ang aming listahan ng mga third-party plugin at baka sa hinaharap ay maidagdag mo rin doon ang sarili mong plugin!

Pinapayagan ng mga plugin ang mga user na i-customize ang functionality ng kanilang installation habang nakikinabang pa rin sa regular na software update.

Ang dokumentasyong ito ay para sa mga developer na nagpapalawak ng LimeSurvey para sa sarili nilang gamit o para sa kanilang mga kliyente; hindi makakatulong ang dokumentasyong ito sa mga end user.

Dapat i-implement ng mga plugin ang interface na iPlugin. Inirerekomenda naming i-extend ang class ng iyong plugin mula sa class na PluginBase.

Ang mga plugin ay binuo batay sa mekanismo ng event.

Mga setting ng plugin

Sa pag-extend, makikinabang ka sa mga karaniwang functionality na kailangan ng mga plugin na na-implement na namin para sa iyo. Isa sa mga function na ito ay ang implementasyon ng function na getPluginSettings. Dapat magbalik ang function na ito ng array na naglalarawan sa mga opsyon sa configuration para sa user.

Isang configurable na setting lang ang inilalantad ng halimbawang plugin: ang mensaheng ipapakita nito.

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

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

Ang array ay naglalaman ng pangalan para sa bawat setting bilang key. Ang mga value ay mga array na naglalaman ng kinakailangang meta data.

Ang mga sinusuportahang type ay:

• logo
• int (integer number)
• string (alphanumeric)
• text
• html
• relevance
• info
• password
• date
• select

Bukod sa type, may iba pang mga key na magagamit:

• label, nagtatakda ng label
• default, nagtatakda ng value na ipapakita kung walang tinukoy na value (para lang sa mga pangkalahatang setting, hindi para sa mga setting ng survey)
• current, nagtatakda ng kasalukuyang value.
• readOnly : ipinapakita ang mga setting bilang readonly
• htmlOptions, ang htmlOptions ng input na bahagi ( tingnan ang Yii manual [[1]])
• pluginOptions, para sa ilang setting (html o select) : itakda ang opsyon ng widget
• labelOptions : htmlOptions ng label
• controlOptions : htmlOptions ng wrapper ng label at input
• localized : kung true, ang value ay iniimbak kada wika. Ipinapadala ang input bilang name[language] at ang current ay dapat na array na naka-index ayon sa code ng wika.
• language : ginagamit kasama ng localized. Maaaring isang code ng wika, o ^{(New in X.Y.Z )} isang array ng mga code ng wika para magpakita ng isang input kada wika (tingnan ang Mga naka-localize na setting ng plugin)

Makakakita ka ng halimbawang plugin na gumagamit ng lahat ng kasalukuyang setting sa exampleSettings

Pagbasa at pagsulat ng mga setting ng plugin

Posibleng magbasa at magsulat ng mga setting ng plugin nang direkta mula sa code ng iyong plugin.

Halimbawa:

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

Maaari kang kumuha ng default na value kung sakaling null ang setting:

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

Mga setting ng plugin na partikular sa survey

Dalawang event ang ginagamit para gumawa ng mga setting ng plugin na partikular sa survey:

• newSurveySettings
• beforeSurveySettings

Halimbawa para i-disable ang isang plugin sa isang partikular na 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);
    }

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

Mga naka-localize na setting ng plugin ^{(New in 7.4 )}

Upang magpakita ng isang input para sa bawat wika ng survey para sa iisang setting, itakda ang localized sa true at ipasa ang listahan ng mga wika sa language. Idinaragdag ang pangalan ng wika sa label ng bawat input.

    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(),
                        // Array na naka-index ayon sa code ng wika, hal. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Ang ipinadalang value ay isang array na naka-index ayon sa code ng wika, kaya ise-save ito ng function na newSurveySettings mula sa halimbawa sa itaas nang walang anumang pagbabago. Upang basahin ang text para sa kasalukuyang wika:

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

Mga Event

Nagsa-subscribe ang mga plugin sa mga event at maaaring makipag-ugnayan sa LimeSurvey kapag na-fire ang event. Para sa listahan ng mga kasalukuyang available na event, tingnan ang Mga event ng plugin.

API

Dapat lamang palawigin ng mga plugin ang LimeSurvey sa pamamagitan ng "public" na API nito. Ibig sabihin, masamang gawi ang direktang paggamit ng mga class na makikita sa source code. Bagama't hindi ka namin mapipigilan, maaaring masira ang iyong plugin sa bawat minor update na ilalabas namin.

Hangga't maaari, makipag-ugnayan sa LimeSurvey sa pamamagitan lamang ng mga method na inilalarawan dito. Ganoon din para sa mga event.

Available ang API object sa pamamagitan ng $this->api kapag nag-extend mula sa PluginBase; kung hindi, makukuha mo ito mula sa instance ng PluginManager na ipinapasa sa constructor ng iyong mga plugin.

Maaaring magdagdag ng mga bagong function sa API object kapag hiniling.

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

Extension ng form ^{(New in 6 )}

Panimula

Ang sistema ng form extension ay isang mas pangkalahatang paraan upang palawigin ang mga form sa core ng LimeSurvey nang hindi nagdaragdag ng bagong event para sa bawat form.

Binubuo ito ng mga sumusunod na bahagi:

• Isang global na module na tinatawag na FormExtensionService
• Isang library ng mga input class na maaaring idagdag ng mga plugin sa initialization ng nabanggit na module
• Isang widget, kasama ang mga custom renderer, na ginagamit sa mga view file ng LimeSurvey

Ang bawat form ay kinikilala ng isang position string, gaya ng <form name><dot><tab name>. Halimbawa: globalsettings.general o globalsettings.security.

Ang layunin ng sistemang nakabatay sa class na walang HTML ay ang alisin sa mga may-akda ng plugin ang trabahong i-update ang HTML tuwing nagbabago ang HTML ng core. Gayunpaman, maaaring gamitin ng may-akda ang uri na RawHtmlInput kung kinakailangan.

Isang bagay na hindi mo magagawa sa sistemang ito ay ang magdagdag ng mga bagong tab ng form.

Halimbawa

Upang magdagdag ng bagong input sa isang form mula sa isang plugin, gamitin ang sumusunod na code mula sa iyong init() function:

TODO: Save in plugin settings instead of global

// 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');
        }
    ])
);

Pag-validate

Ang pag-validate ng input ay ginagawa sa save function (tingnan ang halimbawa sa itaas). Kung hindi valid ang ipinadalang value, mag-throw ng SaveFailedException, at magpapakita sa user ng flash message na babala.

Mga sinusuportahang form

Maaaring palawigin ang mga sumusunod na form:

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

Kung gusto ninyong magdagdag ng suporta para sa isa pang core form, kailangan ninyong i-apply ang sumusunod na pagbabago sa isang pull request:

Sa view file, magdagdag ng:

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

Maaaring kailangan ninyong gumawa ng bagong renderer class batay sa DefaultBaseRenderer kung iba ang HTML ng form kumpara sa ibang mga form. Maaari rin ninyong kailanganing palawakin ang default na renderer class gamit ang mga uri ng input na hindi pa naidaragdag.

Ang pangalawang pagbabagong kailangan ninyong gawin ay ang magdagdag ng tawag sa form extension service class sa controller action na nagse-save ng form:

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

Iyan na!

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

Lokalisasyon ^{(New in 3 )}

Maaaring magdagdag ang mga plugin ng sarili nilang locale file. Ang ginagamit na format ng file ay .mo, kapareho ng mga core translation. Dapat itago ang mga file sa

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

kung saan ang "<language>" ay salitang may dalawang titik tulad ng "de" o "fr".

Para gamitin ang partikular na locale file, gamitin ang plugin function na gT:

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

Kung hindi makita ang ibinigay na string sa locale file na partikular sa plugin, hahanapin ito ng function sa mga core locale file. Kaya ligtas gumamit ng mga string tulad ng "Cancel":

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

Kung gumagamit kayo ng mga view kasama ng inyong plugin, dapat ninyong gamitin ang

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

para sa pagsasalin na partikular sa plugin sa inyong view.

Maaari ninyong gamitin ang file na limesurvey.pot bilang halimbawa kung ano ang hitsura ng isang pot file. Ini-import ito sa inyong translation tool.

Mga tool

Isang open-source na tool para mag-edit ng po- at mo-file ay ang Poedit.

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

Pag-log ^{(New in 3 )}

Kung gusto ninyong mag-log ng anumang bagay mula sa inyong plugin, isulat lamang ang

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

Ang default na antas ng pag-log ay trace, ngunit maaari kayong magbigay ng ibang antas ng log bilang opsyonal na pangalawang argumento:

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

Matatagpuan ang log file sa folder na

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

Awtomatikong ginagamit ang pangalan ng inyong plugin bilang category. Isang magandang paraan para makita lamang ang mga error mula sa inyong plugin ay ang paggamit ng grep (sa Linux):

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

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

Pag-log ng pag-deactivate ng plugin dahil sa error ^{(New in 6.13.3 )}

Simula sa bersyon 5 ng LimeSurvey: maaaring awtomatikong i-deactivate ang isang plugin kapag nagkaroon ng PHP error.

Awtomatikong nagpadala ng email sa administrator ng LimeSurvey. Maaari ninyong gamitin ang log system para gumawa ng alerto para sa iba pang administrator ng server.

Halimbawa: para magpadala ng alert message

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

Karagdagang impormasyon tungkol sa pag-configure ng pag-log sa Yii 1: Optional_settings/tl#Logging_settings.

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

Mga update ng extension ^{(New in 4 )}

Simula sa bersyon 4.0.0 ng LimeSurvey, may sistema para sa mga update ng plugin at iba pang extension. Para magamit ang sistemang ito, kailangang isama ng config.xml file ng inyong extension ang configuration ng 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>

(Ang source tag sa itaas ay tumuturo sa LimeStore REST API, na gagamitin para sa lahat ng extension na available sa aming LimeStore.)

Paglalarawan ng mga updater tag

Tag	Paglalarawan
stable	"1" kung ang source na ito ay nagbibigay lamang ng mga stable na bersyon; "0" kung magbibigay rin ang source ng mga hindi stable na bersyon, tulad ng 0.3.3-beta.
type	Sa ngayon, tanging ang type na rest lamang ang suportado. Madaling magdagdag ng mga bagong uri ng updater (version checker), tulad ng git, wget, atbp.
source	Ang URL kung saan kukunin ang mga bagong bersyon.
manualUpdateUrl	URL na maaaring puntahan ng user para i-update ang pinakabagong bersyon ng extension.
automaticUpdateUrl	TODO

Kung ayaw mong magbigay ng updater, ilagay ang sumusunod na teksto sa iyong config XML file:

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

Sa ganitong paraan, ipinaaalam mo sa system na sinadya mong i-disable ang update system, at hindi mo lang nakalimutang idagdag ito.

Ang bagong plugin na UpdateCheck - naka-install at naka-activate bilang default - ay naghahanap ng mga bagong update para sa lahat ng naka-install na extension tuwing magla-log in ang isang super admin, nang asynchronous, at hindi hihigit sa isang beses kada 24 oras. Kung may matagpuang mga bagong bersyon, magpapadala ng notification.

Kung may matagpuang bagong Panseguridad na update, awtomatikong magbubukas ang notification at lalabas ito sa istilong "danger" na class.

Maaari mong manu-manong suriin ang mga update sa pamamagitan ng pagpunta sa plugin manager at pag-click sa "Check updates". Tandaan na makikita lamang ang button na ito kung naka-activate ang UpdateCheck plugin.

Sa likod ng sistema

Nagbibigay ang seksyong ito ng maikling overview ng implementasyon ng extension updater.

Ang extension updater ay bahagi ng ExtensionInstaller library. Narito sa ibaba ang UML diagram ng mga class na may kaugnayan sa proseso ng updater.

Daloy ng programa kapag nagsimula ang Yii:

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

Daloy ng programa kapag pinapatakbo ang 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

Ang checkAll method sa UpdateCheck plugin ay nagbibigay ng halimbawa kung paano i-query ang lahat ng extension para sa mga bagong bersyon.

Pagdaragdag ng mga bagong version fetcher

Para magdagdag ng bagong custom na version fetcher, patakbuhin ito habang nag-i-initialize ang Yii:

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

Siyempre, kailangang i-subclass ng class na MyNewVersionFetcher ang VersionFetcher.

Para gamitin ang iyong bagong version fetcher, i-configure ang type tag sa updater XML para gamitin ang myNewVersionFetcherType (sa halip na hal. rest).

Pagdaragdag ng mga bagong extension updater

Para magdagdag ng bagong custom na extension updater, patakbuhin ito habang nag-i-initialize ang Yii:

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

Kailangang i-subclass ng class na MyNewExtensionUpdater ang ExtensionUpdater.

Ang pinakamataas na type tag sa config.xml ('plugin', 'theme', ...) ang magkokontrol kung aling extension updater ang gagamitin para sa extension na ito. Hindi pa ganap na nako-customize ang system, dahil kailangan mo ring magdagdag ng custom na ExtensionInstaller, mga menu item, atbp. Ngunit sa teorya, at marahil sa hinaharap, magiging posible nang magdagdag ng bagong uri ng extension sa ganitong paraan.

Extension installer

Binubuo ang extension installer library ng dalawang abstract class:

• ExtensionInstaller
• FileFetcher

Sinusubclass ang ExtensionInstaller para sa bawat uri ng extension, tulad ng PluginInstaller, QuestionThemeInstaller, atbp.

Sinusubclass ang FileFetcher para sa bawat iba't ibang paraan ng pagkuha ng mga file. Sa ngayon, tanging mga na-upload na zip file lamang ang suportado, ngunit sa hinaharap ay maaaring magkaroon din ng Github o LimeStore fetcher.

Tutorial

Ang step-by-step na tutorial na ito ay nagpapakita kung paano gumawa ng plugin na nagpapadala ng post request sa bawat pagsusumite ng tugon sa survey. Ipinapakita rin ng tutorial kung paano gumawa at mag-save ng mga global na setting at mga setting kada survey, kung paano mag-register ng mga event, at marami pang iba.