Pemalam

Gambaran keseluruhan

LimeSurvey mempunyai keupayaan untuk menambah fungsi melalui pemalam. LimeSurvey sudah dilengkapi dengan sejumlah besar pemalam teras. Selain itu, lihat juga senarai pemalam pihak ketiga kami dan mungkin pada masa hadapan anda boleh menambah pemalam anda sendiri ke dalamnya!

Pemalam membolehkan pengguna menyesuaikan fungsi pemasangan mereka sambil terus mendapat manfaat daripada kemas kini perisian yang tetap.

Dokumentasi ini ditujukan kepada pembangun yang memperluas LimeSurvey untuk kegunaan sendiri atau untuk pelanggan mereka; pengguna akhir tidak akan terbantu dengan dokumentasi ini.

Pemalam mesti melaksanakan antara muka iPlugin. Kami mengesyorkan agar kelas pemalam anda diperluas daripada kelas PluginBase.

Pemalam dibangunkan berdasarkan mekanisme peristiwa.

Tetapan pemalam

Dengan memperluas kelas tersebut, anda mendapat manfaat daripada fungsi biasa yang diperlukan oleh pemalam yang telah kami laksanakan untuk anda. Salah satu fungsi tersebut ialah pelaksanaan fungsi getPluginSettings. Fungsi ini mesti mengembalikan tatasusunan yang menerangkan pilihan konfigurasi untuk pengguna.

Pemalam contoh hanya mendedahkan 1 tetapan yang boleh dikonfigurasi, iaitu mesej yang akan dipaparkan.

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

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

Tatasusunan ini mengandungi nama bagi setiap tetapan sebagai kunci. Nilainya ialah tatasusunan yang mengandungi metadata yang diperlukan.

Jenis yang disokong ialah:

• logo
• int (nombor integer)
• string (abjad angka)
• text
• html
• relevance
• info
• password
• date
• select

Selain type, beberapa kunci lain turut tersedia:

• label, menentukan label
• default, menentukan nilai yang dipaparkan jika tiada nilai ditetapkan (hanya untuk tetapan global, bukan untuk tetapan tinjauan)
• current, menentukan nilai semasa.
• readOnly : memaparkan tetapan sebagai baca sahaja
• htmlOptions, htmlOptions bagi bahagian input ( lihat manual Yii [[1]])
• pluginOptions, untuk sesetengah tetapan (html atau select) : menetapkan pilihan widget
• labelOptions : htmlOptions bagi label
• controlOptions : htmlOptions bagi pembungkus label dan input
• localized : jika true, nilai disimpan mengikut bahasa. Input dihantar sebagai name[language] dan current mestilah tatasusunan yang diindeks mengikut kod bahasa.
• language : digunakan bersama localized. Sama ada satu kod bahasa, atau ^{(New in X.Y.Z )} tatasusunan kod bahasa untuk memaparkan satu input bagi setiap bahasa (lihat Tetapan pemalam setempat)

Anda boleh mendapati contoh pemalam yang menggunakan semua tetapan sebenar di exampleSettings

Membaca dan menulis tetapan pemalam

Anda boleh membaca dan menulis tetapan pemalam terus daripada kod pemalam anda.

Contoh:

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

Anda boleh mendapatkan nilai lalai jika tetapan tersebut kebetulan bernilai null:

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

Tetapan pemalam khusus tinjauan

Dua peristiwa digunakan untuk mencipta tetapan pemalam khusus tinjauan:

• newSurveySettings
• beforeSurveySettings

Contoh untuk menyahaktifkan pemalam bagi tinjauan tertentu:

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

Tetapan pemalam setempat ^{(New in 7.4 )}

Untuk memaparkan satu input bagi setiap bahasa tinjauan untuk tetapan yang sama, tetapkan localized kepada true dan berikan senarai bahasa dalam language. Nama bahasa akan ditambah pada label setiap 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(),
                        // Tatasusunan diindeks mengikut kod bahasa, cth. ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

Nilai yang dihantar ialah tatasusunan yang diindeks mengikut kod bahasa, jadi fungsi newSurveySettings daripada contoh di atas menyimpannya tanpa sebarang perubahan. Untuk membaca teks bagi bahasa semasa:

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

Peristiwa

Pemalam melanggan peristiwa dan boleh berinteraksi dengan LimeSurvey apabila peristiwa tersebut dicetuskan. Untuk senarai peristiwa yang tersedia pada masa ini, rujuk Peristiwa pemalam.

API

Pemalam hanya boleh memperluas LimeSurvey melalui API "awam"nya. Ini bermakna menggunakan kelas yang terdapat dalam kod sumber secara terus ialah amalan yang kurang baik. Walaupun kami tidak boleh menghalang anda, anda berisiko mempunyai pemalam yang rosak pada setiap kemas kini kecil yang kami lakukan.

Sebanyak mungkin, berinteraksilah dengan LimeSurvey hanya melalui kaedah yang diterangkan di sini. Perkara yang sama berlaku untuk peristiwa.

Objek API boleh diakses melalui $this->api apabila memperluas daripada PluginBase. Jika tidak, anda boleh mendapatkannya daripada instans PluginManager yang dihantar kepada konstruktor pemalam anda.

Fungsi baharu boleh ditambah pada objek API atas permintaan.

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

Pelanjutan borang ^{(New in 6 )}

Pengenalan

Sistem pelanjutan borang ialah cara yang lebih umum untuk memperluas borang dalam teras LimeSurvey tanpa menambah peristiwa baharu bagi setiap borang.

Ia terdiri daripada komponen berikut:

• Modul global bernama FormExtensionService
• Pustaka kelas input yang boleh ditambah oleh pemalam pada permulaan modul di atas
• Satu widget, bersama perender tersuai, yang digunakan dalam fail paparan LimeSurvey

Setiap borang dikenal pasti dengan rentetan kedudukan, seperti <form name><dot><tab name>. Contoh: globalsettings.general atau globalsettings.security.

Tujuan sistem berasaskan kelas tanpa HTML ialah untuk membebaskan pengarang pemalam daripada kerja mengemas kini HTML apabila HTML teras berubah. Namun, pengarang boleh menggunakan jenis RawHtmlInput jika perlu.

Satu perkara yang tidak boleh dilakukan dalam sistem ini ialah menambah tab borang baharu.

Contoh

Untuk menambah input baharu pada borang daripada pemalam, gunakan kod berikut daripada fungsi init() anda:

TODO: Simpan dalam tetapan pemalam dan bukannya 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');
        }
    ])
);

Pengesahan

Pengesahan input dilakukan dalam fungsi save (lihat contoh di atas). Jika nilai yang dihantar tidak sah, lemparkan SaveFailedException, dan mesej kilat amaran akan dipaparkan kepada pengguna.

Borang yang disokong

Borang berikut boleh dilanjutkan:

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

Jika anda ingin menambah sokongan untuk borang teras yang lain, anda perlu menggunakan perubahan berikut dalam pull-request:

Dalam fail paparan, tambahkan:

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

Anda mungkin perlu mencipta kelas renderer baharu berdasarkan DefaultBaseRenderer, jika HTML borang berbeza daripada borang lain. Anda juga mungkin perlu memperluas kelas renderer lalai dengan jenis input yang belum ditambah.

Perubahan kedua yang perlu anda lakukan ialah menambah panggilan kepada kelas perkhidmatan sambungan borang dalam tindakan pengawal yang menyimpan borang tersebut:

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

Itu sahaja!

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

Penyetempatan ^{(New in 3 )}

Pemalam boleh menambah fail locale mereka sendiri. Format fail yang digunakan ialah .mo, sama seperti terjemahan teras. Fail tersebut mesti disimpan dalam

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

di mana "<language>" ialah perkataan dua huruf seperti "de" atau "fr".

Untuk menggunakan fail locale tertentu, gunakan fungsi pemalam gT:

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

Jika rentetan yang diberikan tidak ditemui dalam fail locale khusus pemalam, fungsi ini akan mencarinya dalam fail locale teras. Jadi, selamat untuk menggunakan rentetan seperti "Batal":

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

Jika anda menggunakan paparan bersama pemalam anda, anda hendaklah menggunakan

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

untuk melakukan terjemahan khusus pemalam dalam paparan anda.

Anda boleh menggunakan fail limesurvey.pot sebagai contoh rupa fail pot. Fail ini diimport ke dalam alat terjemahan anda.

Alat

Satu alat sumber terbuka untuk mengedit fail po dan mo ialah Poedit.

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

Pengelogan ^{(New in 3 )}

Jika anda ingin merekodkan sesuatu daripada pemalam anda, cukup tulis

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

Tahap pengelogan lalai ialah trace, tetapi anda boleh memberikan tahap log lain sebagai argumen kedua pilihan:

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

Fail log boleh ditemui dalam folder

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

Nama pemalam anda digunakan secara automatik sebagai kategori. Cara yang baik untuk melihat ralat daripada pemalam anda sahaja ialah menggunakan grep (pada Linux):

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

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

Pengelogan penyahaktifan pemalam disebabkan ralat ^{(New in 6.13.3 )}

Sejak LimeSurvey versi 5: pemalam boleh dinyahaktifkan secara automatik sekiranya berlaku ralat PHP.

E-mel dihantar secara automatik kepada pentadbir LimeSurvey. Anda boleh menggunakan sistem log untuk menjana amaran kepada pentadbir pelayan yang lain.

Contohnya: untuk menghantar mesej amaran

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

Maklumat lanjut tentang mengkonfigurasi pengelogan dalam Yii 1: Tetapan pengelogan.

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

Kemas kini sambungan ^{(New in 4 )}

Sejak LimeSurvey versi 4.0.0, terdapat sistem untuk mengendalikan kemas kini pemalam dan sambungan lain. Untuk menggunakan sistem ini, fail config.xml sambungan anda perlu menyertakan konfigurasi pengemas kini.

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

(Teg sumber di atas menunjuk kepada API REST LimeStore, yang akan digunakan untuk semua sambungan yang terdapat dalam LimeStore kami.)

Keterangan teg updater

Teg	Keterangan
stable	"1" jika sumber ini hanya memberikan nombor versi stabil; "0" jika sumber ini turut menyediakan versi tidak stabil, seperti 0.3.3-beta.
type	Buat masa ini, hanya jenis rest disokong. Jenis updater baharu (penyemak versi) mudah ditambah, seperti git, wget dan sebagainya.
source	URL untuk mendapatkan versi baharu.
manualUpdateUrl	URL yang boleh dilawati oleh pengguna untuk mengemas kini sambungan kepada versi terkini.
automaticUpdateUrl	TODO

Jika anda tidak mahu menyediakan updater, anda perlu meletakkan teks berikut dalam fail XML konfigurasi anda:

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

Dengan cara ini, anda memaklumkan kepada sistem bahawa anda sengaja menyahdayakan sistem kemas kini, dan bukan sekadar terlupa menambahnya.

Pemalam baharu UpdateCheck - dipasang dan diaktifkan secara lalai - menyemak kemas kini baharu untuk semua sambungan yang dipasang apabila pentadbir super log masuk, secara tak segerak, maksimum sekali setiap 24 jam. Jika sebarang versi baharu ditemui, satu pemberitahuan dihantar.

Jika Kemas kini keselamatan baharu ditemui, pemberitahuan akan dibuka secara automatik dan digayakan dalam kelas "danger".

Anda boleh menyemak kemas kini secara manual dengan pergi ke paparan pengurus pemalam dan klik "Check updates". Perhatikan bahawa butang ini hanya kelihatan jika pemalam UpdateCheck diaktifkan.

Di sebalik tabir

Bahagian ini memberikan gambaran ringkas tentang pelaksanaan updater sambungan.

Updater sambungan merupakan sebahagian daripada pustaka ExtensionInstaller. Di bawah ialah gambar rajah UML bagi kelas yang berkaitan dengan proses updater.

Aliran program apabila Yii bermula:

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

Aliran program apabila pemalam UpdaterCheck dijalankan:

 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

Kaedah checkAll dalam pemalam UpdateCheck memberikan contoh cara membuat pertanyaan kepada semua sambungan untuk versi baharu.

Menambah pengambil versi baharu

Untuk menambah pengambil versi tersuai yang baharu, jalankan kod ini semasa permulaan Yii:

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

Sudah tentu, kelas MyNewVersionFetcher mesti mewarisi VersionFetcher.

Untuk menggunakan pengambil versi baharu anda, konfigurasikan teg type dalam XML updater supaya menggunakan myNewVersionFetcherType (dan bukannya contohnya rest).

Menambah updater sambungan baharu

Untuk menambah updater sambungan tersuai yang baharu, jalankan kod ini semasa permulaan Yii:

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

Kelas MyNewExtensionUpdater mesti mewarisi ExtensionUpdater.

Teg type peringkat atas dalam config.xml ('plugin', 'theme', ...) akan mengawal updater sambungan yang digunakan untuk sambungan ini. Sistem ini belum boleh disesuaikan sepenuhnya, kerana anda juga perlu menambah ExtensionInstaller tersuai, item menu dan sebagainya. Namun secara teori, dan mungkin pada masa hadapan, jenis sambungan baharu boleh ditambah dengan cara ini.

Pemasang sambungan

Pustaka pemasang sambungan terdiri daripada dua kelas abstrak:

• ExtensionInstaller
• FileFetcher

ExtensionInstaller diwarisi untuk setiap jenis sambungan, seperti PluginInstaller, QuestionThemeInstaller dan sebagainya.

FileFetcher diwarisi untuk setiap cara berbeza untuk mendapatkan fail. Buat masa ini, hanya fail zip yang dimuat naik disokong, tetapi pada masa hadapan, mungkin terdapat pengambil Github atau LimeStore juga.

Tutorial

Tutorial langkah demi langkah ini menunjukkan cara mencipta pemalam yang menghantar permintaan post pada setiap penyerahan jawapan tinjauan. Tutorial ini menunjukkan cara mencipta dan menyimpan tetapan global dan tetapan bagi setiap tinjauan, cara mendaftarkan peristiwa dan banyak lagi.