======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.

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

====Format - Unit====

Unit-specific settings are written in the "style" section.

<code javascript>
{
    "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,
            },
            ...
        }
    }
}
</code>

====Format - Tag Attributes====

Some settings can be written in tag attributes.

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

===="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. 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", [[ja:bitsmist-js-core:reference:perk:unit-perk#filename_bm-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".

----

===="hasStyle"====

''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.

----


===="path"====

''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".

----

====<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 [[en:bitsmist-js-core:reference:perk:basic-perk#transform|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. This is the same as setting [[#hasstyle|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"====

''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.

----

===="URL"====

''Type:String''

The URL of the CSS file. Used when the "type" setting is "URL".
=====Event Handlers=====

====beforeTransform====

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

===Reference Settings===

  * [[#apply|style.options.apply]]

----

====doTransform====

In the doTransform event, if "style.options.hasStyle" setting is True (default is True), unit-specific CSS 
 are loaded using [[#summon|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 [[#apply1|apply]] spell. 

===Reference Settings===

  * [[#hasstyle|style.options.hasStyle]]
  * [[#apply|style.styles.<styleName>.apply]]



=====Inventory=====

====styles====

''Type:Object'' ''Target:Instance''

The object that holds style information.

Each item has the following keys:

|< 100% 180px 130px - >|
^Key^Type^Description^
|name|String|The style name.|
|CSS|String|The CSS.|
|status|String|The 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===

|< 100% 180px 130px - >|
^Parameter^Type^Description^
|styleName \\ ''Required''|String|The 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===

|< 100% 180px 130px - >|
^Parameter^Type^Description^
|styleName \\ ''Required''|String|The name of the style to be loaded.|
|options|Object|This is equivalent to [[#format_-_unit|the settings set as a value]] for <styleName>.|

===Return Value===

Returns [[#styles|style info object]] of the loaded style.

===Reference Settings===

  * [[#path|style.options.path]] / [[en:bitsmist-js-core:reference:perk:unit-perk#path_bm-path|unit.options.path]]
  * [[#path|style.options.path]]
  * [[#styleref_bm-styleref|style.options.styleRef]]
  * [[#fileName|style.styless.<styleName>.fileName]]
  * [[#type|style.sytles.<styleName>.type]]
  * [[#css|style.sytles.<styleName>.CSS]]
  * [[#path|style.styles.<styleName>.path]]
  * [[#url|style.sytles.<styleName>.URL]]
  * [[#path|system.style.options.path]] / [[en:bitsmist-js-core:reference:perk:unit-perk#path_bm-path|system.unit.options.path]]