======UnitPerk======

''Inherits:Perk'' ''Section:unit'' ''Priority:400''

=====Overview=====

UnitPerk grants functions related to loading and instantiating units, such as loading class files.
=====Settings=====

====Format - Global====

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

<code javascript>
{
    "system": {
        "unit": {
            "options": {
                "path": String,
            }
        }
    }
}
</code>

====Format - Unit====

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

The "unit.units" section lists the units to be added dynamically. The object set as the value of <unitName> is the settings for the unit to be added. All settings, including those not listed here, can be written. The values written here will be merged into the unit's settings.

<code javascript>
{
    "unit": {
        "options": {
            "adjacentPosition": "beforebegin"|"afterbegin"|"beforeend"|"afterend",
            "autoLoad": Boolean|String,
            "autoMorph": Boolean|String,
            "className": String,
            "fileName": String,
            "parentNode": String,
            "parentUnit": String,
            "path": String,
            "query": String,
            "replaceParent": Boolean,
            "syncOnAdd": String,
            "tag": String,
        },
        "units": {
            <unitName>:  {
                (unit settings)
            },
            ...
        }
    }
}
</code>

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

Some settings can be written in tag attributes.

<code html>
<my-unit
    bm-autoload=Empty|String
    bm-automorph=Empty|String
    bm-classname=String
    bm-filename=String
    bm-path=String
></my-unit>
</code>

===="adjacentPosition"====

''Type:String''

The position at which the unit is to be inserted. One of "beforebegin", "afterbegin", "beforeend", or "afterend" can be specified. The meaning is the same as the position argument of the standard insertAdjacentHTML().

----

===="autoLoad" / bm-autoload====

''Type:Boolean|String'' ''Default:False''

If set, class files for the unit will be automatically loaded. The value can be True, a URL to the unit's JS file, or a URL to an HTML file. If True, files will be loaded using the default path and filename. If a JS file is specified, the specified class file will loaded. If an HTML file is specified, the specified HTML file is loaded after morphing.

If the value is set for the bm-autoload attribute, the value is used as the URL to the file, or true if no value is specified.

----

===="autoMorph" / bm-automorph====

''Type:Boolean|String'' ''Default:"BITSMIST.v1.Unit"''

If set, instantiates a unit using a class that inherits an existing class. If a string is specified, a new class is created that extends the specified class, which is then tied to the tag. If the specified class does not yet exist, the [[#autoload_bm-autoload |autoLoad]] option must also be used to load the class at the same time. If True, the default Unit class is used.

If the value is set for the bm-automorph attribute, the value is used as the class name, or True if no value is specified.

----

===="className" / bm-classname====

''Type:String'' ''Default:(See desc)''

The class name of the unit. If not specified, the class name is the name of the tag name with the word before and after the hyphen concatenated with each word's first letter capitalized.

----

===="fileName" / bm-filename====

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

The file name of the unit without extension. If not specified, the tag name is used as the file name. 

This is used as the file name when loading HTML files, CSS files, and other files, also.

----

===="parentNode"====

''Type:String''

The node to which this unit is to be added. The node must be under the unit specified in [[#parentunit|parentUnit]]. If not specified, it will be added directly under the parent node.

----

===="parentUnit"====

''Type:String'' ''Default:this''

The parent unit to which this unit will be added. The value is the same as the target argument of the [[en:bitsmist-js-core:reference:perk:basic-perk#locate|basic.locate]] skill. If not specified, it is added to itself.

----

===="path" / bm-path====

''Type:String''

The path to the unit. The final path will be the string "system.unit.options.path" and "unit.options.path" concatenated.

This is used as the path when loading HTML files, CSS files, and other files, also.

----

===="query"====

''Type:String''

A query that is appended to the URL when retrieving a file.

----

===="replaceParent"====

''Type:Boolean'' ''Default:False''

Specifies whether to replace the parent node.

----


===="syncOnAdd"====

''Type:Boolean|String'' ''Default:False''

If True, the parent unit waits for the added unit to become "ready". If a string is specified, it waits for the added unit to be the specified status.

For the valid statuses, see [[en:bitsmist-js-core:reference:perk:status-perk#status|Reference - StatuePerk - state -status]].

----

===="tag"====

''Type:String''

The tags of the unit, including the closing tag. This value will be inserted into the HTML.

====<unitName>====

''Type:String''

The name of the unit.

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

====doApplySettings====

Loads settings from the "unit.units" section and add units using [[#materialize|materialize]] spell.

===Reference Settings===

  * [[#format_-_unit|unit.units]]

=====Inventory=====

====units====

''Type:Object'' ''Target:instance''

This object holds the units added to this unit. Each item has the following keys:

|< 100% 180px 130px - >|
^Key^Type^Description^
|object|Unit|Added units.|

=====Spells=====

====materialize====

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

Adds a new unit inside a unit. Instances of the added units will be added to the [[#units|units]] in the inventory, also. If class files need to be loaded, specify the autoLoad or autoMorph option in the settings argument. The class files are loaded using [[#summon|summon]] spell.

===Parameters===

|< 100% 180px 130px - >|
^Parameter^Type^Description^
|tagName \\ ''Required''|String|The tag name of the unit to be added.|
|settings|Object|The settings for the unit to be added. This is equivalent to [[#format_-_unit|the settings set as a value]] for <unitName>.|
|options|Object|Load options. Has the following keys:|
|  "syncOnAdd"|Boolean|Same as [[#synconadd|syncOnAdd]] setting. This one has a higher priority.|

===Return Value===

Instance of the added unit.

===Reference Settings===

  * [[#adjacentPosition|unit.options.adjacentPosition]]
  * [[#parentnode|unit.options.parentNode]]
  * [[#replaceparent|unit.options.replaceParent]]
  * [[#synconadd|unit.options.syncOnAdd]]
  * [[#tag|unit.options.tag]]

----

====materializeAll====

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

Instantiates all units that need to be loaded under the root node specified. The [[#materialize|materialize]] spell is cast to instantiate eatch unit.

===Parameters===

|< 100% 180px 130px - >|
^Parameter^Type^Description^
|rootNode \\ ''Required''|HTMLElement|The node that is the base point for loading units.|
|options|Object|Load options. Has the following keys:|
|  "waitForTags" \\ ''Default:false''|Boolean|If True, waits for all loaded units to become "ready" before going to the next process.|

===Return Value===

Undefined.

===Reference Settings===

  * [[#autoload_bm-autoload|bm-autoload]]
  * [[#automorph_bm-automorph|bm-automorph]]

----

====summon====

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

Loads the class file for the unit. After the file has been loaded, the unit can be instantiated by adding the unit's tag to the document tree. If the tag exists before loading, it will be instantiated as soon as this spell is completed.

===Parameters===

|< 100% 180px 130px - >|
^Parameter^Type^Description^
|tagName \\ ''Required''|Object|Tag name of the unit to be loaded.|
|settings|Object|Unit Settings.|

===Return Value===

Undefined.

===Reference Settings===

  * [[#autoload_bm-autoload|unit.options.autoLoad]]
  * [[#automorph_bm-automorph|unit.options.autoMorph]]
  * [[#classname_bm-classname|unit.options.className]]
  * [[#filename_bm-filename|unit.options.fileName]]
  * [[#path_bm-path|unit.options.path]] / [[#path_bm-path|system.unit.options.path]]
  * [[#query|unit.options.query]]
  * [[#splitclass_bm-split|unit.options.splitclass]]