StylePerk

Inherits:Perk Section:style Priority:200

StylePerk grants the unit's style-related functions, such as loading and applying the CSS.

Settings common to all units are written in the “system.style” section of the global settings.

The CSS specified in the apply setting in the system section is loaded at Perk initialization and applied to the Document.

{
    "system": {
        "style": {
            "options": {
                "apply": [String, ...],
                "path": String,
            },
            "styles": {
                <styleName>: {
                    "apply": [String, ...],
                    "CSS": String,
                    "type": "CSS"|"URL",
                    "URL": String,
                },
                ...
            }
        }
    }
}

Unit-specific settings are written in the “style” section.

{
    "style": {
        "options": {
            "apply": [String, ...],
            "fileName": String,
            "hasStyle": Boolean,
            "path": String,
            "styleRef": Boolean|String,
        },
        "styles": {
            <styleName>: {
                "CSS": String,
                "fileName": String,
                "path": String,
                "type": "CSS"|"URL",
                "URL": String,
            },
            ...
        }
    }
}

Some settings can be written in tag attributes.

<my-unit
    bm-styleref=Empty|String|"false"
></my-unit>

Type:Array of String

The name of the CSS to be applied. If in the “system.style” section, the specified CSS is applied to the document.

Within the “style” section, you can write in the “options” section and the “styles.<styleName>” section. If written in the “options” section, it will be applied no matter which CSS is used. If it is in the “styles.<styleName>” section, it will only be applied when that CSS is used. Each CSS is applied to the unit if in Shadow DOM mode, otherwise to the document.

Note that you do not need to specify the default style here. If “style.options.styleRef” is specified, the default style for the unit is automatically applied most last even if it is not written here.

Type:String

The CSS string. This is CSS, not a CSS filename. Used when the “type” setting is “CSS”.

Type:String Default:<Tag Name>

The CSS file name. No extension is required. This option can be set in either “style.options” or “style.<styleName>”, or both.

The priority, in higher order, is “style.styles.<styleName>.fileName”, “style.options.fileName”, "unit.options.fileName". If all of them are not available, then the tag name is used as the file name.

Loads a file with the filename + extension “css”.

Type:Boolean Default:True

Specifies whether the unit has unit-specific CSS. if false, no unit-specific CSS is loaded. However, common CSS set in “style.options.apply” will be applied.

Type:String

The path to the CSS file. This option can be set in either “style.options” or “style.styles.<styleName>”, or both. The final path is the path concatenated with the path in the global settings and the path in the unit-specific settings.

The global settings are used in the following order of precedence: “system.style.options.path”, “system.unit.options.path” and unit-specific settings are used in the following order of precedence: “style.styles.<styleName>.path”, “style.options.path”, “unit.options.path”.

Type:String

The style name. Specify “default” for the default style. Only one <styleName> can be applied to a unit at the same time. Specify this name when you switch to another CSS using basic.transform spell.

Type:Boolean|String Default:True

The URL to the default style file or a boolean value. If true, the file is loaded from the default URL. If false, the default style file is loaded and applied. This is the same as setting hasStyle option to false.

If the value for the bm-styleref attribute is set, the value is used as the URL to the file, or true if no value is specified. To specify false, set the string “false”.

If the CSS file is not found, it causes a 404 error and the unit initialization stops. To avoid this, you need to set false explicitly if the unit does not have a CSS.

Type:String Default:“URL”

Specifies where to get the CSS from. Type can be “CSS” or “URL”. If “CSS”, the CSS string is retrieved from the “CSS” setting. For “URL”, the CSS file is loaded from the URL specified in the “URL” setting.

Type:String

The URL of the CSS file. Used when the “type” setting is “URL”.

In the beforeTransform event, any styles already applied to a unit are cleared first. Then common CSS are loaded using summon spell and apply loaded CSS to the unit using apply spell.

• style.options.apply

In the doTransform event, if “style.options.hasStyle” setting is True (default is True), unit-specific CSS are loaded using summon spell. The unit-specific CSS are the style specified in e.details.styleName and the styles specified in “style.styles.<styleName>.apply” setting. Those loaded CSS are applied to the unit using apply spell.

• style.options.hasStyle
• style.styles.<styleName>.apply

Type:Object Target:Instance

The object that holds style information.

Each item has the following keys:

Type:Undefined Target:Unit

Applies a style to the unit. If the specified style has already been applied, does nothing.

Undefined.

• If the specified style has not yet been loaded.

Type:Undefined Target:Unit

Loads a CSS file. Only loads, and does not apply. If it has already been loaded, it will not be loaded. If the argument “options” is not passed, it refers to the settings of the specified style name.

Returns style info object of the loaded style.

• style.options.path / unit.options.path
• style.options.path
• style.options.styleRef
• style.styless.<styleName>.fileName
• style.sytles.<styleName>.type
• style.sytles.<styleName>.CSS
• style.styles.<styleName>.path
• style.sytles.<styleName>.URL
• system.style.options.path / system.unit.options.path