CSS

Each unit has one CSS file by default. BitsmistJS uses Constructable Stylesheets, a standard technology for applying CSS, which allows multiple structured CSS to be applied to a unit, including common CSS and CSS specific to each unit, just by writing them in the settings. It is also possible to switch between multiple CSS or to create units that use no CSS at all. These functions are handled by StylePerk.

BitsmistJS also allows you to load and apply styles using the usual <style> tags, but you can make them more componentized using Constructable Stylesheets, which is essential when using Shadow DOM.

The unit uses the “basic.transform” spell during initialization to trigger beforeTransform, doTransform, and afterTransform events. The StylePerk installs beforeTransform event handler to load and apply common CSS and, doTransform event handler to load and apply unit-specific CSS.

You can specify which CSS to load and apply in the settings and Constructable Stylesheets are automatically used. CSS settings can be divided into settings for common CSS used by multiple units and settings for unit-specific CSS.

The settings for common CSS used by multiple units are written in the “system.styles” section of the global settings. StylePerk starts loading the common CSS at its initialization (before starting to load each unit).

BITSMIST.v1.Unit.use("setting.merge", {
    "system": {
        "style": {
            "options": {
                "apply": ["reset", "common", "site"],
            },
            "styles": {
                "reset": {
                    "type": "URL",
                    "URL": "/css/reset.css",
                },
                "common": {
                    "type": "URL",
                    "URL": "/css/common.css",
                }
            }
        }
    }
}

After the common CSS have been loaded, the CSS specified by the “apply” option are applied to the document.

Unit-specific settings are written in the “style” section. The settings for StylePerk itself and common CSS to be applied are written in the “style.options” section, and settings for each CSS are written under the “style.styles” section using the CSS name as a key. The key name is the name specified in Switching CSS described below. The default CSS information is written in the “default” section. If the “default” section does not exist, the default file is loaded.

_getSettings()
{
    return {
        "style": {
            "options": {
                "styleRef": True,
                "apply": [ "common", "wrapper" ]
            },
            "styles": {
                "default": {
                    "type": "URL",
                    "rootNode": "/units/default.html"
                },
                "style2": {
                    "apply": ["common2"],
                    "type": "CSS",
                    "rootNode": "div {'background-color':'black'}"
                }
            }
        }
    }
}

Common CSS written in “styles.options.apply” will be applied no matter which CSS is used. Common CSS written in “styles.<styleName>.apply” will be applied only when switched to this CSS.

If you do not use Shadow DOM, you can also apply styles in the traditional way without using Construtable Stylesheets. Write in the settings to not use CSS and load the styles using <style> tags.

You can make sure that all units do not use CSS by putting it in the global settings.

BITSMIST.v1.Unit.use("setting.merge", {
    "style": {
        "options": {
            "styleRef": false,
        },
    }
}

StylePerk loads and applies CSS in the beforeTransform and doTransform event.

CSS can be loaded from a file or fixed CSS strings. The CSS file is loaded using the default path and file name if no settings are specified.

“system.style.options.path” and “style.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 “css” extension.

If you want to change the path or file name to be loaded, put it in the settings.

_getSettings()
{
    return {
        "style": {
            "options": {
                "path": "my-stylepath",
                "fileName": "my-stylefile",
            },
        }
    }
}

If you want to use a URL, use the skinRef option.

_getSettings()
{
    return {
        "style": {
            "options": {
                "styleRef": "https://example.com/my-stylepath/my-stylefile.css",
            },
        }
    }
}

or in the “styles.default” section.

_getSettings()
{
    return {
        "style": {
            "styles": {
                "default": {
                    "type": "URL",
                    "URL": "https://example.com/my-stylepath/my-stylefile.css",
                },
            }
        }
    }
}

If the unit has no CSS files at all, it must be written in the settings.

_getSettings()
{
    return {
        "style": {
            "options": {
                "styleRef": false,
            },
        }
    }
}

Otherwise, the unit will try to load the default CSS file and a 404 error will occur, interrupting the initialization.

By putting CSS strings in the settings, the CSS is applied to the unit. Using Webpack or similar, the HTML can be written in an external file but combined into one file

_getSettings()
{
    return {
        "style": {
            "styles": {
                "default": {
                    "type": "CSS",
                    "CSS": "div {'background-color':'black'}"
                },
            }
        }
    }
}

The loaded common CSS is applied to the unit in the beforeTransform event and unit-specific CSS in the doTransform event. Though HTML is also applied in the doTransform event, StylePerk has higher priority, and CSS is applied first. In addition, since it is applied to a node that is still in a template clone state, it prevents FOUC.

As with HTML, the “basic.transform” spell can be used to switch between multiple CSS. The CSS is loaded and applied in the same way as initialization. Pass the name of the CSS to switch to for the spell argument.

this.cast("basic.transform", {"styleName": "style2"});

If you wish to switch between CSS, you need to write the target CSS settings in the “style.styles” section of the settings in advance.

_getSettings()
{
    return {
        "style": {
            "styles": {
                "style2": {
                    "type": "CSS",
                    "HTML": "div {'background-color':'pink'}"
                },
            }
        }
    }
}