StylePerk

Inherits:Perk Section:style Priority:200

Overview

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

Settings

Format - Global

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,
                },
                ...
            }
        }
    }
}

Format - Unit

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

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

Format - Tag Attributes

Some settings can be written in tag attributes. 

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

"apply"

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.

"CSS"

Type:String

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

"fileName"

Type:String Default:<Tag Name>

The CSS file name. No extension is required. If not set, then unit.options.fileName is used. If it is not available, then the tag name is used as the file name. Loads a file with the filename + extension “css”.

"path"

Type:String

The path to the CSS file. The “system.style.options.path” and “style.options.path” 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.

<styleName>

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.

"styleRef" / bm-styleref

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.

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"

Type:String

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.

"URL"

Type:String

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

Event Handlers

doTransform

First, loads all the CSS required for the unit using summon spell. The required CSS are the styles specified in “style.options.apply” and the default styles. When loading is complete, all CSS applied to the unit is removed. After that, all loaded CSS is applied in order using apply spell.

Reference Settings

Inventory

styles

Type:Object Target:Instance

The object that holds style information.

Each item has the following keys:

KeyTypeDescription
nameStringThe style name.
CSSStringThe CSS.
statusStringThe style loading status. The values are either “”(empty string) or “loaded”.

Spells

apply

Type:Undefined Target:Unit

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

Parameters

ParameterTypeDescription
styleName
Required		StringThe name of the style to be applied.

Return Value

Undefined.

Exceptions

  • If the specified style has not yet been loaded.

summon

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.

Parameters

ParameterTypeDescription
styleName
Required		StringThe name of the style to be loaded.
optionsObjectThis is equivalent to the settings set as a value for <styleName>.

Return Value

Returns style info object of the loaded style.

Reference Settings