Settings

Each component has its own settings. We explain the settings here. Also, we explain the global settings that are shared between all components.

Settings are written in JSON format. Each component behaves according to those settings.

There are four locations to specify settings.

• In an object returned from a setting function.
• In an independent external file.
• In a tag attribute.
• In global settings.

Let's see the details.

Every BitsmistJS component inherits a base component. The base component has a function called _getSettings(). Overriding the function and returning an object that contains the settings configures the component.

_getSettings()
{
    return {
        "loadings": {
            "path": "common",
        },
        "settings": {
            "name": "BarMain",
        },
        "events": {
            "this": {
                "handlers": {
                    "doSetup": this.onDoSetup
                }
            }
        }
    }
}

This is the most general way of configuring a component.

Prepare settings in JSON format in an independent settings file and specify a URL to the file in bm-settingref attribute.

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

bar-header.setting.js

{
    "loadings": {
        "path": "common"
    },
    "settings": {
        "name": "BarMain",
    },
    "events": {
        "this": {
            "handlers": {
                "doSetup": "onDoSetup"
            }
        }
    }
}

A component loads the specified settings file and merges them during its initialization process. The component stops processing until it finishes loading the settings file.

You can apply tag-specific (instance-specific) settings with this method.

Write settings in bm-settings attribute in JSON format.

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

With this method also, you can specify tag-specific settings like an external setting file previously explained.

Some organizer has their own tag attribute settings. For example, LoaderOrganizer has “bm-path” attribute that specifies a path from where a component is loaded.

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

Global settings are settings that are shared among all components. By default, each BitsmistJS component's settings are linked to the global settings, that is, if a setting referred to does not exist in the component settings, the settings are automatically fetched from the global settings transparently.

The four methods explained above can be mixed. If the same settings exist in different locations, the settings will be overwritten by higher priority settings.

The priority is (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 _getSettings() function and specify tag-specific settings in the tag attribute that override the basic settings.

In BitsmistJS framework, the actual processing is done by organizers. So what settings are available depends on what organizers the component is using.

Here are the settings sections of each organizer in the core library. Please refer to the link for details. Basically, each section is handled by each organizer.

Also, we introduce the “system” section that is referenced by some organizers. These settings are basically written in Global settings which we will explain later since they affect the whole system.

To access settings, use the settings property every component has.

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

. (period) can be used for specifying sections.

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

Most of the settings are component-specific. However, you might want to share some settings among all components. We will explain the application global settings.

Loading BitsmistJS library automatically creates a Store object. By setting the values to the Store object, the values will be shared globally. You can access those settings via BITSMIST.v1.settings global variable.

In the next example, we are merging some settings to the global settings using the merge() method of the Store object.

BITSMIST.v1.settings.merge({
    "system": {
        "appBaseUrl":"https://example.com",
        "componentPath":"/components/",
    },
});

Since global settings affect the whole application, you might want to load them as early as you can, before any components are loaded.

One way to load global settings earlier is to put those settings in a file, say “settings.js”, and import the file in the HEAD using script tag (Make sure it is after BitsmistJS library).

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

By loading the global settings this way, they are available before any components begin to load.

The “settings” property has the ability to chain to another “settings” property. By default, each component's setting property is chained to the global settings, that is, BITSMIST.v1.settings Store object.

When a settings property is chained to another settings property, the setting value will be retrieved from the chained settings if the property doesn't have the item. By accessing the component local settings, you are automatically accessing the global settings (if the item exists in the global settings).

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

This chaining happens if “settings.useGlobalSettings” is set to True (which defaults to True). If you don't want to chain, set this value to false.

_getSettings()
{
    return {
        "settings": {
            "name": "bar-header",
            "useGlobalSettings": false
        }
    };
}

If a component has the same settings as the global settings, the component local settings will be returned. By specifying the same settings that are specified in the global settings, you can override the global settings.

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

There might be the case that you don't want to use the site global settings. For example, the components in a site follow the global settings like the application base URL, but the third-party component that is delivered from another server might want to have its own base URL.

You can access the global settings explicitly by accessing BITSMIST.v1.settings.

console.log(BITSMIST.v1.settings.get("myValue"));