Title: プラグイン設定の追加方法
プラグインによっては、インストール済みプラグイン項目に [設定] リンクが表示され、クリックして表示される画面で細かな設定変更ができるようになっているものがあります。この記事では、このような設定の設置方法や利用方法について説明します。
動作例プラグイン
ここをクリックして、下記の解説で使用しているプラグインをダウンロードできます。
com.traction.sdllessons.settings-1.0.0.zip
注意: このドキュメントを作成中にプラグイン名称を変更しました。スクリーンショットでは、プラグインのフォルダ名が「com.traction.hoge」になっていますが、これを「com.traction.sdllessons.settings」に読み替えてください。
設定の種類（レベル）
設定の種類と影響範囲
まず、TeamPage の設定には、ジャーナル、サーバー、スペース、ユーザーの 4 つの「種類（レベル）」があるということから見てみましょう。
| 種類（レベル） |
説明 |
設定された内容の保存場所 |
|---|
| ジャーナル |
ジャーナル（TeamPageのデータ保管場所）に保存される設定で、サーバー管理者だけが設定できる。 |
ジャーナルの db.properties ファイル |
| サーバー |
サーバーに適用される設定で、サーバー管理者だけが設定できる。ジャーナルを変更しても、このサーバーの設定は変わらない。 |
erver ディレクトリの Traction.properties ファイル |
| スペース |
スペース毎に適用される設定で、スペース管理者またはサーバー管理者が設定できる。 |
ジャーナルの 番号.prop または スペース名.prop ファイル |
| ユーザー |
ユーザーごとに適用される設定で、各ユーザー（ただし「パーソナル セットアップ」権限が必要）とサーバー管理者が設定できる。 |
ジャーナルの users サブディレクトリの 番号.prop ファイル |
例えば、サーバーセットアップ > 既定値 > ジャーナル設定 の ジャーナル ロケール はジャーナルの設定です。この設定を変更すると、設定値は、ジャーナルのフォルダの db.properties ファイルの locale= 行に保存されます。
また、サーバーセットアップ > 既定値 > ユーザー設定 > ブラウザ の ロケール はユーザーの設定です。この設定は、パーソナル セットアップ >ユーザー設定 > ブラウザ にもあります。サーバーセットアップにあるものは、サーバー管理者がすべてのパーソナルセットアップの既定値として設定するものです。それに対して、パーソナルセットアップにあるものは、該当ユーザーが自分の設定として行います。変更内容は、ジャーナルのフォルダにある「users」サブフォルダの「ユーザー番号.prop」ファイルに locale= として保存されます。
参照: DocJp510: 既定値の設定について
設定ファイルが置かれている場所
これらの設定ファイルは、TeamPage がインストールされた server ディレクトリの、config/setting/props 内に、journal、server、project、user などのフォルダごとに分類されて設置されています。
メモ: TeamPage の過去のバージョンでは「スペース」のことを「プロジェクト」と呼んでいました。その歴史的な理由により、スペースの設定ファイルは「project」フォルダに置かれています。
プラグインの動作を変更させるための新しい設定を追加するには、プラグインのフォルダに config/settings/props 階層を作成し、その中に journal, server, project, user などのフォルダを作成し、その中に設定の定義ファイルを設置します。次に、そのやり方を解説します。
新しい設定を利用できるようにする
設定の定義ファイルを設置する
プラグインのフォルダに config/settings/props 階層を作成します。例えば、プラグインの名前が「com.traction.sdllessons.settings」だとすると、TeamPage がインストールされた「server」ディレクトリの中の、「plugins」フォルダの中の、「com.traction.sdllessons.settings」フォルダの中に、「config」フォルダを作り、その中に「settings」フォルダを作り、更にその中に「props」フォルダを作ります。
その「props」フォルダの中に、ユーザー用設定を作る場合は「user」フォルダを、ジャーナル用設定を作る場合は「journal」フォルダを…作成します。
例）ジャーナル用設定を設置する
ここでは、「journal」フォルダの中に hoge_yesno.properties というファイルを設置し、「はい」か「いいえ」の選択ドロップダウンリストを作ることにします。
hoge_yesno.properties をテキストエディタで開き、次のように記述して上書き保存します。
class=com.traction.settings.YesNo
display_name=Hoge YesNo
description=Select Yes or No.
tip=This is a great example.
sdleditor=com.traction.sdl.admin.settings#singleselect
default=true
usedefault=true
- class= ... 設定項目の種類を指定します。「はい」と「いいえ」の選択ドロップダウンを表示するには com.traction.settings.YesNo を指定します。
- display_name= ... 設定項目の見出しです。
- description= ... 設定項目の説明文です。（省略可）
- tip= ... 設定項目の右側に表示されるヒントです。（省略可）
- sdleditor= ... これはドロップダウンリストを表示するための決まり文句です。
- usedefault= ... [既定値を使用] チェックボックスを表示するかどうかの設定です。「true」の場合は表示されます。
- default= ... [既定値を使用] のチェックボックスの初期値（チェックがオンかオフか）を設定します。「true」の場合は既定でチェックがオンになります。
例）ユーザー用設定を設置する
ここでは、「user」フォルダの中に hoge_text.properties というファイルを設置し、テキスト入力の設定欄を作ることにします。
hoge_text.properties をテキストエディタで開き、次のように記述して上書き保存します。
class=com.traction.settings.TextInput
display_name=Hoge Text Input
description=Text box example.
tip=Great!
sdleditor=com.traction.sdl.admin.settings#textinput_belowlabel
size=80
usedefault=true
default=Foo Bar
- class= ... 設定項目の種類を指定します。テキストボックス（テキストを表示するには com.traction.settings.TextInput を指定します。
- display_name= ... 設定項目の見出しです。
- description= ... 設定項目の説明文です。（省略可）
- tip= ... 設定項目の右側に表示されるヒントです。（省略可）
- sdleditor= ... これはテキストボックスを表示するための決まり文句です。他にもいくつかの設定値があります。（下記参照）
- usedefault= ... [既定値を使用] チェックボックスを表示するかどうかの設定です。「true」の場合は表示されます。
- default= ... テキストボックスの既定の値を設定します。
- size= ... テキストボックスの大きさ（長さ）です。
メモ: テキストボックスを表示するための sdleditor には、textinput_belowlabel の他に、textinput, textinput_afterlabel, textinput_afterlabel2 などがあり、それぞれテキストボックスや説明文の配置が異なります。
プラグイン定義ファイルで設定定義ファイルを指定する
プラグインの定義ファイル（「com.traction.sdllessons.settings」フォルダの「plugin.properties」ファイル）をテキストエディタで開き、次のように記述します。
display_name=Hoge Settings Plug-in
description=Shows how to implement journal, server, project, and user settings in config/settings/props directory.
version=1.0.0
buildnum=0
server_config=true
db_config=true
db_settings=hoge_yesno
user_config=true
user_settings=hoge_text
- server_config= ... 「true」にすると、サーバーセットアップ > プラグイン のインストール済みプラグインに [設定] リンクを表示します。
- db_config= ... 「true」にすると、サーバーセットアップ > プラグイン のインストール済みプラグインのプラグインのタイトルをクリックすると設定画面が表示され、db_settings で指定した設定が利用できるようになります。
- db_settings= ... config/settings/props/journal に設置したファイル名（拡張子は省略）を指定します。複数ある場合は半角コンマ記号で区切って記述します。
- user_config= ... 「true」にすると、user_settings で指定した設定が利用できるようになります。
- user_settings= ... config/settings/props/user に設置したファイル名（拡張子は省略）を指定します。複数ある場合は半角コンマ記号で区切って記述します。
ファイルを保存したら、サーバーセットアップ > 一般 > サーバー管理の [キャッシュクリア] をクリックします。
設定画面の表示を確認する
サーバーセットアップ > プラグイン で [Hoge Settings Plug-in] の [設定] リンクをクリックします。[設定] リンクが表示されていない場合は、plugin.properties の server_config= の記述ミスを確認してください。
下図のような設定画面が表示されます。
設定をSDLで利用するには
上記で設定の作り方や設置方法を説明しました。次に、SDL のコード（プログラム）から設定の値を参照する（設定の状態を調べる）方法を解説します。
ビューの作成
設定の動作チェックをするためのビューを作成します。
ビューの定義ファイル (.properties)
プラグインのフォルダの中に config/views/all の階層を作成し、この「all」フォルダの中に「checkhoge.properties」を作成し、テキストエディタで開いて次のように記述します。
sdl=com.traction.sdl.tutorial.checkhoge
ビューの HTML テンプレート ファイル (.sdl)
プラグインのフォルダの中に com/traction/sdl/tutorial の階層を作成し、この「tutorial」フォルダの中に「checkhoge.sdl」を作成し、テキストエディタで開いて次のように記述します。
<!DOCTYPE html>
<html>
<head>
<title>Hoge: Check Configurations</title>
<style>
.true { color: blue; } .false { color: red; }
</style>
</head>
<body>
<p>The value of hoge_yesno is <#journal_config_yesno />.</p>
<p>The description of the text box is <#user_config_text />.</p>
</body>
</html>
<sdl.function name="journal_config_yesno">
<config.db.boolean name="hoge_yesno">
<!-- ジャーナルの「hoge_yesno」設定で「はい」が選択されている場合 -->
<span class="true">YES</span>
<else>
<!-- ジャーナルの「hoge_yesno」設定で「いいえ」が選択されている場合 -->
<span class="false">NO</span>
</config.db.boolean>
</sdl.function>
<sdl.function name="user_config_text">
<!-- ユーザーの「hoge_text」設定テキストボックスの値を取得する -->
<config.user.value name="hoge_text" />
</sdl.function>
ファイルを保存し、サーバーセットアップ > 一般 > サーバー管理 の [キャッシュのクリア] をクリックします。
ビューでの動作確認
検索ボックスに /type checkhoge と入力して Enter キーを押します。
下図のような「checkhoge」のビューが表示されます。
1行目は、ジャーナル設定の「hoge_yesno」の「はい」「いいえ」によって変化します。
2行目は、ユーザー設定の「hoge_text」のテキストボックスに入力された内容が反映されます。
設定値を読み取るための SDL タグ
SDL の <config.*.*> タグで設定値を調べたり値を取得したりできます。
Yes/No 式の設定は Boolean タグで調べる
Yes/No 式の設定の値（「はい」か「いいえ」か）を調べるには <config.*.boolean name="設定名">...</config.*.boolean> タグを使います。ここの「*」には、設定の種類（レベル）が入ります。例えば、ジャーナル設定の場合は <config.db.boolean> に、スペース設定の場合は <config.project.boolean> になります。
この <config.*.boolean> は、<else> タグを組み合わせて「条件が真ではないとき」の条件分岐ができます。
<config.user.boolean name="ConfigName">
<!-- 設定で「はい」が選択されている場合に実行 -->
<else>
<!-- 設定で「いいえ」が選択されている場合に実行 -->
</config.user.boolean>
また not を組み合わせて逆の動作も指定できます。
<config.user.boolean name="ConfigName" not>
<!-- 設定で「いいえ」が選択されている場合に実行 -->
<else>
<!-- 設定で「はい」が選択されている場合に実行 -->
</config.user.boolean>
テキストボックスの値は Value タグで調べる
テキストボックス型の設定欄の値を調べるには、<config.*.value name="設定名" /> を使います。例えば、スペース設定のテキストボックスの値を調べるには <config.project.value name="設定名" /> とします。
さらに、<compare.equals> などの条件分岐タグと組み合わせることも可能です。
参照: DocSDK270: SDL Lesson 11 - 値を比較して「もし真ならばAせよ、さもなくばBせよ」な分岐処理を行う
例えば、次のようにすると、ジャーナルの「today」という設定（テキストボックス）に「2015/01/01」が入力されている場合は、「Happy New Year!」を表示します。（この例には <else> タグがないため、テキストボックスの値が「2015/01/01」ではないときは何も表示しません。）
<compare.equals "<config.db.value name='today' />" "2015/01/01">
<p>Happy New Year!</p>
</compare.equals>
