User Preferences API

You can use the User Preferences API to get and set preference values, and to add new preferences to the Settings dialog.

Introduction to the API

This section provides an introduction to using the User Preferences API.

Obtaining a reference to the User Preferences service

The entry point to the User Preferences API is the User Preferences service. To obtain a reference to the service, use the code below:

var userPreferencesService =
  require('service!caplinps.userpreferences.user-preferences-service');

Adding a new preference to the Settings dialog

The User Preferences feature is modular and it is simple to make your own features configurable by your users.

If you want to make core features configurable by your users, please contact Caplin first as we may be able to add the required configuration to the core product.

You can add a preference to the dialog from any part of your application. The standard preferences in the Settings dialog are defined in the file default-aspect/src/caplinx/settings/UserPreferencesSettings.js.

Within the Settings dialog, preferences are arranged into sections. You specify a preference’s parent section when you add the preference.

To register a new section in the Settings dialog, call the registerSection method of the User Preferences service:

userPreferencesService.registerSection(
  'example-section',
  i18n('caplinx.user-preferences.section.example-section'),
  30
);

The new section will not be visible in the dialog until you add at least one preference to the section. This simplifies conditional registration of preferences based on user permissions. Because empty sections are not displayed, you do not need to determine if a section will have content before you register it.

To add a preference to the new section, call the registerPreference method of the User Preferences service:

var i18n = require('br/I18n');

var preferenceSpecification = {
    key: 'example-preference',
    label: i18n('caplinx.user-preferences.example-preference.label'),
    defaultValue: '1',
    control: caplinps.controls.Dropdown,
    options: [
        {
          key:'1',
          value:i18n('caplinx.user-preferences.example-preference.option.1'),
          disabled:false
        },
        {
          key:'2',
          value:i18n('caplinx.user-preferences.example-preference.option.2'),
          disabled:false
        },
        {
          key:'3',
          value:i18n('caplinx.user-preferences.example-preference.option.3'),
          disabled:false
        }
    ],
    callback: function(value, updateType) {
        doSomething();
    },
    changedLabel: i18n('caplinx.user-preferences.example-preference.changed-label')
};

userPreferencesService.registerPreference(
  'example-section',
  preferenceSpecification,
  5
);

Retrieving a preference value

To retrieve the value of a preference, use the getPreference method.

var value =
  userPreferencesService.getPreference('example-section.example-preference');

Setting a preference value

To set a new value for a preference, use the setPreference method. If the preference’s configuration includes a callback function, setPreference will call the function after setting the value.

userPreferencesService.setPreference('example-section.example-preference', '1');

API reference

The User Preferences service exposes four methods:

registerSection(sectionId, title, ordinal)

Registers a new section with the Settings dialog. The new section will not be displayed in the Settings dialog until at least one preference has been registered to the section using registerPreference.

Parameter Data Type Description

sectionId

String

A unique identifier used to refer to the section when calling registerPreference.

title

String

The title of the new section.

ordinal

Integer

[optional] The ordinal number of this section. The default value is zero. Section labels are sorted firstly by the ordinal number and secondly by their order of registration.

registerPreference(sectionId, preferenceSpecification, ordinal)

Registers a new preference under an existing section in the Settings dialog.

Parameter Data Type Description

sectionId

String

The unique identifier of an existing section. If the section cannot be found, this method logs an error to the JavaScript console.

preferenceSpecification

Object

The specification for the new preference.

See the next table: Preference specification object.

ordinal

Integer

[optional] The ordinal number of this preference. The default value is zero. Preferences are displayed in ascending order.

The preferenceSpecification parameter takes an object with the following properties:

Preference specification object
Property Data Type Description

key

String

A unique reference, used to refer to the preference when calling getPreference and setPreference.

label

String

The title to display in the dialog.

description

String

The descriptive text to display beneath the title in the dialog.

display

Boolean

Set to false to hide the preference in the dialog. Default value is true.

changedLabel

String

The text to display if the user changes the value of the preference.

As an example, the changedLabel property for the 'General > Language' preference warns the user that the change will only take effect from the next login.

defaultValue

String

The default value of the preference if the user has not set a preference.

control

Object

A reference to one of the following user interface controls:

  • caplinps.controls.Dropdown

  • caplinps.controls.Radio

Control objects can be reused between preferences. Do not create a new instance of a control object for each preference.

If you need a new user interface control, please contact Caplin as we may be able to add the control to the core product.

options

Array or Function

An array, or a reference to a function that returns an array. If options is assigned a function reference, the function will be executed each time the Settings dialog is opened.

The array can be an array of strings or an array of objects.

If the option values are the same as the display values (in all languages), then assign an array of strings.

If the option values are not the same as the display values, or some option values must be non-selectable, then assign an array of objects. Each object should have the following properties:

  • key — (string) The value of the option.

  • value — (string) The display value of the option.

  • description — (string) The description of the option. The description property is used by only the radio-button control.

  • disabled — (boolean) Set to true to render the option non-selectable.

callback

Function

A function that is called by the User Preferences Service when the value of this preference is set or updated.

The callback function is passed two parameters: value and updateType.

function(value, updateType) { ... }

Callback function parameters:

  • value — (string) The new value of the preference

  • updateType — (string) The type of the update. This can be one of three possible values:

    • 'local': the preference was set in this browser

    • 'external': the preference was set in another user session, and the new value has propagated to this session via Transformer’s Persistence Service

    • 'page_load': the preference was set on page load

getPreference(compositeKey)

Returns the value of a user preference.

Parameter Data Type Description

compositeKey

String

The composite key for the preference, comprising the section ID and the preference ID separated by a period: section_id.preference_id.

For example, in the standard Settings dialog, the composite key for the Language preference in the General section is: 'general.language'.

For the IDs of other sections and preferences in the standard settings dialog, see Preferences available in the dialog.

setPreference(compositeKey, value)

Sets a new value for a user preference. The Settings dialog automatically calls this method when a user clicks Save.

If the preference was registered with a callback function, this method will call it after setting the new value for the preference.

Parameter Data Type Description

compositeKey

String

The composite key for the preference, comprising the section ID and the preference ID separated by a period: section_id.preference_id.

For example, in the standard Settings dialog, the composite key for the Language preference in the General section is: 'general.language'.

For the IDs of other sections and preferences in the standard settings dialog, see Preferences available in the dialog.

value

String

The new value of the preference.