Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

Export in CSV format

{{DISPLAYTITLE:プラグイン - 上級者向け}}<languages />

==概要==

LimeSurvey2.05以降、LimeSurveyは正式にプラグインをサポートしています。一部のプラグインはLimeSurveyチームによってサポートされ、コアとして組み入れられています。LimeSurveyチーム以外の人たちによってサポートされるものもあります。[[Available third party plugins]]をチェックしてください。あなた自身のプラグインも追加してください！

プラグインを使用すると、通常のソフトウェア更新の恩恵を受けながら、LimeSurveyの機能をカスタマイズすることができます。

このドキュメントは、LimeSurveyを独自に、またはクライアント用に拡張している開発者を対象としています。エンドユーザーはこのドキュメントを読む必要はありません。

プラグインは[https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin]インターフェースを実装する必要があります。[https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase]クラスからプラグインクラスを拡張することをお勧めします。

<div class="mw-translate-fuzzy">
プラグインは、[https://manual.limesurvey.org/Plugin_events イベント]メカニズムを中心に開発されています。
</div>

== プラグイン設定 ==

拡張することで、プラグインで必要とされる実装済の共通機能を利用することができます。その1つとして、getPluginSettings関数の実装があります。この関数は、ユーザーの設定オプションを記述する配列を返すものです。

サンプルプラグインでは設定可能な設定が1つだけ表示されます。

<syntaxhighlight lang="php">
protected $settings = array(
    'logo' => array(
         'type' => 'logo',
         'path' => 'assets/logo.png'
     ),

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

配列には、各設定の名前がキーとして含まれています。値は、必要なメタデータを含む配列です。

サポートされるタイプは次のとおりです。

* ロゴ
* int（整数）
* 文字列（英数字）
* テキスト
* html
* 選択
* 情報
* パスワード
* 日付
* 関連

タイプに加えて、他の多くのキーが利用可能です。

* label : を定義します
* default : 値が指定されていない場合に表示する値を定義します（全体設定のみ、アンケート設定ではない）。
* current : の値を定義します。
* readOnly : 設定が読み取り専用であることを指定します。
* htmlOptions : 入力部分のhtmlOptions（Yiiのマニュアルを参照してください。[[https://www.yiiframework.com/doc/api/1.1/CHtml]]）
* pluginOptions（htmlやselect向けの設定） : ウィジェットオプションを設定します。
* labelOptions : ラベルのhtmlOptions。
* controlOptions : ラベルと入力のラッパーのhtmlOptions。

[https://gitlab.com/SondagesPro/SampleAndDemo/exampleSettings exampleSettings]の実際の設定をすべて使用しているプラグインの例があります。
=== プラグインの設定を読み書きする ===

プラグインコードから直接プラグイン設定を読み書きすることができます。

例:

<syntaxhighlight lang="php">
$mySetting = $this->get('mySetting');
$this->set('mySetting', $mySetting + 1);
</syntaxhighlight>

設定がnullの場合、既定値を取得できます。

<syntaxhighlight lang="php">
$mySetting = $this->get('mySetting', null, null, 10); // 既定値は10
</syntaxhighlight>

=== アンケート固有のプラグイン設定 ===

アンケート固有のプラグイン設定を作成するには次の２つのイベントを使用します。

* newSurveySettings
* beforeSurveySettings

特定のアンケートでプラグインを無効にする例：

<syntaxhighlight lang="php">
 
 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);
 }
</syntaxhighlight>

== イベント ==

プラグインはイベント発生を待機し、イベントが発生するとLimeSurveyと対話できます。現在利用可能なイベントのリストについては、[[Plugin events]]を確認してください。

== API ==

プラグインは、"公開された"APIを介してLimeSurveyを拡張するだけにすべきです。つまり、ソースコードにあるクラスを直接使用するのはよくないやり方です。強制はできませんが、私たちが行うすべてのマイナーアップデートによってプラグインが壊れる危険性があります。

LimeSurveyとは、可能な限り[http://api.limesurvey.org/classes/LimeSurvey.PluginManager.LimesurveyApi.html ここ]で説明する方法でのみ対話してください。イベントについても同じです。

APIオブジェクトはPluginBaseから拡張するときに<code>$this->api</code>経由で使用できます。または、プラグインのコンストラクタに渡されるPluginManagerインスタンスから取得できます。

新しい機能は、要求に応じてAPIオブジェクトに追加することができます。

== フォーム拡張{{NewIn/ja|v=6}} ==

=== はじめに ===

フォーム拡張システムは、フォームごとに新しいイベントを追加せずにコアLimeSurveyでフォームを拡張する、より一般的な方法です。

次のコンポーネントから構成されます。

* '''FormExtensionService'''というグローバルモジュール
* 上記のモジュールの初期化にプラグインを追加できる'''input classes'''ライブラリー
* カスタムレンダラーとともに、LimeSurveyのビューファイルで使用される'''widget'''

各フォームは、<form name><dot><tab name>という形式の'''position string'''によって識別されます。例：<code>globalsettings.general</code>や<code>globalsettings.security</code>

HTMLのないクラスベースのシステムの背後にあるポイントは、プラグイン作者がコアHTMLが変更された場合でもHTMLを更新する必要がないことです。それでも、作者は必要に応じて <code>RawHtmlInput</code> 型を使用できます。

このシステムでは、''新しいフォームタブ''の追加はできません。

=== 例 ===

プラグインからフォームに新しい入力を追加するには、<code>init()</code>関数で以下のコードを使用します。

TODO：グローバルではなくプラグイン設定に保存。

<syntaxhighlight lang="php">
// ファイルの先頭
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');
 }
 ])
);
</syntaxhighlight>

===検証===

入力値の検証は<code>save</code>関数によって行われます（上例を参照）。入力値が無効な場合は、<code>SaveFailedException</code>が返り、警告のフラッシュメッセージがユーザーに提示されます。

=== 対応フォーム ===

以下のフォームを拡張できます。

* globalsettings.general{{NewIn/ja|v=6.0.0}}

別のコアフォームのサポートを追加する場合は、pull-requestで次の変更を適用する必要があります。

ビューファイルに以下を追加します。

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

フォームのHTMLが他のフォームと異なる場合は、<code>DefaultBaseRenderer</code>に基づく新しいレンダラークラスを作成しなければならない場合があります。入力タイプが追加されていない既定のレンダラークラスを拡張しなければならない場合もあります。

次に、フォームを保存するコントローラーアクションにフォーム拡張サービスクラスの呼び出しを追加する変更を行います。

<syntaxhighlight lang="php">
$request = App()->request;
Yii::app()->formExtensionService->applySave('globalsettings', $request);
</syntaxhighlight>

以上。

== ローカリゼーション{{NewIn/ja|v=3}} ==

プラグインで独自のロケールファイルを追加することが可能です。使用されるファイル形式は、コア翻訳と同じ.moです。ファイルは次の場所に保存する必要があります。

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

"<language>"は"de"や"fr"のような二文字の文字列です。

特定のロケールファイルを使用するには、プラグイン関数gTを使用します。

<syntaxhighlight lang="php">
$this->gT("A plugin text that needs to be translated");
</syntaxhighlight>

指定された文字列がプラグイン固有のロケールファイルに見あたらない場合、関数はコアロケールファイルを検索します。したがって、"キャンセル"のような文字列は安全に使用することができます。

<syntaxhighlight lang="php">
$this->gT("Cancel"); // "Cancel"がプラグインロケールファイルにない場合でも翻訳されます
</syntaxhighlight>

プラグインと一緒にビューを使用している場合は、

<syntaxhighlight lang="php">
$plugin->gT("Translate me");
</syntaxhighlight>

のようにし、ビューでプラグイン固有の翻訳を行います。

potファイルがどのように見えるか、その例として[https://github.com/LimeSurvey/LimeSurvey/blob/master/locale/_template/limesurvey.pot limesurvey.pot]ファイルを使用できます。これは翻訳ツールにインポートされます。

===ツール===

po-ファイルやmo-ファイルを編集するツールの一つとして、[https://poedit.net/ Poedit]があります。

== Logging {{NewIn/ja|v=3}} ==

プラグインから何かをログに記録する場合は、次のように記述します。

<syntaxhighlight lang="php">
$this->log("ログに記録するメッセージ");
</syntaxhighlight>

デフォルトのロギングレベルはtraceですが、オプションの第2引数として別のログレベルを指定することもできます。

<syntaxhighlight lang="php">
$this->log("何か間違っている!", CLogger::LEVEL_ERROR);
</syntaxhighlight>

ログファイルは次のフォルダにあります。

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

プラグイン名は自動的にカテゴリーとして使用されます。当該のプラグインのエラーだけを表示するには、grep（Linuxの場合）を使用してください。

$ tail -f tmp/runtime/plugin.log | grep <プラグイン名>

=== Logging plugin deactivation due to error  {{NewIn|v=6.13.3}} ===

Since version 5 of Limesurvey: a plugin can be automatically deactivated in the event of a PHP error.

An email was sent automatically to LimeSurvey administrator. You can use the log system to generate an alert to the other server administrators.

For example: to send an alert message

<syntaxhighlight lang="php">
 // 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
 )
</syntaxhighlight>

Yii 1におけるロギング設定の詳細は[[Optional_settings/ja#.E3.83.AD.E3.82.AE.E3.83.B3.E3.82.B0.E8.A8.AD.E5.AE.9A|ロギング設定]]を参照してください。

== 拡張機能の更新 {{NewIn/ja|v=4}} ==

LimeSurveyバージョン4.0.0以降、プラグインやその他の拡張機能の更新を処理するシステムが用意されています。このシステムを使用するには、拡張機能のconfig.xmlファイルにアップデーター設定を追加する必要があります。

<syntaxhighlight lang="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>
</syntaxhighlight>

（上のソースタグはLimeStore REST APIを指しています。これはLimeStoreのすべての拡張機能で使用されます）。

{| class="wikitable"
|+ アップデータータグの説明
|-
! タグ 
! 説明
|-
| stable 
| "1"は、安定バージョンであることを示します。"0"は、安定バージョンでないことを示し、<code>0.3.3-beta</code>のようになります。
|-
| type 
| 現時点では、<code>rest</code>タイプだけサポートされています。gitやwgetのような新しいアップデータータイプ（バージョンチェッカー）を追加します。
|-
| source 
| 新しいバージョンを読み込むURL。
|-
| manualUpdateUrl 
| 最新の拡張機能にアップデートするためのユーザー向けURL
|-
| automaticUpdateUrl 
| TODO
|}

アップデータを提供したくない場合は、config XMLファイルに次のテキストを入力する必要があります。

このようにして、更新システムに関する情報を追加し忘れたのではなく、更新システムを意図的に無効にしたことをシステムに伝えます。

新しいプラグイン '''UpdateCheck''' - デフォルトでインストールされ、アクティブ化されます。スーパー管理者がログインすると、インストールされた''すべての''拡張機能の新しいアップデートがないか非同期で24時間ごとにチェックします。新しいバージョンが見つかった場合は、通知がプッシュされます。

[[File:availableupdates.png||Available updates]]

新しいセキュリティ更新プログラムが見つかった場合、通知は自動的に開き、"danger"クラスでスタイルされます。

[[File:availablesecurityupdates.png||Available security updates]]

プラグインマネージャービューに移動して"更新を確認"をクリックすると、手動で更新がないか確認できます。このボタンは、UpdateCheckプラグインが有効になっている場合にのみ表示されます。

[[File:manuallycheckforupdates.png||手動でアップデートを確認する]]

===仕組み===

このセクションでは、拡張機能のアップデーターの実装について簡単に説明します。

拡張機能アップデーターは、ExtensionInstallerライブラリの一部です。以下は、アップデータープロセスに関連するクラスのUML図です。

[[File:extensionupdateruml.png||拡張機能アップデーターのUML図]]

Yii開始時のプログラムフロー:

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

UpdaterCheckプラグインが機能する時のプログラムフロー:

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

UpdateCheckプラグインの[https://github.com/LimeSurvey/LimeSurvey/blob/develop/application/core/plugins/UpdateCheck/UpdateCheck.php#L130 checkAll]メソッドは、新しいバージョンのすべての拡張機能を照会する方法の例です。

====新しいバージョンのフェッチャーを追加する====

新しいカスタムバージョンフェッチャーを追加するには、Yiiの初期化中にこれを実行します。

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

もちろん、クラス<code>MyNewVersionFetcher</code>は、<code>VersionFetcher</code>をサブクラス化します。

新しいバージョンのフェッチャーを使用するには、アップデーターXMLの<code>type</code>タグを<code>myNewVersionFetcherType</code>を使用するよう設定します（例えば、<code>rest</code>の代わりに）。

====新しい拡張機能アップデーターの追加====

新しいカスタム拡張機能フェッチャーを追加するには、Yiiの初期化中にこれを実行します。

<syntaxhighlight lang="php">
$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
 'myNewExtensionUpdater',
 function () {
 return MyNewExtensionUpdater::createUpdaters();
 }
);
</syntaxhighlight>

<code>MyNewExtensionUpdater</code>クラスは<code>ExtensionUpdater</code>をサブクラス化します。

config.xml（ 'plugin'、 'theme'、...）の最初の<code>type</code>タグは、この拡張機能で使用される拡張機能アップデーターを制御します。カスタムExtensionInstaller、メニュー項目などを追加する必要もあるので、このシステムはまだ完全にカスタマイズ可能ではありません。しかし、理論的、そして将来的には、このように新しいタイプの拡張を追加することは可能です。

==拡張インストーラー==

拡張インストーラライブラリーは、次の２つの抽象クラスで構成されています。

* ExtensionInstaller
* FileFetcher

ExtensionInstallerは、PluginInstaller、QuestionThemeInstallerなどの拡張タイプごとにサブクラス化されています。

FileFetcherは、ファイルをフェッチする方法ごとにサブクラス化されています。現在、アップロードされたzipファイルのみがサポートされていますが、将来的にはGithubまたはLimeStoreフェッチャーもサポートされる可能性があります。

[[File: extensioninstalleruml.png]]

== 特殊なプラグイン ==

* [[Authentication plugin development|認証プラグインの開発]]
* [[Export plugin development|プラグインの開発をエクスポートする]]

== 利用可能なプラグイン ==
* [[Authentication plugins|認証プラグイン]]
* [[Audit log|監査ログ]]
* [[AzureOAuthSMTP Plugin]]
* [[CintLink]]
* [[Available third party plugins|利用可能なサードパーティのプラグイン]]

== Tutorial ==
[https://medium.com/@evently/creating-limesurvey-plugins-adcdf8d7e334 この]ステップバイステップのチュートリアルでは、アンケート回答を提出するごとにPOSTリクエストを送信するプラグインを作成する方法を示しています。このチュートリアルでは、全体およびアンケートごとの設定の作成／保存の方法、イベントの登録方法などが紹介されています。

[[Category:Development]]
[[Category:Plugins]]

Main chapters

Special

Export translations