======HTML======
=====概要=====
各ユニットはデフォルトでは1つのHTMLファイルを持ちます（BitsmistJSではスキンと呼びます）。各ユニットのHTMLファイルは、ロードしてユニットに適用（ノードに追加）される必要があります。複数のHTMLファイルを切り替えて表示したり、逆に全くHTMLを使用しないユニットを作成することもできます。これらの機能は、SkinPerkによって処理されます。さらにShadow DOMの適用も、SkinPerkによって行われます。
ユニットは初期化中に"basic.transform"スペルを使い、beforeTransform・doTransform・afterTransformイベントをトリガーします。SkinPerkはbeforeTransformでHTMLをロードするイベントハンドラをインストールし、doTransformでロードしたHTMLを適用するイベントハンドラをインストールします。
=====設定=====
SkinPerkの設定は"skin"セクションに記述します。SkinPerkに対する設定は"skin.options"セクションに、各HTMLに関する設定は、"skin.skins"セクション配下にスキン名をキーに記述します。スキン名は後述の[[#切り替え|スキンの切り替え]]時に指定する名前となります。デフォルトのスキンに関する情報は"default"セクションに記述します。なお"default"セクションが存在しない場合は、デフォルトのファイルをロードします。
_getSettings()
{
return {
"skin": {
"options": {
"skinRef": True,
},
"skins": {
"default": {
"type": "URL",
"rootNode": "/units/default.html"
},
"skin2": {
"type": "HTML",
"rootNode": ""
}
}
}
}
}
SkinPerkの設定の詳細については以下をご覧ください。
* [[ja:bitsmist-js-core:reference:perk:skin-perk#設定|リファレンス - パーク - SkinPerk - 設定]]
=====ロード=====
SkinPerkはbeforeTransformイベントでHTMLをロードします。その際、ロードしたHTMLを元にTemplateノードを作成し、ユニットのインベントリのbasic.unitRootにセットします。この時点ではまだ、画面には表示されません。
HTMLのロード元としては、ファイル・ノード・固定のHTMLの3種類からロードすることができます。何も設定を記述しない場合、デフォルトのパスとファイル名を使ってHTMLファイルをロードします。
====ファイル====
===デフォルトのパスとファイル===
"system.skin.options.path"と"skin.options.path"を繋げたものが、デフォルトのパスとして使用されます。もし設定が存在しない場合はそれぞれ、"system.unit.options.path"と"unit.options.path"が代わりに使用されます。
また、タグ名に拡張子"html"をつけたファイル名を、デフォルトのファイル名として使用します。
==ファイル名やパスを指定する==
もし、ロードするパスやファイル名を変更したい場合は、設定に記述します。
_getSettings()
{
return {
"skin": {
"options": {
"path": "my-skinpath",
"fileName": "my-skinfile",
},
}
}
}
URLを使用したい場合は、skinRefオプションを使用します。
_getSettings()
{
return {
"skin": {
"options": {
"skinRef": "https://example.com/my-skinpath/my-skinfile.html",
},
}
}
}
または"skins.default"セクションに記述します。
_getSettings()
{
return {
"skin": {
"skins": {
"default": {
"type": "URL",
"URL": "https://example.com/my-skinpath/my-skinfile.html",
},
}
}
}
}
===HTMLが不要な場合===
もし、ユニットがHTMLファイルを全く持たない場合、設定にそう記述する必要があります。
_getSettings()
{
return {
"skin": {
"options": {
"skinRef": false,
},
}
}
}
そうでないと、ユニットがデフォルトのHTMLファイルをロードしようとして404エラーが発生し、初期化が中断してしまいます。
====固定のHTML====
設定にHTMLを記述することで、そのHTMLを元にTemplateノードを作成し、それを表示します。Webpackなどを使用すれば、HTMLは外部ファイルに記述しておきながら、一つのファイルにまとめることも可能です。
_getSettings()
{
return {
"skin": {
"skins": {
"default": {
"type": "HTML",
"HTML": ""
},
}
}
}
}
====ノード====
自身のユニット内のノードのinnerHTMLを元にTemplateノードを作成し、それを使用します。なお、ノードを指定するためにはそのノードが含まれるユニットのHTMLをあらかじめロードしておく必要があるため、最初はファイルか固定のHTMLでロードしておかなければなりません。そのため、切り替え用のHTMLを指定するために使用されます。
_getSettings()
{
return {
"skin": {
"skins": {
"default": {
"type": "node",
"selctor": "template#grid"
},
}
}
}
}
=====適用=====
ロードしたHTMLは、doTransformイベントでユニットに適用されます。具体的には、ユニットのinnerHTMLが""（空文字）で初期化された後、Templateをクローンしたノードがユニットに追加されます。
=====切り替え=====
"basic.transform"スペルを使い、複数のHTMLを状況に応じて、切り替えることができます。その際、初期化と同じようにHTMLのロードと適用が行われます。スペルの引数には切り替え先のスキン名を指定します。
this.cast("basic.transform", {"skinName": "skin2"});
初期化時のデフォルトHTMLのロードと適用にも、"basic.transform"スペルが使用されています。
HTMLを切り替えて使用する場合、あらかじめ設定の"skin.skins"セクションに、切り替え先のHTMLの設定を記述しておく必要があります。
_getSettings()
{
return {
"skin": {
"skins": {
"skin2": {
"type": "HTML",
"HTML": ""
},
}
}
}
}
=====Shadow DOM=====
BitsmistJSでは、各ユニットに"open"、"closed"のいずれのShadow DOMも適用することができます。Shadow DOMを使用することで、各ユニットの独立性が上がります。Shadow DOMの適用は、SkinPerkによって行われます。
Shadow DOMはJavascriptの標準技術です。詳細については、以下をご覧ください。
* [[https://developer.mozilla.org/ja/docs/Web/API/Web_components/Using_shadow_DOM|シャドウ DOM の使用 - Mozilla Developer]]
デフォルトではShadow DOMは使用されません。Shadow DOMを使用する場合、設定に記述する必要があります。
_getSettings()
{
return {
"skin": {
"options": {
"shadowDOM": "open",
},
}
}
}
"open"または"closed"を指定することができます。
Shadow DOMを使う場合、CSSの構造を綿密に設計する必要があります。CSSを取り扱うStylePerkの設定についても参照してください。
* [[ja:bitsmist-js-core:unit:css#設定|ユニットの解説 - CSS - 設定]]