Settings
Overview
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.
Specifying 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.
In an object returned from a setting function
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.
In an independent external file
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.
In tag attribute
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>
In global settings
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.
For the details of the global settings, please refer to the dedicated section.
Priority
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):
- Tag attributes
- External files
- _getSettings() function
- 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.
Sections
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.
Section | Organizer | Description |
---|---|---|
events | EventOrganizer | Event handler settings. |
loadings molds components | LoaderOrganizer | Settings for loading components. |
organizers | OrganizerOrganizer | Settings describing which organizer is applied. |
settings | SettingOrganizer | Basic settings such as component name. |
templates | TemplateOrganizer | Settings to set an HTML string as a template. |
waitFor | StateOrganizer | Settings to wait for other componens to become a specific state. |
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.
Section | Item | Description |
---|---|---|
system | appBaseUr | A base URL for the application. |
componentPath | A base component path. | |
templatePath | A base HTML template path. |
The global settings can be overridden by the component settings.
Accessing settings
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
The settings property is a Store class.
Global settings
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.
Specifying 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/", }, });
We recommend using merge() instead of set() so that you do not remove existing settings that might be already set elsewhere.
Loading global settings
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.
Chaining to global settings
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 } }; }
Overriding global settings
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.
Accessing global settings
You can access the global settings explicitly by accessing BITSMIST.v1.settings.
console.log(BITSMIST.v1.settings.get("myValue"));