User preferences

Definition

CMS Ametys lets you manage user preferences.

There are 2 kinds of user preferences:

  • back-office user preferences(for contributors)
  • front-office user preferences(for visitors)

How do I add user preferences?

The extension point org.ametys.runtime.plugins.core.userpref.UserPreferencesExtensionPoint allows you to define user preferences for contributors (back-office side).

The extension point org.ametys.runtime.plugins.core.userpref.UserPreferencesExtensionPoint.FO allows you to define user preferences for viewers (front-office side).

These are multiple extension points: in other words, several implementations of these extension points can be active at the same time.

A user preference is defined in the same way as a classic parameter, as described on the Parameter overview page. It has some additional information enabling it to be categorized and scheduled.
It is made up of :

  • a unique identifier
  • a wording
  • a description
  • a type: string, long, date, ...
  • a widget (optional)
  • one or more validation rules (optional)
  • a list of enumerated values (optional)
  • a group, to group several preferences under a single group
  • a number to order them

User preferences are defined in a file plugin.xml. If you need to create a new plugin file, follow the instructions on the plugin Ametys page.

Sample declaration

<extension point="org.ametys.runtime.plugins.core.userpref.UserPreferencesExtensionPoint.FO"
           class="org.ametys.runtime.plugins.core.userpref.StaticUserPreferenceProvider"
           id="demo.user.prefs.fo"> 
	<param id="title" type="string">
    	<label i18n="true">DEMO_USER_PREFS_TITLE_LABEL</label>
        <description i18n="true">DEMO_USER_PREFS_TITLE_DESC</description>
        <group i18n="true">DEMO_USER_PREFS_PERSONAL_DETAILS</group>
        <order>5</order>
        <enumeration>
        	<entry>
            	<value>mr</value>
                <label i18n="true">DEMO_USER_PREFS_TITLE_MR</label>
            </entry>
            <entry>
            	<value>mme</value>
                <label i18n="true">DEMO_USER_PREFS_TITLE_MME</label>
            </entry>    
        </enumeration>
	</param>
    <param id="lastname" type="string">
    	<label i18n="true">DEMO_USER_PREFS_LASTNAME_LABEL</label>
        <description i18n="true">DEMO_USER_PREFS_LASTNAME_DESC</description>
        <group i18n="true">DEMO_USER_PREFS_PERSONAL_DETAILS</group>
        <order>10</order>
        <validation>
        	<mandatory/>
        </validation>
	</param>
	<param id="birthday" type="date">
    	<label i18n="true">DEMO_USER_PREFS_BIRTHDAY_LABEL</label>
        <description i18n="true">DEMO_USER_PREFS_BIRTHDAY_DESC</description>
        <group i18n="true">DEMO_USER_PREFS_PERSONAL_DETAILS</group>
        <order>15</order>
   	</param>
	<param id="email" type="string">
		<label i18n="true">USER_PREFS_MAIL_LABEL</label>
        <description i18n="true">USER_PREFS_MAIL_DESC</description>
        <group i18n="true">USER_PREFS_MY_DETAILS_GROUP</group>
        <order>20</order>
        <validation>
        	<mandatory/>
            <regexp>.*@.*\..*</regexp>
        </validation>
     </param>
</extension>

Storage of user preferences

The user preference storage mode is defined by a single extension point (i.e. only one implementation can be active at a time):

  • org.ametys.runtime.plugins.core.userpref.DefaultUserPreferencesStorage for contributors' user preferences
  • org.ametys.runtime.plugins.core.userpref.DefaultUserPreferencesStorage.FO for visitors' user preferences

There are only 2 native storage implementations:

  • org.ametys.runtime.plugins.core.userpref.JdbcUserPreferencesStorage or org.ametys.runtime.plugins.core.userpref.JdbcUserPreferencesStorage.FO to store user preferences in a database. This is the default implementation.
  • org.ametys.runtime.plugins.core.userpref.EmptyUserPreferencesStorage to avoid using user preferences.

The site application generally has no user preferences (not to be confused with visitors' user preferences). This is why the "empty" implementation is generally used:

Extract from runtime file.xml site application

<extensions>
         <org.ametys.runtime.plugins.core.userpref.DefaultUserPreferencesStorage>org.ametys.runtime.plugins.core.userpref.EmptyUserPreferencesStorage</org.ametys.runtime.plugins.core.userpref.DefaultUserPreferencesStorage>
 </extensions>

Using user preferences

Use of contributors' user preferences (back-office)

In JavaScript, the org.ametys.dao.userpref.UserPrefDAO to access the logged-in user's preference values.

Synchronous mode access

Simple user preference

var value = org.ametys.dao.userpref.UserPrefDAO.getInstance().getValue("my-user-pref");

Multivalued user preference

var values = org.ametys.dao.userpref.UserPrefDAO.getInstance().getValues("my-user-pref");

Asynchronous mode access

function cbFn1(value)
{
     alert("The user preference is " + (value || ""));
}
 
function cbFn2(values)
{
     var str = "";
     if (values != null)
     {
		if (i != 0) str += ", ";
        for (var i = 0; i < values.length; i++)
        {
			str += values[i];
		}
     }
     alert("User preferences are " + str);
}
 
org.ametys.dao.userpref.UserPrefDAO.getInstance().getValue("my-user-pref", cbFn1);
org.ametys.dao.userpref.UserPrefDAO.getInstance().getValues("my-user-pref", callbackFn);

Use of visitors' user preferences (front-office)

Visitors' user preferences are available through the "User preferences" service.

 

Back to top

Setup and integration manual