Actions

プラグイン - 上級者向け

From LimeSurvey Manual

Revision as of 01:39, 12 July 2021 by Bravehorse (talk | contribs) (Created page with "==拡張インストーラー==")
Other languages:

概要

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

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

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

  • ロゴ
  • 文字列
  • 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

イベント

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

API

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

LimeSurveyとは、可能な限りここで説明する方法でのみ対話してください。イベントについても同じです。

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

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

ローカリゼーション (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");

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

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におけるロギング設定の詳細はロギング設定を参照してください。

拡張機能の更新 (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時間ごとにチェックします。新しいバージョンが見つかった場合は、通知がプッシュされます。

Available updates

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

Available security updates

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

手動でアップデートを確認する

仕組み

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

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

拡張機能アップデーターの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、メニュー項目などを追加する必要もあるので、このシステムはまだ完全にカスタマイズ可能ではありません。しかし、理論的、そして将来的には、このように新しいタイプの拡張を追加することは可能です。

拡張インストーラー

The extension installer library consists of two abstract classes:

  • ExtensionInstaller
  • FileFetcher

The ExtensionInstaller is subclassed for each extension type, like PluginInstaller, QuestionThemeInstaller, etc.

The FileFetcher is subclassed for each different way to fetch files. Currently, only uploaded zip files are supported, but in the future, there could be a Github or LimeStore fetcher too.

特殊なプラグイン

利用可能なプラグイン

Tutorial

このステップバイステップのチュートリアルでは、アンケート回答を提出するごとにPOSTリクエストを送信するプラグインを作成する方法を示しています。このチュートリアルでは、全体およびアンケートごとの設定の作成／保存の方法、イベントの登録方法などが紹介されています。

Retrieved from "http://manual.limesurvey.org/index.php?title=Plugins_-_advanced/ja&oldid=168241"