Web管理ツール上からカスタマイズ可能な設定をプラグインに持たせるための方法を説明します。
以下、+PLUSTを使って生成されたプラグインプロジェクトについて説明します。プラグイン名は「com.example」とします。またプラグインプロジェクトのルートディレクトリを「com.example」とします。
設定を定義するクラスの作成
まずcom.example.setting.ExamplePluginSettingsクラスで設定を定義します。設定の項目はこのクラスのJavaBeansプロパティとして定義されます。なおプロパティ名が例えば「contentId」のようなCamelスタイルの名前の場合、項目名は「content-id」のようにハイフンで連結された形になります。
例えば設定可能な項目として文字列型の「description」という項目を定義するには、ExamplePluginSettingsクラスに以下のようにGetter/Setterを定義して下さい。
private String description;
public String getDescription() {
return description;
}
@Attribute
public void setDescription(String description) {
this.description = description;
}
Setterには「@Attribute」というアノテーションをつけています。これはnet.skirnir.xom.annotation.Attributeアノテーションで、このクラスで定義された設定項目をXML形式に永続化する際に属性値として永続化する必要があることをフレームワークに指示するためのものです。同様のアノテーションとして子要素として永続化することを指示するChildアノテーションや、要素のボディとして永続化することを支持するContentアノテーション等があります。これらのアノテーションが付与されていないプロパティは永続化されないので注意して下さい。
同じ項目を複数持たせることもできます。その場合は複数項目を取得するためのGetterと項目を1つ追加するためのメソッドを作成しておいて下さい。例えばdescriptionを複数個持たせる場合は以下のようになります。
private List<String> descriptions;
public String[] getDescriptions() {
return descriptions.toArray(new String[0]);
}
@Child
public void addDescription(String description) {
descriptions.add(description);
}
設定項目の説明の記述
前節で作成したクラスは永続化に使用される一方で、管理ツールから設定を管理する際にも使用されます。管理ツールで設定を管理する際に適切な説明文が表示されるよう、クラスと項目の説明をcom/example/settings/ExamplePluginSettings.xpropertiesに記述しておきます。
このファイルは国際化されていますので、例えば英語の説明をExamplePluginSettings.xpropertiesに書き、日本語の説明をExamplePluginSettings_ja.xpropertiesに書くということもできます。
このファイルにはキーとして以下のものを記述することができます。
- description
- クラス自体の説明、すなわち設定全体の説明
- [項目名].description
- 項目の説明
初期値の指定
定義した設定のための初期値を指定するには、plugin.xmlと同じ場所にplugin-settings.xmlという名前でXMLファイルを置いて下さい。XMLのルート要素は設定クラス名のCamel結合をハイフン結合に変えたものにして下さい。例えばExamplePluginSettingsクラスであれば「example-plugin-settings」として下さい。内容は設定クラスの項目をXML形式で記述して下さい。
例えば以下の設定クラスであれば、
public class ExamplePluginSettings {
private String description;
public String getDescription() {
return description;
}
@Attribute
public void setDescription(String description) {
this.description = description;
}
}
plugin-settings.xmlは以下のようになります。
<?xml version="1.0" encoding="UTF-8"?> <example-plugin-settings description="DESCRIPTION"> </example-plugin-settings>
管理ツールによる設定のカスタマイズ
管理ツールからは、「プラグイン管理」から設定をカスタマイズできます。保存した設定内容はKvasir/Soraのインストールディレクトリ以下のkvasir/configuration/plugins/com.example/plugin-settings.xmlに保存されます。
プラグイン配下のクラスからの設定の利用
Plugin#getSettings()メソッドを使うと、設定を保持するJavaBeanを取り出すことができます。なおこのオブジェクトは参照専用ですので、状態を変更するメソッドを呼び出してはいけません。