Setting.getValue Action

Format

s = CS.Settings.getValue(key := ...ʃ, value := ...ʅʃ, source := ...ʅ)

Argument	Description	Types / Required
key	The key that uniquely identifies the setting.	string required
value	A value to return if the setting is not defined.	string, number, boolean, array, object not required
source	The name of the settings database. The default value is "UserSettings".	string not required

Description

The Settings.getValue action returns a value from a settings database. Using the identifier key, the setting is retrieved from a table of attribute-value pairs. A setting's value is set using Settings.putValue.

The default source database, "UserSettings", corresponds to the User Settings database used by the loadsetting function. These settings can be viewed and modified in the CSPro Designer using the User and Configuration Settings dialog. You can use a custom settings database by specifying the name of a database, which will be created automatically if it does not exist.

The file from which settings are retrieved can be modified by altering the CommonStore attribute of a PFF file. The settings are stored in a SQLite database and the settings should not be considered secure as they can accessed by other applications.

Settings from the User Settings database, but not custom databases, can also be retrieved using the loadsetting function.

Return Value

The action returns the setting using the type that it was stored in the database. For example, if Settings.putValue is used to store an array, then Settings.getValue will also return an array.

Exceptions

The action throws an exception if any of its arguments are not specified in a valid form, or if the setting does not exist and no default value is provided.

Example (CSPro Logic)

PROC FRESHWATER_BIRDS_FF

preproc

string SettingsSource = "FreshwaterBirdsSurvey";
string LanguageKey = "language";

// restore the language that was in use when the user last ran this survey, defaulting to English
string language = CS.Settings.getValue(source := SettingsSource,
key := LanguageKey,
value := "EN");
setlanguage(language);

postproc

// save the language in use
CS.Settings.putValue(source := SettingsSource,
key := LanguageKey,
value := getlanguage());

Example (JavaScript)

// save the user credentials for later use
CS.Settings.putValue({
source: "FreshwaterBirdsSurvey",
key: "credentials",
value: {
username: "GBH",
lastAccessTimestamp: new Date().getTime()
}
});

// ... at a later point, query for the saved user credentials
const credentials = CS.Settings.getValue({
source: "FreshwaterBirdsSurvey",
key: "credentials",
value: {}
});

// only use the user credentials if the date is within a day of the last access
const secondsBetweenAccess = new Date().getTime() - credentials.lastAccessTimestamp;

if( secondsBetweenAccess <= ( 24 * 60 * 60 ) ) {
// use the credentials
}