Module: ConfigClient

This client provides run-time access to Finsemble's configuration. The Config Client functions similar to a global store created with the Distributed Store Client and offers many of the same methods. Values modified at runtime are not persisted.

See the Configuration tutorial for a configuration overview.

Type Aliases

FieldAndValueParam

Ƭ FieldAndValueParam: Object

Type declaration

Name	Type
field	string
value?	any

---

FieldAndValueParams

Ƭ FieldAndValueParams: FieldAndValueParam[] | string[]

---

FieldOnlyParam

Ƭ FieldOnlyParam: Object

Type declaration

Name	Type
field	string

---

ListenerParam

Ƭ ListenerParam: Object

Type declaration

Name	Type
field	string
listener	ListenerFunction

---

RemoveListenersType

Ƭ RemoveListenersType: ListenerParam | ListenerParam[]

Functions

addListener

▸ addListener<T>(params, fn, cb?): Promise<void>

Add a listener to the config at either the root config level or field level. If no field is given, the root config level is used. You can also listen for changes to config fields any number of levels deep -- finsemble.configitem.deeperconfigitem.evendeeperconfigitem

let myFunction = function(err,data){};
FSBL.Clients.ConfigClient.addListener({ field:'field1' }, myFunction, cb);

Type parameters

Name	Type
T	any

Parameters

Name	Type	Description
params	Object	-
params.field	null | string	-
fn	ListenerFunction<T>	The function to be called when the observed piece of config is modified.
cb?	() => void	Callback to be invoked after the listener is added.

Returns

Promise<void>

---

addListeners

▸ addListeners<T>(params, fn, cb?): undefined | Promise<void>

Add an array of listeners as objects or strings. If using strings, you must provide a function callback as the second parameter.

let myFunction = function(err,data){}
FSBL.Clients.ConfigClient.addListeners(
    [
        { field: "field1", listener: myFunction },
        { field: "field2", listener: myFunction }
    ],
    null,
    cb
);

FSBL.Clients.ConfigClient.addListeners(
[{ field: "field1" }, { field: "field2", listener: myFunction }],
myFunction,
cb
);

FSBL.Clients.ConfigClient.addListeners(["field1", "field2"], myFunction, cb);

Type parameters

Name	Type
T	any

Parameters

Name	Type	Description
params	string[] | ListenerParam[]
fn	ListenerFunction<T>	The function to be called when the observed piece of config is modified.
cb?	() => void	Callback to be invoked after the listeners are added.

Returns

undefined | Promise<void>

---

getManifest

▸ getManifest(cb?): StandardPromise<Manifest>

Retrieves the entire manifest

FSBL.Clients.ConfigClient.getManifest(function(err, value){ });
const {err, data} = await FSBL.Clients.ConfigClient.getManifest();

Parameters

Name	Type
cb?	StandardErrorCallback<Manifest>

Returns

StandardPromise<Manifest>

---

getPreferences

▸ getPreferences(cb?): StandardPromise<null | Record<string, any>>

Parameters

Name	Type
cb?	StandardErrorCallback<null | Record<string, any>>

Returns

StandardPromise<null | Record<string, any>>

---

getValue

▸ getValue<T>(params, cb?): StandardPromise<T>

Get a value from the config.

FSBL.Clients.ConfigClient.getValue({ field:'field1' }, function(err,value){ });
FSBL.Clients.ConfigClient.getValue('field1', function(err,value){ });
const {err, data} = await FSBL.Clients.ConfigClient.getValue({ field:'field1' });
const {err, data} = await FSBL.Clients.ConfigClient.getValue('field1');

Type parameters

Name	Type
T	any

Parameters

Name	Type	Description
params	string | FieldOnlyParam	-
cb?	StandardErrorCallback<T>	Will return the value if found.

Returns

StandardPromise<T>

---

getValues

▸ getValues<T>(fields?, cb?): StandardPromise<Record<string, T>>

Get multiple values from the config.

Deprecated functionality: If there are no fields provided, the complete configuration manifest is returned (use getManifest()).

FSBL.Clients.ConfigClient.getValues(['field1','field2'], function(err,values){ });
FSBL.Clients.ConfigClient.getValues(null, callback); // returns the complete manifest containing the finsemble property
const {err, data} = await FSBL.Clients.ConfigClient.getValues(['field1', 'field2']);

Type parameters

Name	Type
T	any

Parameters

Name	Type	Description
fields?	null | string[] | FieldOnlyParam[]	An array of field objects.
cb?	StandardErrorCallback<Record<string, T>>	Will return the value if found.

Returns

StandardPromise<Record<string, T>>

---

processAndSet

▸ processAndSet(params, cb?): StandardPromise<Manifest>

Dynamically set config values within the Finsemble configuration. New config properties may be set or existing ones modified. Note that configuration changes will not necessarily dynamically modify the components or services that use the corresponding configuration -- it depends if the component or service handles the corresponding change notifications (either though PubSub or the config's DataStore). Also, these changes do not persist in any config files.

Note: Anytime config is set using this API, the newConfig along with the updated manifest will by published to the PubSub topic "Config.changeNotification". To get these notifications any component or service can subscribe to the topic. An example is shown below.

Note: Anytime config is set using this API, the dataStore underlying configuration 'Finsemble-Configuration-Store' will also be updated. To get these dataStore events a listener can be set as shown in the example below. However, any config modifications made directly though the DataStore will not result in corresponding PubSub notifications.

Caution: During dynamic configuration, Finsemble can overwrite components already in the configuration when ConfigClient.processAndSet is called. To prevent this from happening, set manifest.component.category = "system" in the config of the component. This setting is used, for example, to prevent system UI components from being dropped out of the config.

// Examples using processAndSet()
FSBL.Clients.ConfigClient.processAndSet({ newConfig: { myNewConfigField: 12345 }, overwrite: false });
FSBL.Clients.ConfigClient.processAndSet(
{
    newConfig: {
        "myNewConfigField": 12345,
        "myNewConfigObject": {
            A: "this is a test",
            B: "more test"
        },
        "importConfig": [
            "$applicationRoot/configs/application/test.json",
        ]
    },
    overwrite: true,
 replace: false,
},
    function (err, finsemble) {
        if (err) {
            console.error("ConfigClient.set", err);
        } else {
            console.log("new finsemble config", finsemble);
        }
    }
);

 // example subscribing to PubSub to get notifications of dynamic updates
RouterClient.subscribe("Config.changeNotification", function (err, notify) {
        console.log("set notification", notify.data.newConfig, notify.data.finsemble);
    });

 // example using DataStore to get notifications of dynamic updates
DistributedStoreClient.getStore({ store: 'Finsemble-Configuration-Store', global: true }, function (err, configStore) {
        configStore.addListener({ field: "finsemble" }, function (err, newFinsembleConfig) {
            console.log("new manifest.finsemble configuration", newFinsembleConfig);
        });
});

Parameters

Name	Type	Description
params	Object
params.newConfig	Record<string, any>	Provides the configuration properties to add into the existing configuration under manifest.finsemble. This config must match the Finsemble config requirements as described in the Configuration tutorial. It can include importConfig references to dynamically fetch additional configuration files.
params.overwrite	boolean	If true then overwrite any preexisting config with new config (can only set to true when running from same origin, not cross-domain); if false then newConfig must not match properties of existing config, including service and component configuration.
params.replace	boolean	True specifies any component, app, or service definitions in the new config will place all existing non-system component and service configuration
cb?	StandardErrorCallback<QueryResponse<Manifest>>	-

Returns

StandardPromise<Manifest>

Returns the resulting manifest

---

removeListener

▸ removeListener(params, fn, cb?): void

Remove a listener from config. If no field is given, we look for a config root listener

let myFunction = function(err,data){ }
FSBL.Clients.ConfigClient.removeListener({
    field:'field1'
}, myFunction, function(err, bool){ });
FSBL.Clients.ConfigClient.removeListener(myFunction, function(err, bool){ });

Parameters

Name	Type	Description
params	Object	-
params.field	null | string	-
fn	ListenerFunction<any>	The listener to remove.
cb?	Function	Returns true if it was successful in removing the listener.

Returns

void

---

removeListeners

▸ removeListeners(params, fn?, cb?): void

Remove an array of listeners from the config

let myFunction = function(err,data){ }
FSBL.Clients.ConfigClient.removeListeners({
    field: 'field1'
}, MyFunction, function(bool){ });
FSBL.Clients.ConfigClient.removeListeners([{ field:'field1', listener: MyFunction }], function(bool){ });
FSBL.Clients.ConfigClient.removeListeners(['field1'], MyFunction, function(bool) { });

Parameters

Name	Type	Description
params	RemoveListenersType
fn?	ListenerFunction<any>	The listener to remove
cb?	StandardErrorCallback<boolean>	Returns true if it was successful in removing the listener.

Returns

void

---

removeValue

▸ removeValue(field, cb?): Promise<{ err: undefined | null | string }>

Remove a value from the config.

FSBL.Clients.ConfigClient.removeValue('field1', function(err){ });
const {err} = await FSBL.Clients.ConfigClient.removeValue('field1');

Parameters

Name	Type	Description
field	String	Name of field to remove
cb?	StandardErrorCallback<void>	Returns an error if there is one

Returns

Promise<{ err: undefined | null | string }>

---

removeValues

▸ removeValues(params, cb?): Promise<{ err: StandardError }>

Removes multiple values from the config.

FSBL.Clients.ConfigClient.removeValues(['field1'], function(err){ });
const {err} = await FSBL.Clients.ConfigClient.removeValues(['field1'])

Parameters

Name	Type	Description
params	FieldAndValueParams	An Array of field objects
cb?	StandardErrorCallback<void>	Returns an error if there is one.

Returns

Promise<{ err: StandardError }>

---

setPreference

▸ setPreference(params, cb?): StandardPromise<void>

Sets a value on the configStore and persists that value to storage. On application restart, this value will overwrite any application defaults.

FSBL.Clients.ConfigClient.setPreference({
    field: "finsemble.initialWorkspace",
    value: "Workspace 2"
}, (err, response) => {
        //preference has been set
});
const {err, data} = await FSBL.Clients.ConfigClient.setPreference({field: "finsemble.initialWorkspace", value: "Workspace 2"});

Parameters

Name	Type
params	FieldAndValueParam
cb?	StandardErrorCallback<void>

Returns

StandardPromise<void>

---

setValue

▸ setValue(params, cb?): Promise<{ err: undefined | null | string }>

Set a value in the config. Setting a value will trigger events that you can listen to using addListener().

FSBL.Clients.ConfigClient.setValue({ field:'field1', value:"new value" }, function(err){ });
const {err} = await FSBL.Clients.ConfigClient.setValue({ field:'field1', value:'new value' })

Parameters

Name	Type	Description
params	FieldAndValueParam	-
cb?	StandardErrorCallback<void>	Optional callback

Returns

Promise<{ err: undefined | null | string }>

---

setValues

▸ setValues(fields, cb?): Promise<{ err: undefined | null | string }>

This will set multiple values in the config.

FSBL.Clients.ConfigClient.setValues([{ field:'field1', value: "new value" }]);
const {err} = await FSBL.Clients.ConfigClient.setValues([{ field:'field1', value: "new value" }]);

Parameters

Name	Type	Description
fields	FieldAndValueParams	-
cb?	StandardErrorCallback<void>	Optional callback

Returns

Promise<{ err: undefined | null | string }>

---

unsetPreference

▸ unsetPreference(params, cb?): StandardPromise<void>

Reset a user preference value to default. On application restart, the application default value will be used instead of the preference.

FSBL.Clients.ConfigClient.unsetPreference({
    field: "finsemble.initialWorkspace",
}, (err, response) => {
        //preference has been unset
});
const {err, data} = await FSBL.Clients.ConfigClient.unsetPreference({field: "finsemble.initialWorkspace"});

Parameters

Name	Type	Description
params	FieldOnlyParam	The preference field to unset.
cb?	StandardErrorCallback<void>	-

Returns

StandardPromise<void>