プラグイン - 上級者向け
From LimeSurvey Manual
概要
LimeSurvey2.05以降、LimeSurveyは正式にプラグインをサポートしています。一部のプラグインはLimeSurveyチームによってサポートされ、コアとして組み入れられています。LimeSurveyチーム以外の人たちによってサポートされるものもあります。Available third party pluginsをチェックしてください。あなた自身のプラグインも追加してください！
プラグインを使用すると、通常のソフトウェア更新の恩恵を受けながら、LimeSurveyの機能をカスタマイズすることができます。
このドキュメントは、LimeSurveyを独自に、またはクライアント用に拡張している開発者を対象としています。エンドユーザーはこのドキュメントを読む必要はありません。
プラグインはiPluginインターフェースを実装する必要があります。PluginBaseクラスからプラグインクラスを拡張することをお勧めします。
プラグインは、イベントメカニズムを中心に開発されています。
プラグイン設定
拡張することで、プラグインで必要とされる実装済の共通機能を利用することができます。その1つとして、getPluginSettings関数の実装があります。この関数は、ユーザーの設定オプションを記述する配列を返すものです。
サンプルプラグインでは設定可能な設定が1つだけ表示されます。
protected $settings = array(
'logo' => array(
'type' => 'logo',
'path' => 'assets/logo.png'
),
'message' => array(
'type' => 'string',
'label' => 'Message'
)
);
配列には、各設定の名前がキーとして含まれています。値は、必要なメタデータを含む配列です。
サポートされるタイプは次のとおりです。
- ロゴ
- int（整数）
- 文字列（英数字）
- テキスト
- html
- 選択
- 情報
- パスワード
- 日付
- 関連
タイプに加えて、他の多くのキーが利用可能です。
- label : を定義します
- default : 値が指定されていない場合に表示する値を定義します（全体設定のみ、アンケート設定ではない）。
- current : の値を定義します。
- readOnly : 設定が読み取り専用であることを指定します。
- htmlOptions : 入力部分のhtmlOptions（Yiiのマニュアルを参照してください。[[1]]）
- pluginOptions（htmlやselect向けの設定） : ウィジェットオプションを設定します。
- labelOptions : ラベルのhtmlOptions。
- controlOptions : ラベルと入力のラッパーのhtmlOptions。
exampleSettingsの実際の設定をすべて使用しているプラグインの例があります。
プラグインの設定を読み書きする
プラグインコードから直接プラグイン設定を読み書きすることができます。
例:
$mySetting = $this->get('mySetting');
$this->set('mySetting', $mySetting + 1);
設定がnullの場合、既定値を取得できます。
$mySetting = $this->get('mySetting', null, null, 10); // 既定値は10
アンケート固有のプラグイン設定
アンケート固有のプラグイン設定を作成するには次の２つのイベントを使用します。
- 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);
}
イベント
プラグインはイベント発生を待機し、イベントが発生するとLimeSurveyと対話できます。現在利用可能なイベントのリストについては、Plugin eventsを確認してください。
API
プラグインは、"公開された"APIを介してLimeSurveyを拡張するだけにすべきです。つまり、ソースコードにあるクラスを直接使用するのはよくないやり方です。強制はできませんが、私たちが行うすべてのマイナーアップデートによってプラグインが壊れる危険性があります。
LimeSurveyとは、可能な限りここで説明する方法でのみ対話してください。イベントについても同じです。
APIオブジェクトはPluginBaseから拡張するときに$this->api経由で使用できます。または、プラグインのコンストラクタに渡されるPluginManagerインスタンスから取得できます。
新しい機能は、要求に応じてAPIオブジェクトに追加することができます。
<span id="Form_extension (New in 6 )">
フォーム拡張 (6 から追加)
はじめに
フォーム拡張システムは、フォームごとに新しいイベントを追加せずにコアLimeSurveyでフォームを拡張する、より一般的な方法です。
次のコンポーネントから構成されます。
- FormExtensionServiceというグローバルモジュール
- 上記のモジュールの初期化にプラグインを追加できるinput classesライブラリー
- カスタムレンダラーとともに、LimeSurveyのビューファイルで使用されるwidget
各フォームは、<form name><dot><tab name>という形式のposition stringによって識別されます。例：globalsettings.generalやglobalsettings.security
HTMLのないクラスベースのシステムの背後にあるポイントは、プラグイン作者がコアHTMLが変更された場合でもHTMLを更新する必要がないことです。それでも、作者は必要に応じて RawHtmlInput 型を使用できます。
このシステムでは、新しいフォームタブの追加はできません。
例
プラグインからフォームに新しい入力を追加するには、init()関数で以下のコードを使用します。
TODO：グローバルではなくプラグイン設定に保存。
// ファイルの先頭
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;
// 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が返り、警告のフラッシュメッセージがユーザーに提示されます。
対応フォーム
以下のフォームを拡張できます。
- globalsettings.general (6.0.0 から追加)
別のコアフォームのサポートを追加する場合は、pull-requestで次の変更を適用する必要があります。
ビューファイルに以下を追加します。
<?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に基づく新しいレンダラークラスを作成しなければならない場合があります。入力タイプが追加されていない既定のレンダラークラスを拡張しなければならない場合もあります。
次に、フォームを保存するコントローラーアクションにフォーム拡張サービスクラスの呼び出しを追加する変更を行います。
$request = App()->request;
Yii::app()->formExtensionService->applySave('globalsettings', $request);
以上。
<span id="Localization_ (New in 3 )">
ローカリゼーション (3 から追加)
プラグインで独自のロケールファイルを追加することが可能です。使用されるファイル形式は、コア翻訳と同じ.moです。ファイルは次の場所に保存する必要があります。
<plugin root folder>/locale/<language>/<language>.mo
"<language>"は"de"や"fr"のような二文字の文字列です。
特定のロケールファイルを使用するには、プラグイン関数gTを使用します。
$this->gT("A plugin text that needs to be translated");
指定された文字列がプラグイン固有のロケールファイルに見あたらない場合、関数はコアロケールファイルを検索します。したがって、"キャンセル"のような文字列は安全に使用することができます。
$this->gT("Cancel"); // "Cancel"がプラグインロケールファイルにない場合でも翻訳されます
プラグインと一緒にビューを使用している場合は、
$plugin->gT("Translate me");
のようにし、ビューでプラグイン固有の翻訳を行います。
potファイルがどのように見えるか、その例としてlimesurvey.potファイルを使用できます。これは翻訳ツールにインポートされます。
ツール
po-ファイルやmo-ファイルを編集するツールの一つとして、Poeditがあります。
<span id="Logging_ (New in 3 )">
Logging (3 から追加)
プラグインから何かをログに記録する場合は、次のように記述します。
$this->log("ログに記録するメッセージ");
デフォルトのロギングレベルはtraceですが、オプションの第2引数として別のログレベルを指定することもできます。
$this->log("何か間違っている!", CLogger::LEVEL_ERROR);
ログファイルは次のフォルダにあります。
<limesurvey root folder>/tmp/runtime/plugin.log
プラグイン名は自動的にカテゴリーとして使用されます。当該のプラグインのエラーだけを表示するには、grep（Linuxの場合）を使用してください。
$ tail -f tmp/runtime/plugin.log | grep <プラグイン名>
Yii 1におけるロギング設定の詳細はロギング設定を参照してください。
<span id="Extension_updates_ (New in 4 )">
拡張機能の更新 (4 から追加)
LimeSurveyバージョン4.0.0以降、プラグインやその他の拡張機能の更新を処理するシステムが用意されています。このシステムを使用するには、拡張機能のconfig.xmlファイルにアップデーター設定を追加する必要があります。
<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>
（上のソースタグはLimeStore REST APIを指しています。これはLimeStoreのすべての拡張機能で使用されます）。
| タグ | 説明 |
|---|---|
| stable | "1"は、安定バージョンであることを示します。"0"は、安定バージョンでないことを示し、0.3.3-betaのようになります。
|
| type | 現時点では、restタイプだけサポートされています。gitやwgetのような新しいアップデータータイプ（バージョンチェッカー）を追加します。
|
| source | 新しいバージョンを読み込むURL。 |
| manualUpdateUrl | 最新の拡張機能にアップデートするためのユーザー向けURL |
| automaticUpdateUrl | TODO |
アップデータを提供したくない場合は、config XMLファイルに次のテキストを入力する必要があります。
<updaters disabled="disabled">
</updaters>
このようにして、更新システムに関する情報を追加し忘れたのではなく、更新システムを意図的に無効にしたことをシステムに伝えます。
新しいプラグイン UpdateCheck - デフォルトでインストールされ、アクティブ化されます。スーパー管理者がログインすると、インストールされたすべての拡張機能の新しいアップデートがないか非同期で24時間ごとにチェックします。新しいバージョンが見つかった場合は、通知がプッシュされます。
新しいセキュリティ更新プログラムが見つかった場合、通知は自動的に開き、"danger"クラスでスタイルされます。
プラグインマネージャービューに移動して"更新を確認"をクリックすると、手動で更新がないか確認できます。このボタンは、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をサブクラス化します。
新しいバージョンのフェッチャーを使用するには、アップデーターXMLのtypeタグをmyNewVersionFetcherTypeを使用するよう設定します（例えば、restの代わりに）。
新しい拡張機能アップデーターの追加
新しいカスタム拡張機能フェッチャーを追加するには、Yiiの初期化中にこれを実行します。
$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
'myNewExtensionUpdater',
function () {
return MyNewExtensionUpdater::createUpdaters();
}
);
MyNewExtensionUpdaterクラスはExtensionUpdaterをサブクラス化します。
config.xml（ 'plugin'、 'theme'、...）の最初のtypeタグは、この拡張機能で使用される拡張機能アップデーターを制御します。カスタムExtensionInstaller、メニュー項目などを追加する必要もあるので、このシステムはまだ完全にカスタマイズ可能ではありません。しかし、理論的、そして将来的には、このように新しいタイプの拡張を追加することは可能です。
拡張インストーラー
拡張インストーラライブラリーは、次の２つの抽象クラスで構成されています。
- ExtensionInstaller
- FileFetcher
ExtensionInstallerは、PluginInstaller、QuestionThemeInstallerなどの拡張タイプごとにサブクラス化されています。
FileFetcherは、ファイルをフェッチする方法ごとにサブクラス化されています。現在、アップロードされたzipファイルのみがサポートされていますが、将来的にはGithubまたはLimeStoreフェッチャーもサポートされる可能性があります。
特殊なプラグイン
利用可能なプラグイン
Tutorial
このステップバイステップのチュートリアルでは、アンケート回答を提出するごとにPOSTリクエストを送信するプラグインを作成する方法を示しています。このチュートリアルでは、全体およびアンケートごとの設定の作成／保存の方法、イベントの登録方法などが紹介されています。