Settings

Each unit operates according to its settings described in JSON or Javascript object format. There are two types of settings: global settings for all units and settings specific to each unit. Unit settings and global settings are linked, so that settings not found in the unit settings are automatically obtained from the global settings. The settings are stored in “setting” asset.

This page describes the settings.

There are four ways to specify a unit's settings.

• Return the Settings Object in _getSettings().
• Load from the External File.
• Specify in Tag Attributes.
• Specify in Global Settings.

Every BitsmistJS unit has a method called _getSettings(). Overriding the method and returning an object that contains the settings configures the unit.

_getSettings()
{
    return {
        "setting": {
            "options": {
                "path": "common",
            }
        },
        "event": {
            "events": {
                "this": {
                    "handlers": {
                        "doSetup": this.onDoSetup
                    }
                }
            }
        }
    }
}

This is the most typical way of configuring a unit.

Write the settings in JSON or Javascript Object format in an external file and specify its URL in the bm-settingsref attribute of the tag.

<bar-header bm-settingsref="https://example.com/settings/bar-header.settings.js"></bar-header>

bar-header.setting.js

{
    "setting": {
        "options": {
            "path": "common"
        }
    },
    "event": {
        "events": {
            "this": {
                "handlers": {
                    "doSetup": this.onDoSetup
                }
            }
        }
    }
}

If an external settings file is specified, the file is loaded during unit initialization and merged into the unit's settings. Initialization is suspended until the file has been loaded.

Using this method, it is possible to load different settings for different tags (instances) of the same class.

Write settings in the bm-options attribute using JSON format.

<button-link bm-options='{"title":"BitsmistJS"}'></button-link>

However, the only section you can specify here is the “options” section of the settings.

In this way, as with reading external files, different settings are possible for different tags in the same unit.

Some perks also read settings from their own attributes. For example, UnitPerk reads the attribute “bm-path” to specify the path of the unit.

<bar-header bm-autoload bm-path="common"></bar-header>

Global settings are settings shared by all units on the page. Each unit's settings are linked to the global settings. This means that when a unit refers to its own setting that does not exist, they are transparently retrieved from the global settings.

Multiple settings can be used in combination. If the same settings exist, they will be overwritten by the one with the higher priority. The order of priority is as follows (the upper the higher):

1. Tag Attributes
2. External files
3. _getSettings() function
4. Global settings

One typical way is to configure the basic settings in the _getSettings() function and specify tag-specific settings in the tag attribute that overrides the basic settings.

The actual processing of the units according to their settings is done by each perk. Therefore, what settings exist will depend on which perk is applied.

The settings are separated by sections. Each perk has its own dedicated section and its settings are written in that section.

Here is a list of the sections of each perk in the core library. Please follow the links for details on each perk's settings.

There is also a “system” section that is referenced by the various perks. Since this affects the entire system, it is usually written in Global Settings, which will be explained later.

To access the settings, use the setting asset for each unit.

this.set("setting", "value", 1);
console.log(this.get("setting", "value")); // console displays 1

. (period) can be used as a hierarchy separator.

this.set("setting", "mysection.value", 1);
console.log(this.get("setting", "value")); // console displays "undefined"
console.log(this.get("setting", "mysection.value")); // console displays 1

This section describes the global settings that are shared among all units.

Just as each unit has a setting asset, the BITSMIST.V1.Unit static class, the parent of all units, also has a setting asset. The value set in the setting asset of this Unit class becomes the global value.

The following example uses the setting.merge skill to merge settings into global settings.

BITSMIST.V1.Unit.use("skill", "setting.merge", {
    "system": {
        "options": {
            "env": "prod",
        }
    },
});

The global settings describe the system-wide settings. Without these settings, units cannot act properly, so they should be loaded as early as possible.

One way to do this, for example, is to write the above settings in a Javascript file called settings.js and load it in the HEAD tag (but after the BitsmistJS library).

<script type='text/javascript' src='/js/settings.js'></script>

This way, the global settings will take effect before the units' autoloading starts.

Setting assets can be linked to other settings. Each unit setting is linked to global settings.

When the unit's setting is linked to global settings, if the setting does not exist in the unit, it is retrieved from the linked setting. Therefore, by accessing a setting that doesn't exist in the unit's settings, the corresponding global settings are automatically retrieved if that setting exists in the global settings.

BITSMIST.v1.Unit.set("setting", "myValue", 1) // global setting
 
console.log(this.get("setting", "myValue")); // console displays 1

This can be used to apply the same settings to all units by writing the unit settings in the global settings.

BITSMIST.v1.Unit.use("setting.merge", {
    "style": {
        "options": {
            "styleRef": false,
        },
    }
}

In the above example, all units do not load unit-specific CSS.

If there is a setting in a unit that also exists in the global setting, the unit's setting takes precedence. Therefore, for units that use settings different from the global settings, setting the same items in the unit will prevent the unit from using the global settings.

BITSMIST.v1.Unit.set("setting", "myValue", 1)
console.log(this.get("setting", "myValue")); // console displays 1
 
this.set("setting", "myValue", 2)
console.log(this.get("setting", "myValue")); // console displays 2

For example, a unit on the site will follow the global settings, but a third-party unit served from a different server may want to use its own settings.

However, there are exceptions. Depending on the variable type combination of global and unit settings, setting the same item in a unit will result in a merge.

BITSMIST.v1.Unit.set("setting", "myValue", [1, 2, 3]);
this.set("setting", "myValue", 4);
 
console.log(this.get("setting", "myValue")); // console displays [1,2,3,4]

If you want to access global settings explicitly, access the setting asset in BITSMIST.v1.Unit.

console.log(BITSMIST.v1.Unit.get("setting", "myValue"));