Class: ConfigClient

Methods

addListener

(params, fn, cb)

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

Name	Type	Description
params		Name Type Description field
fn	ListenerFunction
cb	undefined | Type Literal	optional Callback to be invoked after the listener is added. Name Type Description N/A Type Literal

Example

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

addListeners

(params, fn, cb)

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

Name	Type	Description
params	ListenerParam[] | string[]	Name Type Description ListenerParam Name Type Description field string listener fn
fn	ListenerFunction
cb	undefined | Type Literal	optional Callback to be invoked after the listeners are added. Name Type Description N/A Type Literal

Example

var 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);

getManifest

(cb)

Retrieves the entire manifest

Name	Type	Description
cb	StandardErrorCallback	optional

Example

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

getPreferences

(cb)

Retrieves all of the preferences set for the application.

Name	Type	Description
cb	StandardErrorCallback	optional

Example

FSBL.Clients.ConfigClient.getPreferences((err, preferences)=> {
		 if (!err) {
		 	console.log(preferences); // an object containing the entire user preferences.
		 }
});
const {err, data} = await FSBL.Clients.ConfigClient.getPreferences();

getValue

(params, cb)

Get a value from the config.

Name	Type	Description
params	FieldOnlyParam | string	Name Type Description FieldOnlyParam Name Type Description field string
cb	StandardErrorCallback	optional Will return the value if found.

Example

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');

getValues

(fields, cb)

Get multiple values from the config.

Name	Type	Description
fields	FieldOnlyParam[] | string[] | null	optional An array of field objects. Name Type Description FieldOnlyParam Name Type Description field string
cb	StandardErrorCallback	optional Will return the value if found. Deprecated functionality: If there are no fields provided, the complete configuration manifest is returned (use getManifest()).

Example

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']);

processAndSet

(params, cb)

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.

Name	Type	Description
params		Name Type Description newConfig Record 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. 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. 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	optional

Example

// 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);
		});
});

removeListener

(params, fn, cb)

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

Name	Type	Description
params		Name Type Description field
fn	ListenerFunction
cb	Function	optional Returns true if it was successful in removing the listener.

Example

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

removeListeners

(params, fn, cb)

Remove an array of listeners from the config

Name	Type	Description
params	ListenerParam | ListenerParam[]	Name Type Description ListenerParam Name Type Description field string listener fn
fn	ListenerFunction
cb	StandardErrorCallback	optional Returns true if it was successful in removing the listener.

Example

var 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) { });

removeValue

(field, cb)

Remove a value from the config.

Name	Type	Description
field	String	Name of field to remove
cb	StandardErrorCallback	optional Returns an error if there is one

Example

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

removeValues

(params, cb)

Removes multiple values from the config.

Name	Type	Description
params	FieldAndValueParam[] | string[]	Name Type Description FieldAndValueParam Name Type Description field string value any
cb	StandardErrorCallback	optional Returns an error if there is one.

Example

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

setPreference

(params, cb)

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

Name	Type	Description
params	FieldAndValueParam	Name Type Description field string value any optional
cb	StandardErrorCallback	optional

Example

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"});

setValue

(params, cb)

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

Name	Type	Description
params	FieldAndValueParam	Name Type Description field string value any optional
cb	StandardErrorCallback	optional Optional callback

Example

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

setValues

(fields, cb)

This will set multiple values in the config.

Name	Type	Description
fields	FieldAndValueParam[] | string[]	Name Type Description params FieldAndValueParam Name Type Description field string value any
cb	StandardErrorCallback	optional Optional callback

Example

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

unsetPreference

(params, cb)

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

Name	Type	Description
params	FieldOnlyParam	Name Type Description field string
cb	StandardErrorCallback	optional

Example

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