|
In essence, a preference management mechanism is a means of maintaining a user's preferences as a collection of name-value pairs. The new preference manager provides this ability, and in addition, it offers several features directed at making the designer's task easier.
|
|
|
|
Basic concepts.
|
|
Instead of treating preferences as an amorphous collection of name-value pairs, the preference manager enables the application designer to organize preferences into
preference groups. Each preference group is given a name, and contain zero or more preference names and corresponding values. A group can also contain other preference groups, and this nesting can be arbitrarily deep. In effect, the designer can organize preferences as a tree, with the top level group corresponding to the tree's root, the contents of that group being the root's children, and so forth. Here is a diagram illustrating an example. (By convention, the root has no name, so we omit it in the diagram.)
|
| |
|
|
| In this diagram, we have organized the preferences into two top-level groups named
general and look and feel. The former group has two values, and the latter group has two subgroups that contain values. |
|
| Given this organization, the preferences manager can be used to perform the following functions.
|
|
| Extracting a preference value. |
|
You can create
a UDM node that uses this data port, with data type item. If you then specify the
preferencesInXml
parameter appropriately (to retrieve the passive form of the above preferences), and specify the
preferenceName
parameter as general.email
address, the data port will return the string
Sam Colwell as the value attribute. So you can use the sequence of names beginning from the topmost group, separated by the dot character '.', to specify a preference name. Note that this means that you cannot use the dot character as part of a preference name or a group name. |
In some cases, you might want to maintain a list of strings as the value of a preference. In the above example, the preference
general.look and
feel.account view.shown
nodes in order is one such. If you wish to break down the value into a list of strings, you can create a list node with this data port, using the
itemValueAsCSVList
data type. This will give you the individual strings in the comma-separated list, in the correct order. (You could, of course, use the string splitter port or the CSV reader port to achieve a similar effect.) |
|
|
|
Listing all contained
preferences
|
|
To list all the contained preferences in a particular group, you create a list node that uses this data port, with data type item, and provide the full name of that group as the
preferenceName
parameter. The returned list will contain the names and values of all contained preferences in the group and all its contained groups. For instance, with the preference set shown above, if you specify
look and feel
as the group name, you will obtain a list containing five values, corresponding to the five items in the two subgroups contained in
look and feel.
|
|
|
|
Adding a new preference |
|
You can add a new preference via a UDM node that carries insert mode. To add a preference, you must specify the full name of the preference relative to the group in which it will be contained. For example, with the above set of preferences, it you add a preference named
foo.bar.glarch
to the preference group account
view, the new groups
foo and
bar will be automatically created.
|
|
Removing a preference |
|
You can remove a preference name and its associated value via a UDM node that has delete mode. Removing a preference group will remove all its contained subgroups as well as contained values. |
|
|
|
Caveats |
|
Preference names and group names cannot include the dot character. This constraint must be enforced via the user interface for maintaining preferences. |
|
|
