======SkinPerk======

''Inherits:Perk'' ''Section:skin'' ''Priority:210''

=====Overview=====

The SkinPerk grants the HTML-related features. The Shadow DOM is also handled by this perk.
=====Settings=====

====Format - Global====

Settings common to all units are written in the "system.skin" section of the global settings.

<code javascript>
{
    "system": {
        "skin": {
            "options": {
                "path": String,
                "shadowDOM": "open"|"close",
            }
        }
    }
}
</code>

====Format - Unit====

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

<code javascript>
{
    "skin": {
        "options": {
            "fileName": String,
            "hasSkin": Boolean,
            "path": String,
            "shadowDOM": "open"|"closed",
            "skinRef": Boolean|String,
        },
        "skins": {
            <skinName>: {
                "fileName": String,
                "HTML": String,
                "path": String,
                "rootNode": String,
                "type": "HTML"|"node"|"URL",
                "URL": String,
            },
            ...
        }
    }
}
</code>

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

Some settings can be written in tag attributes.

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

===="fileName"====

''Type:String'' ''Default:<tag name>''

The HTML file name. No extension is required. This option can be set in either "skin.options" or "skin.<skinName>", or both. 

The priority, in higher order,  is "skin.skins.<skinName>.fileName", "skin.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 "html".

----

===="hasSkin"====


''Type:Boolean'' ''Default:True''

Specifies whether the unit has HTML. if false, no HTML is loaded. However, the events related to loading, beforeTransform, doTransform, and afterTransform events will be fired even if the value is false.

----

===="HTML"====

''Type:String''

The HTML string. This is **HTML, not an HTML filename**. Used when the "type" setting is "HTML".

----

===="path"====

''Type:String''

The path to the HTML file. This option can be set in either "skin.options" or "skin.skins.<skinName>", 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 system settings are used in the following order of precedence: "system.skin.options.path", "system.unit.options.path" and unit-specific settings are used in the following order of precedence: "skin.skins.<skinName>.path", "skin.options.path", "unit.options.path".

----

===="rootNode"====

''Type:String''

The selector string that points to a specific node in the unit. The format is the same as querySelector(). The innerHTML of the node is used as the skin. Used when the "type" setting is "node".

----

===="shadowDOM"====

''Type:String'' ''Default:False''

To use Shadow DOM, specify "open" or "closed", otherwise Shadow DOM is not used. By default, Shadow DOM is not used.

----

====<skinName>====

''Type:String''

The skin name. Specify "default" for the default skin. Only one <skinName> can be applied to a unit at the same time. Specify this name when you switch to another HTML using [[en:bitsmist-js-core:reference:perk:basic-perk#transform|basic.transform]] spell.

----

===="skinRef" / bm-skinref====

''Type:Boolean|String'' ''Default:True''

The URL to the default skin file or a boolean value. If true, the file is loaded from the default URL. If false, no skin file is loaded and applied. This is the same as setting [[#hasskin|hasSkin]] option to false.

If the value for the bm-skinref 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 skin 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 skin.

----

===="type"====

''Type:String'' ''Default:"URL"''

Specifies where to get the HTML template from. Type can be "HTML", "URL", or "node". If "HTML", the HTML string is retrieved from the "HTML" setting. For "URL", the HTML file is loaded from the URL specified in the "URL" setting. For "node", the selector specified in the "rootNode" setting is used to obtain the node. For inline", the innerHTML of the unit is used as a template.

----

===="URL"====

''Type:String''

The URL of the HTML file. Used when the "type" setting is "URL".

=====Event Handlers=====

====beforeTransform====

If "skin.options.hasSkin" in the settings is True (default is True), then loads the skin using the [[#summon|summon]] spell.

The template node created in the [[#summon|summon]] skill is cloned in this event handler and set to the [[en:bitsmist-js-core:reference:perk:basic-perk#unitroot| unitRoot]] property. Until the next doTransform event, operations on the unit's skin will be performed on this clone and will not be drawn to the screen.

===Reference Settings===

  * [[#hasskin|skin.options.hasSkin]]

----

====doTransform====

If the setting "skin.options.hasSkin" is True (default is True), the skin is applied (append to unit) using [[#apply|apply]] skill.

===Reference Settings===

  * [[#hasskin|skin.options.hasSkin]]

=====Inventory=====

====skins====

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

The object that holds skin information.

Each item has the following keys:

|< 100% 180px 130px - >|
^Key^Type^Description^
|name|String|The skin name.|
|HTML|String|The skin HTML.|
|template|String|The template node created from the skin's HTML.|
|status|String|The skin loading status. The values are either ""(empty string) or "loaded".|

----

====active====

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

The object that stores the currently active skin information.

Each item has the following keys:

|< 100% 180px 130px - >|
^Key^Type^Description^
|skinName|String|The currently active skin name. Set when the [[#apply|apply]] skill is used.|

=====Skills=====

====apply====

''Type:Undefined'' ''Target:Unit''

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

===Parameters===

|< 100% 180px 130px - >|
^Parameter^Type^Description^
|skinName \\ ''Required''|String|The name of the skin to be applied.|
|clone|Node|The template to apply. If not specified, the template in [[#skins|the skin info]] is used.|

===Return Value===

Undefined.

===Exceptions===

  * If the specified skin has not yet been loaded.

=====Spells=====

====summon====

''Type:Object'' ''Target:Unit''

Loads an HTML 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 skin name.

===Parameters===

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

===Return Value===

Returns [[#skins|skin info object]] of the loaded skin.

===Reference Settings===

  * [[#path|skin.options.path]] / [[en:bitsmist-js-core:reference:perk:unit-perk#path_bm-path|unit.options.path]]
  * [[#skinref_bm-skinref|skin.options.skinRef]]
  * [[#path|skin.options.path]]
  * [[#fileName|skin.skins.<skinName>.fileName]]
  * [[#type|skin.skins.<skinName>.type]]
  * [[#html|skin.skins.<skinName>.HTML]]
  * [[#path|skin.skins.<skinName>.path]]
  * [[#rootnode|skin.skins.<skinName>.rootNode]]
  * [[#url|skin.skins.<skinName>.URL]]
  * [[#path|system.skin.options.path]] / [[en:bitsmist-js-core:reference:perk:unit-perk#path_bm-path|system.unit.options.path]]