JPlatform 10 - API des préférences utilisateurs (MemberPreference)

Certaines fonctions de JPlatform (portée par le coeur ou par les modules) proposent à l'utilisateur des options qui peuvent être persistées.

Par exemple, la nouvelle Topbar de JPlatform 10 propose le menu "Applications" dans lequel l'utilisateur peut choisir ses applications préférées et l'ordre dans lequel elles apparaissent dans le menu.

Jusqu'à présent les développeurs devaient gérer eux même un mode de stockage spécifique pour ces préférences utilisateur (ExtraDBData ou type dédié).

JPlatform 10 fournit désormais une API homogène et performante pour le stockage des préférences utilisateurs.

1. La classe MemberPreference

Les préférences sont représentées par la classe MemberPreference (dérivant de Data) dont les instances sont enregistrées dans JcmsDB.

Une MemberPreference comporte essentiellement les champs suivants :

• author : le membre sur lequel porte la préférence
• key : la clé de la préférence
• value : la valeur de la préférence

Les clés des préférences sont limitées à 255 caractères. Si une préférence utilise une clé supérieure à 255 caractères elle sera tronquée à 255 caractères.

La valeur associée à une préférence est limitée à 64 KB.

2. La classe MemberPreferenceManager

Le MemberPreferenceManager est le service (au sens DDD) permettant d'enregistrer et de lire des préférences utilisateurs.

2.1 Enregistrer une préférence

loggedMember.savePreference("jcmsplugin.myplugin.mypref", "the value of my pref");

ou bien

MemberPreferenceManager.getInstance().savePreference(loggedMember, "jcmsplugin.myplugin.mypref", "the value of my pref");

2.2 Lire une préférence

String value = loggedMember.getPreference("jcmsplugin.myplugin.mypref");

ou bien

String value = MemberPreferenceManager.getInstance().getPreference(loggedMember, "jcmsplugin.myplugin.mypref");

2.3 Récupérer toutes les préférences d'un membre

List<MemberPreference> mbrPrefList = MemberPreferenceManager.getInstance().getMemberPreferenceList(loggedMember);

3. Préférence par défaut

Il est possible de définir des préférences par défaut.

Les préférences par défaut peuvent être renseignées de 2 manières :

• par des propriétés
• par des valeurs enregistrés comme telles

3.1 Déclaration d'une préférence par défaut en propriété

Pour déclarer une préférence par défaut par propriété, il suffit de déclarer une propriété commençant par le préfixe mbrpref.

Exemple :

mbrpref.jcmsplugin.myplugin.mypref: my default value

3.2 Enregistrement d'une préférence par défaut

La méthode MemberPreferenceManager::saveDefaultPreference() permet d'enregistrer une valeur par défaut pour une clé de préférence.

MemberPreferenceManager.getInstance().saveDefaultPreference("jcmsplugin.myplugin.mypref", "my default value");

Les préférences par défaut sont enregistrées avec un auteur null. C'est ainsi que l'on distingue une préférence par défaut des préférences pour un membre.

Attention ! la méthode MemberPreferenceManager::savePreference() n'enregistrera pas une préférence par défaut si le membre fourni en paramètre est null. Il faut impérativement passer par la méthode MemberPreferenceManager::saveDefaultPreference().

3.3 Lecture d'une préférence par défaut

La méthode MemberPreferenceManager::getDefaultPreference() permet de lire une valeur par défaut pour une clé de préférence.

String defaultValue = MemberPreferenceManager.getInstance().getDefaultPreference("jcmsplugin.myplugin.mypref");

3.4 Lecture d'une préférence utilisateur avec recherche dans la valeur par défaut

Par défaut la méthode getPreference() recherche dans les préférences par défaut.

L'ordre de recherche d'une préférence est le suivant :

• Préférence enregistrée pour l'utilisateur
• Préférence par défaut enregistrée
• Préférence par défaut déclarée en propriété

Il est cependant possible de ne pas rechercher dans les valeurs par défaut en mettant à false le dernier argument de la méthode getPreference()

String value = loggedMember.getPreference("jcmsplugin.myplugin.mypref", false);

ou bien

String value = MemberPreferenceManager.getInstance().getPreference(loggedMember, "jcmsplugin.myplugin.mypref");

4. Appel HTTP

La JSP savePreference.jsp est fournie pour déclencher la sauvegarde d'une préférence pour le membre authentifié (loggedMember) :

http://example.org/front/memberpreference/savePreference.jsp?key=jcmsplugin.myplugin.mypref&value=myvalue

5. Cache

A partir de JPlatform 10 SP1, MemberPreferenceManager intègre un système de cache afin d'optimiser les performances (notamment pour les espaces favoris) en réduisant les requêtes à la base.

En contre partie, avec JPlatform 10 SP1, la mise en place du cache introduit des petites période d'incohérence dans un cluster JSync lié au fonctionnement des DBEventLog. Lorsqu'une MemberPreference est modifiée sur un réplica, cette modification mettra environs 1 minute a être répercuter sur le leader et encore 1 minute a être répercuter sur les autres réplicas. Cette contrainte sera levée avec JPlatform 10 SP2 qui intégre un système de déclenchement immédiat des DBEventLog sur l'ensemble du cluster.

Le cache est par défaut actif et configuré à 10 000 entrées. Une entrée correspond à une MemberPreference pour un utilisateur données.

La taille du cache peut être modifié par la propriété suivante : 

channel.mbrpref.cache.max-entries: 10000

Le cache peut aussi être complétement désactivé avec la propriété suivante :

channel.mbrpref.cache.enabled: false

Ces 2 propriétés sont éditables dans l'onglet Avancé de l'éditeur de propriétés.

6. Conventions

6.1 Conventions sur le nommage des clés

Pour éviter les conflits, il est recommandé d'utiliser les préfixes suivants pour les clés de préférences :

• core. pour les préférences du coeurs
• jcmsplugin.myplugin. pour les préférences du module "My Plugin"

6.2 Conventions sur le contenu des valeurs

Lorsqu'une préférence comporte une simple valeur non structurée (p. ex. un entier) il est recommandé d'enregistrer cette valeur directement.

Lorsqu'une préférence comporte une valeur structurée comportant plusieurs champs, il est recommandé d'enregistrer une représentation sérialisée en JSON de cette valeur.

7. Affichage des MemberPreference

L'inspecteur de donnée d'un membre affiche l'ensemble de ses MemberPreference :

8. Cadre d'usage des préférences utilisateurs

En fournissant un système de stockage très simple, il peut être tentant d'utiliser les préférences utilisateurs au delà du cadre pour lequel elles ont été conçues.

8.1 Dans quels cas utiliser les préférences utilisateur ?

Utilisez les préférences utilisateurs pour stocker des options de paramétrages de fonctionnalités fournies par le coeur ou par les modules.

Exemple :

• Paramétrage du menu Application de la topbar

8.2 Dans quels cas utiliser un type dédiée associé à un Membre ?

Utilisez un type dédié pointant un membre lorsque vous devez stocker des informations de progression ou des champs additionnels.

Exemples :

• JLearn : JLearnMemberInfo, JLearnProgress
• JDrive : JDriverMemberInfo
• ESN : MemberData, MemberJob, MemberEducation

8.3 Dans quels cas utiliser les ExtraDBData sur Membre ?

Utilisez les ExtraDBData pour ajouter un seul champ sur un membre (p. ex. un matricule employé) ou une information de suivi simple (p. ex. Dernières connexions).