Plugin - nâng cao

This page is a translated version of the page Plugins - advanced and the translation is 92% complete.

Outdated translations are marked like this.

Tổng quan

Bắt đầu từ LimeSurvey 2.05, LimeSurvey sẽ chính thức hỗ trợ plugin. Một số plugin sẽ được nhóm LimeSurvey hỗ trợ và sẽ đi vào lõi. Một số sẽ được hỗ trợ bởi những người khác ngoài nhóm LimeSurvey. Để giúp tìm thấy chúng, hãy xem Các plugin có sẵn của bên thứ ba và thêm plugin của riêng bạn vào đó!

Plugin cho phép người dùng tùy chỉnh chức năng cài đặt của họ trong khi vẫn có thể hưởng lợi từ các bản cập nhật phần mềm thường xuyên.

Tài liệu này dành cho các nhà phát triển đang mở rộng LimeSurvey cho mục đích sử dụng của riêng họ hoặc cho khách hàng của họ; người dùng cuối sẽ không được tài liệu này trợ giúp.

Các plugin phải triển khai giao diện iPlugin. Chúng tôi khuyên bạn nên mở rộng lớp plugin của mình từ lớp PluginBase.

Các plugin được phát triển dựa trên cơ chế event.

Cài đặt plugin

Bằng cách mở rộng, bạn sẽ được hưởng lợi từ chức năng chung được yêu cầu bởi các plugin mà chúng tôi đã triển khai cho bạn. Một trong những chức năng này là việc triển khai chức năng getPluginSettings. Hàm này phải trả về một mảng mô tả các tùy chọn cấu hình cho người dùng.

Plugin ví dụ chỉ hiển thị 1 cài đặt có thể định cấu hình, thông báo sẽ hiển thị.

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

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

Mảng chứa tên cho mỗi cài đặt làm khóa. Các giá trị là các mảng chứa dữ liệu meta cần thiết.

Các loại được hỗ trợ là:

logo
int (số nguyên)
chuỗi (chữ và số)
văn bản
html
mức độ liên quan
thông tin
mật khẩu
ngày
chọn

Ngoài ra còn có một số phím gõ khác:

nhãn, xác định nhãn
mặc định, xác định giá trị để hiển thị nếu không có giá trị nào được chỉ định (chỉ dành cho cài đặt chung, không dành cho cài đặt khảo sát)
hiện tại, xác định giá trị hiện tại.
readOnly : đã hiển thị các cài đặt dưới dạng chỉ đọc
htmlOptions, htmlOptions của phần đầu vào ( xem hướng dẫn sử dụng Yii [[1]])
pluginOptions, để biết một số cài đặt (html hoặc select): đặt tùy chọn tiện ích
labelOptions : htmlOptions của nhãn
controlOptions : htmlOptions của trình bao bọc nhãn và đầu vào

Bạn có thể tìm thấy ví dụ về plugin sử dụng tất cả cài đặt thực tế tại exampleSettings

Đọc và ghi cài đặt plugin

Có thể đọc và ghi cài đặt plugin trực tiếp từ mã plugin của bạn.

Ví dụ:

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

Bạn có thể nhận giá trị mặc định nếu cài đặt là null:

$mySetting = $this->get('mySetting', null, null, 10); // 10 là mặc định

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

Sự kiện

Các plugin đăng ký sự kiện và có thể tương tác với LimeSurvey khi sự kiện được kích hoạt. Để biết danh sách các sự kiện hiện có, hãy kiểm tra Sự kiện plugin.

API

Các plugin chỉ nên mở rộng LimeSurvey thông qua API "công khai" của nó. Điều này có nghĩa là việc sử dụng trực tiếp các lớp có trong mã nguồn là một cách làm không tốt. Mặc dù chúng tôi không thể buộc bạn không làm vậy nhưng bạn có nguy cơ gặp phải plugin bị hỏng sau mỗi lần cập nhật nhỏ mà chúng tôi thực hiện.

Chỉ tương tác với LimeSurvey càng nhiều càng tốt thông qua các phương pháp được mô tả tại đây. Tương tự như đối với các sự kiện

Đối tượng API có sẵn thông qua $this->api khi mở rộng từ PluginBase, nếu không, bạn có thể lấy nó từ phiên bản PluginManager được chuyển đến hàm tạo của plugin của bạn.

Các chức năng mới có thể được thêm vào đối tượng API theo yêu cầu.

Tiện ích mở rộng biểu mẫu^{(New in 6 )}

Giới thiệu

Hệ thống tiện ích mở rộng biểu mẫu là một cách tổng quát hơn để mở rộng biểu mẫu trong LimeSurvey cốt lõi mà không cần thêm sự kiện mới cho mỗi biểu mẫu.

Nó bao gồm các thành phần sau:

Một mô-đun toàn cầu có tên FormExtensionService
Một thư viện các lớp đầu vào mà các plugin có thể thêm vào quá trình khởi tạo mô-đun ở trên
Một widget, cùng với trình kết xuất tùy chỉnh, được sử dụng trong các tệp xem LimeSurvey

Mỗi dạng được xác định bằng một chuỗi vị trí, như<form name><dot><tab name> . Ví dụ: globalsettings.general hoặc globalsettings.security .

Mục đích đằng sau một hệ thống dựa trên lớp không có HTML là giải phóng các tác giả plugin của tác phẩm để cập nhật HTML khi HTML cốt lõi thay đổi. Tuy nhiên, tác giả có thể sử dụng loại RawHtmlInput nếu cần.

Một điều bạn không thể làm trong hệ thống này là thêm tab biểu mẫu mới.

Ví dụ

Để thêm đầu vào mới vào biểu mẫu từ plugin, hãy sử dụng đoạn mã sau từ init() của bạn:

VIỆC CẦN LÀM: Lưu trong cài đặt plugin thay vì lưu chung

// Ở đầu tệp
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Bên trong init()
Yii::app()->formExtensionService->add(
 'globalsettings.general',
 new TextInput([
 'name' => 'myinput', 
 'label' => 'Label',
 'disabled' => true,
 'tooltip' => 'Moo moo moo',
 'help' => 'Một số văn bản trợ giúp', 
 'save' => function($request, $connection) {
 $value = $request->getPost('myinput');
 if ($value === 'một số giá trị không hợp lệ') {
 Throw new SaveFailedException("Không thể lưu thông tin nhập tùy chỉnh 'myinput'");
 } else {
 SettingGlobal::setSetting('myinput', $value);
 }
 } ,
 'load' => function () {
 return getGlobalSetting('myinput');
 }
 ])
);

Xác thực

Việc xác thực đầu vào được thực hiện trong chức năng save (xem ví dụ ở trên). Nếu giá trị được đăng không hợp lệ, hãy ném SaveFailedException và một thông báo flash cảnh báo sẽ được hiển thị cho người dùng.

Các hình thức được hỗ trợ

Các hình thức sau đây có thể được mở rộng:

Globalsettings.general^{(New in 6.0.0 )}

Nếu bạn muốn thêm hỗ trợ cho một biểu mẫu cốt lõi khác, bạn cần áp dụng thay đổi sau trong yêu cầu kéo:

Trong tệp xem, thêm:

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

Bạn có thể phải tạo một lớp trình kết xuất mới dựa trên DefaultBaseRenderer , nếu HTML biểu mẫu khác với các biểu mẫu khác. Bạn cũng có thể cần mở rộng lớp trình kết xuất mặc định với các loại đầu vào chưa được thêm vào.

Thay đổi thứ hai bạn phải thực hiện là thêm lệnh gọi đến lớp dịch vụ tiện ích mở rộng biểu mẫu trong hành động của bộ điều khiển lưu biểu mẫu:

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

Đó là nó!

Bản địa hóa ^{(New in 3 )}

Các plugin có thể thêm tệp ngôn ngữ của riêng chúng. Định dạng tệp được sử dụng là .mo, giống như các bản dịch cốt lõi. Các tập tin phải được lưu trữ trong

<plugin root folder>/địa phương/<language> /<language> .mo

Ở đâu "<language> " là một từ có hai chữ cái như "de" hoặc "fr".

Để sử dụng tệp ngôn ngữ cụ thể, hãy sử dụng chức năng plugin gT:

$this->gT("Văn bản plugin cần được dịch");

Nếu không thể tìm thấy chuỗi đã cho trong tệp ngôn ngữ cụ thể của plugin, hàm sẽ tìm trong tệp ngôn ngữ cốt lõi. Vì vậy, an toàn khi sử dụng các chuỗi như "Hủy":

$this->gT("Hủy"); // Sẽ được dịch ngay cả khi "Hủy" không có trong tệp ngôn ngữ plugin

Nếu bạn đang sử dụng chế độ xem cùng với plugin của mình, bạn nên sử dụng

$plugin->gT("Dịch tôi");

để thực hiện bản dịch cụ thể của plugin trong chế độ xem của bạn.

Bạn có thể sử dụng tệp Limesurvey.pot làm ví dụ về hình thức của tệp pot. Điều này được nhập vào công cụ dịch thuật của bạn.

Công cụ

Một công cụ nguồn mở để chỉnh sửa các tệp po- và mo- là Poedit.

Đang ghi nhật ký ^{(New in 3 )}

Nếu bạn muốn đăng nhập nội dung nào đó từ plugin của mình, chỉ cần viết

$this->log("Tin nhắn của bạn");

Mức ghi nhật ký mặc định là theo dõi, nhưng bạn có thể đưa ra một mức nhật ký khác làm đối số thứ hai tùy chọn:

$this->log("Đã xảy ra lỗi!", CLogger::LEVEL_ERROR);

Tệp nhật ký có thể được tìm thấy trong thư mục

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

Tên plugin của bạn sẽ tự động được sử dụng làm danh mục. Một cách hay để chỉ xem các lỗi từ plugin của bạn là sử dụng grep (trên Linux):

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

Thông tin thêm về cách định cấu hình ghi nhật ký trong Yii 1: Optional_settings#Logging_settings.

Cập nhật tiện ích mở rộng ^{(New in 4 )}

Kể từ phiên bản LimeSurvey 4.0.0, đã có sẵn một hệ thống để xử lý các bản cập nhật plugin và tiện ích mở rộng khác. Để sử dụng hệ thống này, tệp config.xml tiện ích mở rộng của bạn cần bao gồm cấu hình trình cập nhật.

<updaters> 
<updater> 
<stable> 1</stable> 
<type> nghỉ ngơi</type> 
<source> https://comfortupdate.limesurvey.org/index.php?r=limestorerest</source> 
<manualUpdateUrl> https://somedownloadlink.com/maybegithub</manualUpdateUrl> 
</updater> 
</updaters>

(Thẻ nguồn ở trên trỏ tới API LimeStore REST, sẽ được sử dụng cho tất cả các tiện ích mở rộng có sẵn trong LimeStore của chúng tôi.)

Mô tả thẻ trình cập nhật
Gắn thẻ	Mô tả
ổn định	"1" nếu nguồn này chỉ cung cấp cho bạn số phiên bản ổn định; "0" nếu nguồn cũng sẽ cung cấp các phiên bản không ổn định, như `0.3.3-beta` .
gõ	Hiện tại, chỉ hỗ trợ loại phần `rest` . Thật dễ dàng để thêm các loại trình cập nhật mới (trình kiểm tra phiên bản), như git, wget, v.v.
nguồn	URL để tìm nạp phiên bản mới từ.
hướng dẫn sử dụngUpdateUrl	URL mà người dùng có thể truy cập để cập nhật phiên bản mới nhất của tiện ích mở rộng.
tự độngUpdateUrl	TODO

Nếu bạn không muốn cung cấp trình cập nhật, bạn nên đặt văn bản sau vào tệp XML cấu hình của mình:

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

Bằng cách này, bạn cho hệ thống biết rằng bạn đã cố tình vô hiệu hóa hệ thống cập nhật và không quên thêm nó.

Plugin mới UpdateCheck - được cài đặt và kích hoạt theo mặc định - kiểm tra các bản cập nhật mới cho tất cả tiện ích mở rộng đã cài đặt khi quản trị viên cấp cao đăng nhập, không đồng bộ, tối đa một lần sau mỗi 24 giờ. Nếu tìm thấy bất kỳ phiên bản mới nào, một thông báo sẽ được đưa ra.

Nếu tìm thấy bản cập nhật bảo mật mới, thông báo sẽ tự động mở và được xếp vào loại "nguy hiểm".

Bạn có thể kiểm tra cập nhật theo cách thủ công bằng cách đi tới chế độ xem trình quản lý plugin và nhấp vào "Kiểm tra cập nhật". Lưu ý rằng nút này chỉ hiển thị nếu plugin UpdateCheck được kích hoạt.

Dưới mui xe

Phần này cung cấp thông tin tổng quan ngắn gọn về việc triển khai trình cập nhật tiện ích mở rộng.

Trình cập nhật tiện ích mở rộng là một phần của thư viện ExtensionInstaller. Dưới đây là sơ đồ UML cho các lớp liên quan đến quá trình cập nhật.

Luồng chương trình khi Yii khởi động:

 Yii bắt đầu
 VersionFetcherServiceLocator->init()
 Thêm trình tìm nạp phiên bản REST
 ExtensionUpdaterServiceLocator->init()
 Thêm PluginUpdater
 VIỆC CẦN LÀM: Thêm trình cập nhật cho từng loại tiện ích mở rộng (chủ đề, mẫu câu hỏi, ...)

Luồng chương trình khi chạy plugin UpdaterCheck:

 Nhận tất cả các bản cập nhật từ ExtensionUpdaterServiceLocator
 Lặp lại từng trình cập nhật
 Đối với mỗi trình cập nhật, lặp qua các trình tìm nạp phiên bản được định cấu hình bởi<updater> XML
 Đối với mỗi trình tìm nạp phiên bản, hãy liên hệ với nguồn từ xa và nhận thông tin phiên bản
 Soạn tất cả các phiên bản thành một thông báo

Phương thức checkAll trong plugin UpdateCheck cung cấp ví dụ về cách truy vấn tất cả tiện ích mở rộng cho phiên bản mới .

Thêm trình tìm nạp phiên bản mới

Để thêm trình tìm nạp phiên bản tùy chỉnh mới, hãy chạy nó trong quá trình khởi tạo Yii:

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

Tất nhiên, lớp MyNewVersionFetcher phải phân lớp VersionFetcher .

Để sử dụng trình tìm nạp phiên bản mới của bạn, hãy định cấu hình thẻ type trong XML của trình cập nhật để sử dụng

myNewVersionFetcherType (thay vì ví dụ như rest ).

Thêm trình cập nhật tiện ích mở rộng mới

Để thêm trình cập nhật tiện ích mở rộng tùy chỉnh mới, hãy chạy trình này trong quá trình khởi tạo Yii:

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

Lớp MyNewExtensionUpdater phải phân lớp ExtensionUpdater .

Thẻ type hàng đầu trong config.xml ('plugin', 'theme', ...) sẽ kiểm soát trình cập nhật tiện ích mở rộng nào được sử dụng cho tiện ích mở rộng này. Hệ thống này chưa thể tùy chỉnh hoàn toàn vì bạn cũng cần thêm ExtensionInstaller tùy chỉnh, các mục menu, v.v. Nhưng về mặt lý thuyết và có thể trong tương lai, bạn có thể thêm một loại tiện ích mở rộng mới theo cách này.

Trình cài đặt tiện ích mở rộng

Thư viện trình cài đặt tiện ích mở rộng bao gồm hai lớp trừu tượng:

ExtensionInstaller
FileFetcher

ExtensionInstaller được phân lớp cho từng loại tiện ích mở rộng, như PluginInstaller, AskThemeInstaller, v.v.

FileFetcher được phân lớp cho từng cách tìm nạp tệp khác nhau. Hiện tại, chỉ hỗ trợ các tệp zip đã tải lên, nhưng trong tương lai, có thể có trình tìm nạp Github hoặc LimeStore.

Tập tin: Extensioninstalleruml.png

Các plugin đặc biệt

Các plugin có sẵn

Hướng dẫn

Hướng dẫn từng bước này chỉ ra cách tạo plugin gửi yêu cầu đăng bài trên mỗi phản hồi khảo sát nộp hồ sơ. Hướng dẫn này chỉ cho bạn cách tạo và lưu cài đặt chung và cài đặt cho mỗi khảo sát, cách đăng ký sự kiện, v.v.

Danh mục:Phát triển Danh mục:Plugin

Plugin - nâng cao

From LimeSurvey Manual

Contents

Tổng quan

Cài đặt plugin

Đọc và ghi cài đặt plugin

Survey specific plugin settings

Sự kiện

API

Tiện ích mở rộng biểu mẫu^{(New in 6 )}

Giới thiệu

Ví dụ

Xác thực

Các hình thức được hỗ trợ

Bản địa hóa ^{(New in 3 )}

Công cụ

Đang ghi nhật ký ^{(New in 3 )}

Cập nhật tiện ích mở rộng ^{(New in 4 )}

Dưới mui xe

Thêm trình tìm nạp phiên bản mới

Thêm trình cập nhật tiện ích mở rộng mới

Trình cài đặt tiện ích mở rộng

Các plugin đặc biệt

Các plugin có sẵn

Hướng dẫn

Plugin - nâng cao

From LimeSurvey Manual

Tổng quan

Cài đặt plugin

Đọc và ghi cài đặt plugin

Survey specific plugin settings

Sự kiện

API

Tiện ích mở rộng biểu mẫu (New in 6 )

Giới thiệu

Ví dụ

Xác thực

Các hình thức được hỗ trợ

Bản địa hóa (New in 3 )

Công cụ

Đang ghi nhật ký (New in 3 )

Cập nhật tiện ích mở rộng (New in 4 )

Dưới mui xe

Thêm trình tìm nạp phiên bản mới

Thêm trình cập nhật tiện ích mở rộng mới

Trình cài đặt tiện ích mở rộng

Các plugin đặc biệt

Các plugin có sẵn

Hướng dẫn

Tiện ích mở rộng biểu mẫu^{(New in 6 )}

Bản địa hóa ^{(New in 3 )}

Đang ghi nhật ký ^{(New in 3 )}

Cập nhật tiện ích mở rộng ^{(New in 4 )}