Introduction to User Preferences

01/10/2008 15:18 by Sten Roger Sandvik

In this article I will briefly describe the user preferences feature that is implemented in Vertical Site 4.3. I will illustrate how to use this in datasources, userservices and the Java API.

Introduction to User Preferences

User preferences is a set of key/value pairs that is bound to a user. This means that Anonymous user does not have any user preferences. All preference values is persistent and therefore durable between restarts. User preferences can be accessed in three different ways:

• DataSource methods (only getting values)
• DataSource expression language function (only getting values)
• User services (setting and getting values)
• Java client API (setting and getting values)

In this article I will describe all of the access methods. The first methods requires basic html and Vertical Site knowledge and the last one also requires some basic Java knowledge.

What is a scope?

All of the user preference accessing methods require a scope. A scope is where the preference value will be visible. The following scopes are available:

• global - visible for a single user on any sites.
• site - visible for a single user on a single site.
• page - visible for a single user on a single page.
• portlet - visible for a single user on a single portlet (also known as object) on any pages.
• window - visible for a single user on a single portlet within a single page.

So, to sum it up: the first is least restricted scope and the last is most restricted scope.

DataSource methods

So, to start of with something basic we will see how you can use this inside Vertical Site datasources. This can be done with the getPreferences datasource method. The method can retrieve a single value, all values or all values with keys based on a pattern.

To retreive all preferences for the logged in user:

<datasource>
  <methodname>getPreferences</methodname>
  <parameters>
  </parameters>
</datasource>

Also, to get all preferences with a specified scope:

<datasource>
  <methodname>getPreferences</methodname>
  <parameters>
    <parameter>page</parameter>
  </parameters>
</datasource>

The last thing we can do is to retrieve values based on a pattern within a specified scope.

<datasource>
  <methodname>getPreferences</methodname>
  <parameters>
    <parameter>global</parameter>
    <parameter>sendNewsLetter</parameter>
  </parameters>
</datasource>

You have not any setter methods in datasources. To set a user preference values we need to use either user services or Java plugins.

DataSource expression language

To retrieve preference values we can also use expression language functions inside datasources. The pref expression language function is implemented to allow retrieval of user preference values inside datasources. It takes two parameters: scope and key. The scope is user preference scope and key is any value you decide as will be the key.

Example datasource that uses a user preference:

<datasource>
  <methodname>someMethod</methodname>
  <parameters>
    <parameter>${pref("site", "some.key")}</parameter>
  </parameters>
</datasource>

If a preference value does not exist it will return an empty value. So combining the select function with the pref function will make the value retrieval more robust.

<datasource>
  <methodname>someMethod</methodname>
  <parameters>
    <parameter>${select(pref("site", "some.key"), "default")}</parameter>
  </parameters>
</datasource>

User Services

Using the user services you can set and delete user preferences. This is used using the user handler with operations setpreferences and deletepreferences.

To set preference values you use the following base url:

_services?_handler=user&_op=setpreferences&

All other parameters on the url is interpreted as scope.key. To illustrate this I will set the two global user preference values sendNewsLetter and useHtmlMail. The resulting URL is now:

_services?_handler=user&_op=setpreferences&global.sendNewsLetter=true&global.useHtmlMail=false

If I want to delete some preferences I use the following base url:

_services?_handler=user&_op=deletepreferences&

So, to illustrate this I would like to delete the two keys I set in the previous example. This is done by appending preferenceKey parameter to the url:

_services?_handler=user&_op=deletepreferences&preferenceKey=global.sendNewsLetter&global.useHtmlMail

To simplify the URL creation we would recommend using createServicesUrl in your XSLT templates. Using this function would like to generate the URLs like this:

portal:createServicesUrl("user", "setpreferences", "myRedirectUrl", 
  ("global.sendNewsLetter", "true", "global.useHtmlMail", "false"))

Java Client API

To top this off I would like to describe the Java API methods that can be used. This can be used both in plugins and in standalone applications using the remote API. We can get, set and delete preferences using this API. All the methods will use the currently loggeed in user and will only work for a logged in user.

To retreive the preferences we have two methods. One that retrieves all preference values for a user and one that returns one preference. The following example finds all preference values:

for (Preference pref : client.getPreferences()) {
  System.out.println("key = " + pref.getKey());
  System.out.println("Value = " + pref.getValue());
  System.out.println("Scope = " + pref.getScope());
}

To retreive only one:

GetPreferenceParams params = new GetPreferenceParams();
params.scope = PreferenceScope.createSite(3);
params.key = "sendNewsLetter";

Preference pref = client.getPreference(params);
if (pref != null) {
  System.out.println("Value = " + pref.getValue());
}

We have also implemented a method to set a single preference. This can be done like this:

SetPreferenceParams params = new SetPreferenceParams();
params.scope = PreferenceScope.createGlobal();
params.key = "sendNewsLetter";
params.value = "true";

client.setPreference(params);

And to delete the same preference:

DeletePreferenceParams params = new DeletePreferenceParams();
params.scope = PreferenceScope.createGlobal();
params.key = "sendNewsLetter";

client.deletePreference(params);

We can use the same API methods in all of our plugin types (for example FunctionLibraryPlugin) and in the remote client.