設定
概要
各コンポーネントは固有の設定を持っています。ここではその設定について説明します。また、全コンポーネント間で共有される、グローバルな設定に関しても説明します。
設定はJSON形式で記述されます。各コンポーネントはその設定によって動作を変更します。
設定の読込
コンポーネントの設定を記述する方法は4通りあります。
- 設定取得用の関数から設定を返す
- 外部ファイルに記述する
- タグの属性に記述する
- グローバル設定に記述する
それぞれの方法を詳しく見ていきます。
設定取得用の関数から返す
BitsmistJSのコンポーネントを作成する場合は、既存のコンポーネントを継承して作成します。コンポーネントには_getSettings()という関数があるので、その関数をオーバーライドし、設定内容のオブジェクトを返します。
_getSettings() { return { "loadings": { "path": "common", }, "settings": { "name": "BarMain", }, "events": { "this": { "handlers": { "doSetup": this.onDoSetup } } } } }
これが最も一般的な方法です。
外部ファイルに記述する
外部ファイルにJSON形式で設定を記述し、そのURLをタグのbm-settingref属性に指定します。
<bar-header bm-settingref="https://example.com/settings/bar-header.settings.js"></bar-header>
- bar-header.setting.js
{ "loadings": { "path": "common" }, "settings": { "name": "BarMain", }, "events": { "this": { "handlers": { "doSetup": "onDoSetup" } } } }
外部設定ファイルの指定がある場合、コンポーネントの初期化中に該当のファイルがロードされ、コンポーネントの設定にマージされます。ファイルのロードが完了するまで、初期化は中断されます。
この方法を使うと、同じコンポーネントでもタグ(インスタンス)ごとに違う設定を読み込ませることが可能です。
タグの属性に記述する
bm-settings属性にJSON形式で記述します。
<button-link bm-settings='{"title":"BitsmistJS"}'></button-link>
この方法の場合、外部ファイルを読む場合と同じく、同じコンポーネントでもタグごとに違う設定が可能です。
また、オーガナイザによっては、独自の属性から設定を読み込みます。例えばLoaderOrganizerでは“bm-path”という属性で、コンポーネントを読み込むパスを指定できます。
<bar-header bm-autoload bm-path="common"></bar-header>
グローバル設定に記述する
グローバル設定はページ上の全てのコンポーネントで共有される設定です。デフォルトでは、各コンポーネントの設定はグローバル設定に連結されています。どういうことかというと、コンポーネントが自身の設定を参照した際、もしその設定が存在しない場合は透過的にグローバル設定から取得されるようになっています。
グローバル設定についての詳細は、専用のセクションを参考にしてください。
設定の優先度
4つの設定の記述方法は、複数組み合わせて使うこともできます。その際、同じ設定が存在する場合は優先順位の高い方で上書きされます。優先度は以下のようになります。上の方がより優先度が高くなります。
- タグの属性
- 外部ファイル
- _getSettings()関数
- グローバル設定
基本的な設定を_getSettings()関数に記述しておき、ページによって変わる設定内容をタグの属性で記述しておく、といった使い方が可能です。
設定内容
BitmistJSではコンポーネントの設定内容に応じた実際の処理は、オーガナイザによって行われます。そのため、どのような設定が存在するかは、どのオーガナイザを適用するかによって変わってきます。
ここでは、コアライブラリに含まれる各オーガナイザが担当する設定の一覧を示します。設定内容についてはリンク先の各オーガナイザーの説明をご覧ください。基本的には設定のセクションによって、使用されるオーガナイザが決まります。
セクション | 担当オーガナイザ | 説明 |
---|---|---|
events | EventOrganizer | イベントハンドラ関係を管理します。 |
loadings molds components | LoaderOrganizer | コンポーネントやテンプレートHTMLのローディングを管理します。 |
organizers | OrganizerOrganizer | どのオーガナイザをコンポーネントに適用するか管理します。 |
settings | SettingOrganizer | 基本的な設定を管理します。 |
templates | TemplateOrganizer | 固定のHTMLテンプレートを指定するための設定です。 |
waitFor | StateOrganizer | 他のコンポーネントが特定の状態になるのを待つための設定です。 |
また、上記とは別に、様々なオーガナイザから参照される“system”セクションについても紹介します。これらはシステム全体に影響を与えるため、後に紹介するグローバル設定に記述します。
セクション | 設定 | 説明 |
---|---|---|
system | appBaseUr | アプリのベースとなるURLを指定します。 |
componentPath | コンポーネントを格納するベースのパスを指定します。 | |
templatePath | HTMLファイルを格納するベースのパスを指定します。 |
グローバルなシステム設定をコンポーネントの設定に記述することで、上書きすることも可能です。
設定へのアクセス
設定内容にアクセスするためには、各コンポーネントのsettingsプロパティを使用します。
this.settings.set("value", 1); console.log(this.settings.get("value")); // console displays 1
.(ピリオド)を使用して、セクションを指定したアクセスも可能です。
this.settings.set("mysection.value", 1); console.log(this.settings.get("value")); // console displays "undefined" console.log(this.settings.get("mysection.value")); // console displays 1
このsettingsプロパティはStoreオブジェクトを使用しています。
グローバル設定
ここでは全コンポーネント間で共有できる、グローバル設定について説明します。
グローバル設定の設定方法
BitsmistJSをロードすると、BITSMIST.v1.settingsというStoreオブジェクトが使えるようになります。そのStoreオブジェクトに値をセットすると、それがグローバルな設定となります。グローバル設定にはBITSMIST.v1.settingオブジェクトを使ってアクセスできます。
次の例では、Storeのmerge()メソッドを使って、既存の設定に設定をマージしています。
BITSMIST.v1.settings.merge({ "system": { "appBaseUrl":"https://example.com", "componentPath":"/components/", }, });
既に他の場所でグローバル設定がされている可能性もあるため、それらを消してしまわないよう、set()ではなくmerge()を使うことをお勧めします。
グローバル設定のロード
グローバル設定には全体に関わる設定が記述されます。この設定情報がないと処理を正しく先に進めることができないことが多いので、できるだけ早めにロードした方がいいかもしれません。
一つの方法として、例えば上記の設定をsettings.jsというJavascriptに記述し、HEAD内で読み込みます(ただし、BitsmistJSライブラリよりかは後にしてください)。
<script type='text/javascript' src='/js/settings.js'></script>
こうすると、コンポーネントのオートロードが始まる前に、グローバル設定が有効になります。
グローバル設定の連結
settingsプロパティには他の設定と連結させる機能があります。各コンポーネントの設定は、デフォルトではグローバルな設定(BITSMIST.v1.settings)と連結しています。
グローバル設定と連結していると、コンポーネント内にその設定が存在しない場合、連結されている設定から取得されます。そのため通常の設定のアクセス方法と同じようにアクセスすることで、グローバル設定にその設定が存在するのであれば、自動的にグローバルな設定が取得されます。
BITSMIST.v1.settings.set("myValue", 1) // global setting console.log(this.settings.get("myValue")); // console displays 1
このグローバル設定との連結は、設定で“settings.useGlobalSettings”がTrueにセットされていると行われます(デフォルトはTrueです)。もし連結させたくない場合は、次の例のように、この値をFalseにセットしてください。
_getSettings() { return { "settings": { "name": "bar-header", "useGlobalSettings": false } }; }
グローバル設定の上書き
グローバルな設定と同じ設定がコンポーネント内にあると、そちらが優先されます。そのため、あえてグローバルとは違う設定を使いたいコンポーネントに対しては、コンポーネントに同じ項目の設定をすることで、連結されたグローバルな設定を取得しないようになります。
BITSMIST.v1.settings.set("myValue", 1) this.settings.set("myValue", 2) console.log(this.settings.get("myValue")); // console displays 2
例えば、そのサイト上のコンポーネントはそのサイトのグローバル設定に従いますが、全く別のサーバーから提供されるサードパーティのコンポーネントは、独自の設定を使いたいかもしれません。
グローバル設定へのアクセス
明示的にグローバルな設定にアクセスしたい場合は、BITSMIST.v1.settingsにアクセスします。
console.log(BITSMIST.v1.settings.get("myValue"));