Les préférences utilisateurs

Définition

Le CMS Ametys permet de gérer des préférences utilisateurs.

Il existe 2 sortes de préférences utilisateurs :

  • les préférences utilisateurs du back-office (pour les contributeurs)
  • les préférences utilisateurs du front-office (pour les visiteurs)

Comment ajouter des préférences utilisateurs ?

Le point d'extension org.ametys.runtime.plugins.core.userpref.UserPreferencesExtensionPoint permet de définir des préférences utilisateur pour les contributeurs (coté back-office).

Le point d'extension org.ametys.runtime.plugins.core.userpref.UserPreferencesExtensionPoint.FO permet de définir des préférences utilisateur pour les visteurs (coté front--office).

Il s'agit de points d'extension multiples: c'est à dire que plusieurs implémentations de ces points d'extension peuvent être actives au même moment.

Une préférence utilisateur est définie de la même manière qu'un paramètre classique comme cela est décrit dans la page Généralités sur les paramètres. Elle possède quelques informations supplémentaires permettant de la catégoriser et de l'ordonnancer.
Elle est composée de :

  • un identifiant unique
  • un libellé
  • une description
  • un type : string, long, date, ...
  • un widget d'édition (optionnel)
  • une ou des règles de validation (optionnelles)
  • une liste de valeurs énumérée (optionnelle)
  • un groupe, permettant de grouper plusieurs préférences sous un même groupe
  • un chiffre permettant de les ordonner

Les préférences utilisateurs sont définies dans un fichier plugin.xml. Au besoin, vous serez amené à créer un nouveau plugin, suivez alors les instructions de la page Architecture d'un plugin Ametys.

Exemple de déclaration

<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>

Stockage des préférences utilisateurs

Le mode de stockage des préférences utilisateurs est défini par un point d'extension simple (c'est à dire qu'une seule implémentation peut être active à la fois):

  • org.ametys.runtime.plugins.core.userpref.DefaultUserPreferencesStorage pour les préférences utilisateurs des contributeurs
  • org.ametys.runtime.plugins.core.userpref.DefaultUserPreferencesStorage.FO pour les préférences utilisateurs des visiteurs

Il existe nativement que 2 implémentations de stockage :

  • org.ametys.runtime.plugins.core.userpref.JdbcUserPreferencesStorage ou org.ametys.runtime.plugins.core.userpref.JdbcUserPreferencesStorage.FO pour stocker les préférences utilisateurs en base de données. Il s'agit de l'implémentation par défaut.
  • org.ametys.runtime.plugins.core.userpref.EmptyUserPreferencesStorage pour ne pas utiliser de préférences utilisateurs.

L'application site ne possède généralement pas de préférences utilisateurs (ne pas confondre avec les préférences utilisateurs des visiteurs). C'est donc l'implémentation "vide" qui est généralement utilisée:

Extrait du fichier runtime.xml de l'application site

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

Utilisation des préférences utilisateurs

Utilisation des préférences utilisateurs des contributeurs (back-office)

En JavaScript, la classe org.ametys.dao.userpref.UserPrefDAO permet d'accéder aux valeurs des préférences de l'utilisateur connecté.

Accès mode synchrone

Préférence utilisateur simple

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

Préférence utilisateur multivaluée

var values = org.ametys.dao.userpref.UserPrefDAO.getInstance().getValues("my-user-pref");
Accès mode asynchrone
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);

Utilisation des préférences utilisateurs des visiteurs (front-office)

Les préférences utilisateurs des visiteurs sont utilisables au travers du service "Préférences utilisateur"