HTML
Overview
Each unit has one HTML file 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 HTML are written under the “skin.skins” section using the HTML name as a key. The key name is the name specified in Switching HTML described below. Information about the default HTML 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": "<div></div>" } } } } }
For more information on SkinPerk settings, please see below.
Loading HTML
SkinPerk loads HTML in the beforeTransform event. In the event, it creates a template node based on the loaded HTML and sets it to the unitRoot property of the unit. 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. If no settings are specified, the HTML file will be loaded using the default path and file name.
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": "<div></div>" }, } } } }
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", "rootNode": "template#grid" }, } } } }
Applying HTML
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 HTML
Using the “basic.transform” spell, you can switch between multiple HTMLs. The HTML is loaded and applied in the same manner as initialization. Pass the name of the HTML to switch to for the spell argument.
this.use("spell", "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 HTML in the “skin.skins” section of the settings in advance.
_getSettings() { return { "skin": { "skins": { "skin2": { "type": "HTML", "HTML": "<div></div>" }, } } } }
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
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.