プラグイン - 上級者向け
From LimeSurvey Manual
概要
LimeSurveyは、プラグインによって機能を追加できます。LimeSurveyには、すでに多くのコアプラグインが同梱されています。サードパーティ製プラグインの一覧もご確認ください。将来的には、あなた自身のプラグインもこの一覧に追加してみてはいかがでしょうか!
プラグインを使用すると、通常のソフトウェア更新の恩恵を受けながら、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。
- localized : trueの場合、値は言語ごとに保存されます。入力は
name[language]として送信され、currentは言語コードをキーとする配列である必要があります。 - language : localizedと併用します。単一の言語コード、または (New in X.Y.Z )言語コードの配列を指定すると、言語ごとに1つの入力が表示されます(ローカライズされたプラグイン設定を参照)。
exampleSettingsの実際の設定をすべて使用しているプラグインの例があります。
プラグインの設定を読み書きする
プラグインコードから直接プラグイン設定を読み書きすることができます。
例:
$mySetting = $this->get('mySetting');
$this->set('mySetting', $mySetting + 1);
設定がnullの場合、既定値を取得できます。
$mySetting = $this->get('mySetting', null, null, 10); // 既定値は10
アンケート固有のプラグイン設定
アンケート固有のプラグイン設定を作成するには次の2つのイベントを使用します。
- 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 )
同じ設定についてアンケート言語ごとに1つの入力を表示するには、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と対話できます。現在利用可能なイベントのリストについては、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 <プラグイン名>
<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におけるロギング設定の詳細はロギング設定を参照してください。
<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.3.3-betaのような不安定バージョンも提供する場合は「0」を指定します。
|
| 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、メニュー項目などを追加する必要もあるので、このシステムはまだ完全にカスタマイズ可能ではありません。しかし、理論的、そして将来的には、このように新しいタイプの拡張を追加することは可能です。
拡張インストーラー
拡張インストーラライブラリーは、次の2つの抽象クラスで構成されています。
- ExtensionInstaller
- FileFetcher
ExtensionInstallerは、PluginInstaller、QuestionThemeInstallerなどの拡張タイプごとにサブクラス化されています。
FileFetcherは、ファイルをフェッチする方法ごとにサブクラス化されています。現在、アップロードされたzipファイルのみがサポートされていますが、将来的にはGithubまたはLimeStoreフェッチャーもサポートされる可能性があります。
チュートリアル
こちらのステップバイステップのチュートリアルでは、アンケートの回答が送信されるたびにPOSTリクエストを送信するプラグインの作成方法を紹介しています。全体設定とアンケートごとの設定の作成と保存、イベントの登録方法などを解説しています。




