Class: ConfigClient

Config Client

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

new ConfigClient
()
clients/configClient.js, line 24

Methods

addListener
(params, fn, cb)
clients/configClient.js, line 190

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 Object

Params object

Name Type Description
field String optional

The data field to listen for. If this is empty it listen to all changes of the store.

fn function

the function to call when a listener is triggered

cb function optional

callback

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

addListeners
(params, fn, cb)
clients/configClient.js, line 229

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

TODO
  • make the typing proper.
Name Type Description
params Object | Array.<Object>

Params object

params[].field String

The data field to listen for.

params[].listener String

the function to call when a listener is triggered. If this is empty, fn is used.

fn function optional

the function to call when a listener is triggered

cb function optional
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);

getPreferences
(params, callback)
clients/configClient.js, line 551

Retrieves all of the preferences set for the application.

Name Type Description
params Object

parameters to pass to getPreferences. Optional. Defaults to null.

callback function

callback to be invoked when preferences have been retrieved from the service.

Example
FSBL.Clients.ConfigClient.getPreferences((err, preferences)=>{
		//use preferences.
});

getValue
(params, cb){any}
clients/configClient.js, line 39

Get a value from the config.

Name Type Description
params Object | String

Params object. This can also be a string

Name Type Description
field String

The field where the value is stored.

cb function

Will return the value if found.

Returns:
Type Description
any
  • The value of the field. If no callback is given and the value is local, this will run synchronous
Example
FSBL.Clients.ConfigClient.getValue({field:'field1'},function(err,value){});
 FSBL.Clients.ConfigClient.getValue('field1',function(err,value){});

getValues
(fields, cb){Object}
clients/configClient.js, line 67

Get multiple values from the config.

Name Type Description
fields Array.<Object> | Array.<String>

An array of field objects. If there are no fields proviced, the complete configuration manifest are returned.

fields[].field String

The name of the field

cb function optional

Will return the value if found.

Returns:
Type Description
Object
  • returns an object of with the fields as keys.If no callback is given and the value is local, this will run synchronous
Example
FSBL.Clients.ConfigClient.getValues([{field:'field1'},{field2:'field2'}],function(err,values){});
	FSBL.Clients.ConfigClient.getValues(['field1','field2'],function(err,values){});
	FSBL.Clients.ConfigClient.get(null, callback); // returns the complete manifest containing the finsemble property

processAndSet
(params, cb)
clients/configClient.js, line 502

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.)

Special 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.

Special 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.

Name Type Description
params object
Name Type Description
newConfig object

provides the configuration properties to add into the existing configuration under manifest.finsemble. This config must match the Finsembe config requirements as described in Understanding Finsemble's Configuration. It can include importConfig references to dynamically fetch additional configuration files.

overwrite boolean optional

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 optional

true specifies any component or service definitions in the new config will place all existing non-system component and service configuration

cb function optional

callback to be invoked upon task completion.

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)
clients/configClient.js, line 275

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

Name Type Description
params Object

Params object

Name Type Description
field String optional

The data field

fn function optional

the function to remove from the listeners

cb function optional

returns true if it was succesfull in removing the listener.

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

removeListeners
(params, fn, cb)
clients/configClient.js, line 312

Remove an array of listeners from the config

Name Type Description
params Object | Array.<Object>

Params object

Name Type Description
field String

The data field to listen for. If this is empty it listen to all changes of the store.

listener function

The listener function

fn function optional

the function to remove from the listeners

cb function optional

returns true if it was succesfull 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
(params, cb)
clients/configClient.js, line 137

Remove a value from the config.

Name Type Description
params Object | String

Either an object or string

param.field String

The name of the field

cb function optional

returns an error if there is one

Example
FSBL.Clients.ConfigClient.removeValue({field:'field1'},function(err,bool){});

removeValues
(params, cb)
clients/configClient.js, line 157

Removes multiple values from the config.

Name Type Description
params Array.<Object>

An Array of field objects

cb function optional

returns an error if there is one.

Example
FSBL.Clients.ConfigClient.removeValue({field:'field1'},function(err,bool){});

setPreference
(params, callback)
clients/configClient.js, line 534

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 Object

Params object

Name Type Description
field String

The name of the field where data will be stored

value any

Value to be stored

callback function

callback to be invoked when preferences have been retrieved from the service.

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

setValue
(params, cb){null}
clients/configClient.js, line 96

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

Name Type Description
params Object

Params object

Name Type Description
field String

The name of the field where data will be stored

value any

Value to be stored

cb function optional

optional callback

Returns:
Type Description
null
Example
FSBL.Clients.ConfigClient.setValue({field:'field1',value:"new value"});

setValues
(fields, cb){null}
clients/configClient.js, line 117

This will set multiple values in the config.

Name Type Description
fields Object

An Array of field objects

Name Type Description
field String

The name of the field

value any

Field value

cb function optional

optional callback

Returns:
Type Description
null
Example
FSBL.Clients.ConfigClient.setValues([{field:'field1',value:"new value"}]);