Class: ConfigClient
Config Client (Finsemble Connect)
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.
Methods
-
addEventListener(event, handler)
-
Name Type Description event
string handler
Function -
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
fieldOnlyParam Name Type Description field
string Name of the field
fn
any The function to be called when the observed piece of config is modified.
cb
any optional Callback to be invoked after the listener is added.
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 | listenerParam[] | fieldOnlyParam | string[] Name Type Description listenerParam
Name Type Description field
string The data field to listen for.
listener
Function The function to be called when the observed piece of config is modified. If this is empty, fn is used.
listenerParam
Name Type Description field
string The data field to listen for.
listener
Function The function to be called when the observed piece of config is modified. If this is empty, fn is used.
params
fieldOnlyParam Name Type Description field
string Name of the field
fn
Function optional The function to be called when the observed piece of config is modified.
cb
Function optional Callback to be invoked after the listeners are added.
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)
-
Retrieves all of the preferences set for the application.
Name Type Description params
any optional callback
StandardCallback The callback to be invoked if the method fails.
Example
FSBL.Clients.ConfigClient.getPreferences((err, preferences)=> { //use preferences. });
-
getValue(params, cb)
-
Get a value from the config.
Name Type Description params
fieldOnlyParam | string Name Type Description params
fieldOnlyParam Name Type Description field
string Name of the field
cb
Function Will return the value if found.
Example
FSBL.Clients.ConfigClient.getValue({ field:'field1' }, function(err,value){ }); FSBL.Clients.ConfigClient.getValue('field1', function(err,value){ });
-
getValues(fields, cb)
-
Get multiple values from the config.
Name Type Description fields
fieldOnlyParam[] | string[] optional An array of field objects. If there are no fields provided, the complete configuration manifest is returned.
Name Type Description params
fieldOnlyParam Name Type Description field
string Name of the field
cb
Function Will return the value if found.
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, callback)
-
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.
Name Type Description params
Name Type Description newConfig
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.
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 or service definitions in the new config will place all existing non-system component and service configuration
callback
StandardCallback The callback to be invoked if the method fails.
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); }); });
-
removeEventListener(event, handler)
-
Removes an event listener added by addEventListener
Name Type Description event
any An event that was used with addEventListener to add a listener
handler
any The handler that was used with addEventListener for the event
-
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
fieldOnlyParam Name Type Description field
string Name of the field
fn
Function The listener to remove.
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(bool){ }); FSBL.Clients.ConfigClient.removeListener(MyFunction, function(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 The data field to listen for.
listener
Function The function to be called when the observed piece of config is modified. If this is empty, fn is used.
listenerParam
Name Type Description field
string The data field to listen for.
listener
Function The function to be called when the observed piece of config is modified. If this is empty, fn is used.
fn
Function optional The listener to remove
cb
Function 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(params, cb)
-
Remove a value from the config.
Name Type Description params
fieldAndValueParam Name Type Description field
string Name of the field
value
any optional Value of the field
cb
Function Returns an error if there is one
Example
FSBL.Clients.ConfigClient.removeValue({ field:'field1' }, function(err,bool){ });
-
removeValues(params, cb)
-
Removes multiple values from the config.
Name Type Description params
fieldAndValueParam[] | string[] Name Type Description params
fieldAndValueParam Name Type Description field
string Name of the field
value
any Value of the field
cb
Function Returns an error if there is one.
Example
FSBL.Clients.ConfigClient.removeValues([{ field:'field1' }], function(err,bool){ });
-
setPreference(params, callback)
-
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 Name of the field
value
any optional Value of the field
callback
StandardCallback The callback to be invoked if the method fails.
Example
FSBL.Clients.ConfigClient.setPreference({ field: "finsemble.initialWorkspace", value: "Workspace 2" }, (err, response) => { //preference has been set });
-
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 Name of the field
value
any optional Value of the field
cb
any optional Optional callback
Example
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 Name of the field
value
any Value of the field
cb
any optional Optional callback
Example
FSBL.Clients.ConfigClient.setValues([{ field:'field1', value: "new value" }]);