======HTML======
=====Overview=====
Each unit has one HTML file (called "skin" in BitsmistJS) by default. The unit's HTML file must be loaded and applied to the unit (added to the node). It is possible to switch between multiple HTML files or create a unit with no HTML at all. These functions are handled by SkinPerk. In addition, the Shadow DOM is also handled by SkinPerk.
A unit uses the "basic.transform" spell during its initialization to trigger beforeTransform, doTransform, and afterTransform events. The SkinPerk installs beforeTransform event handler to load HTML, and doTransform event handler to apply the loaded HTML.
=====Settings=====
SkinPerk settings are written in the "skin" section. The settings for SkinPerk itself are written in the "skin.options" section, and settings for each skin are written under the "skin.skins" section using the skin name as a key. The key name is used when [[#switching_html|switching a skin]]. The settings for the default skin is written in the "default" section. If the "default" section does not exist, the default file is loaded.
_getSettings()
{
return {
"skin": {
"options": {
"skinRef": True,
},
"skins": {
"default": {
"type": "URL",
"rootNode": "/units/default.html"
},
"skin2": {
"type": "HTML",
"rootNode": ""
}
}
}
}
}
For more information on SkinPerk settings, please see below.
* [[en:bitsmist-js-core:reference:perk:skin-perk#settings|Reference - Perk - SkinPerk - Settings]]
=====Loading a Skin=====
SkinPerk loads an HTML file in the beforeTransform event. In the event, it creates a template node based on the loaded HTML and sets it to the basic.unitRoot of the unit's inventory. At this point, the HTML is not yet displayed on the screen.
HTML can be loaded from a file, a node, or fixed HTML strings. The HTML file will be loaded using the default path and file name if no settings are specified.
====File====
===Default Path and File===
"system.skin.options.path" and "skin.options.path" settings concatenated will be used as the default path. If the setting does not exist, "system.unit.options.path" and "unit.options.path" will be used instead.
The default filename is the tag name with the "html" extension.
===Specifying a Filename or Path===
If you want to change the path or filename to be loaded, specify it in the settings.
_getSettings()
{
return {
"skin": {
"options": {
"path": "my-skinpath",
"fileName": "my-skinfile",
},
}
}
}
If you want to use a URL, use the skinRef option.
_getSettings()
{
return {
"skin": {
"options": {
"skinRef": "https://example.com/my-skinpath/my-skinfile.html",
},
}
}
}
or in the "skins.default" section.
_getSettings()
{
return {
"skin": {
"skins": {
"default": {
"type": "URL",
"URL": "https://example.com/my-skinpath/my-skinfile.html",
},
}
}
}
}
===No HTML===
If a unit has no HTML files at all, it must be written in the settings.
_getSettings()
{
return {
"skin": {
"options": {
"skinRef": false,
},
}
}
}
Otherwise, the unit will try to load the default HTML file and a 404 error will occur, interrupting the initialization.
====Fixed HTML====
By writing HTML strings in the settings, a template node is created based on that HTML, which is then displayed. Using Webpack or similar, the HTML can be written in an external file but combined into one file.
_getSettings()
{
return {
"skin": {
"skins": {
"default": {
"type": "HTML",
"HTML": ""
},
}
}
}
}
====Node====
A template node is created based on the innerHTML of a node in its own unit. Note that in order to specify a node, the HTML of the unit containing that node must be loaded in advance, so it must initially be loaded as a file or fixed HTML. Therefore, it can be used to specify HTML for switching.
_getSettings()
{
return {
"skin": {
"skins": {
"default": {
"type": "node",
"selector": "template#grid"
},
}
}
}
}
=====Applying a Skin=====
The loaded HTML is applied to the unit in the doTransform event. Specifically, after the innerHTML of the unit is initialized with "" (an empty string), the cloned template node is added to the unit.
=====Switching a Skin=====
Using the "basic.transform" spell, you can switch between multiple HTMLs. The HTML is loaded and applied in the same manner as initialization. Pass a skin name to switch for the spell argument.
this.cast("basic.transform", {"skinName": "skin2"});
The "basic.transform" spelling is also used to load and apply the default HTML at initialization.
If you want to switch between HTMLs, you need to write the settings for the target skin in the "skin.skins" section of the settings in advance.
_getSettings()
{
return {
"skin": {
"skins": {
"skin2": {
"type": "HTML",
"HTML": ""
},
}
}
}
}
=====Shadow DOM=====
BitsmistJS allows for either "open" or "closed" Shadow DOM to be applied to each unit, making each unit more independent. SkinPerk handles the application of Shadow DOM.
Shadow DOM is a standard Javascript technology. For more information, see
* [[https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM|Using shadow DOM - Mozilla Developer]]
Shadow DOM is not used by default. If you want to use Shadow DOM, you must put it in your settings.
_getSettings()
{
return {
"skin": {
"options": {
"shadowDOM": "open",
},
}
}
}
You can specify "open" or "closed".
When using Shadow DOM, the CSS structure must be carefully designed; see also the StylePerk configuration for handling CSS.
* [[en:bitsmist-js-core:unit:css#settings|Unit Explained - CSS - Settings]]