Les préférences utilisateurs

Enregistrer une préférence

Il faut d'abord sélectionner le workspace (espace de travail) des préférences grâce à la fonction addWorkSpace() :

$core->auth->user_prefs->addWorkSpace('example');

Note :

Le paramètre de addWorkspace() ne doit contenir que des chiffres ou des lettres sans accent.

Permis : [a-zA-Z][a-zA-Z0-9]

Il est conseillé d'utiliser le nom du plugin comme workspace pour éviter que 2 plugins n'aient le même workspace.

Pour sauvegarder une préférence on utilise la fonction put(), dont les paramètres sont :

le nom de la préférence (une chaîne de caractères contenant uniquement des chiffres ou des lettres sans accent et _)
sa valeur
son type (une chaîne de caractères) (facultatif mais recommandé pour éviter les ambiguïtés)
son label (une chaîne de caractères) (facultatif)
un booléen : écraser l'ancienne valeur (valeur par défaut : oui) (facultatif)
un booléen : le paramètre est global (valeur par défaut : non) (facultatif)

Example avec une chaîne de caractères avec un label

# création du workspace
$core->auth->user_prefs->addWorkSpace('example');
# l'objet $core->auth->user_prefs->example a été créé

# enregistrement de la préférence dans le workspace example
$core->auth->user_prefs->example->put('pref_name', __('Hello World!'), 'string', 'My label');

Il est possible d'utiliser l'assignation par référence pour faciliter l'accès aux préférences :

# création du workspace
$core->auth->user_prefs->addWorkSpace('example');
 
# assignation par référence, $example_prefs pointe vers le workspace nouvellement créé
$example_prefs =& $core->auth->user_prefs->example;
 
# enregistrement de la préférence
$example_prefs->put('pref_name', __('Hello World!'), 'string', 'My label');

Les différents types de préférence

Enregistrer un nombre flottant :

$core->auth->user_prefs->example->put('pi', 3.14159265, 'float');

Enregistrer un nombre entier :

$core->auth->user_prefs->example->put('nb_entries', 217, 'integer');

Enregistrer un booléen :

$core->auth->user_prefs->example->put('is_valid', true, 'boolean');

Enregistrer une chaîne de caractères :

$core->auth->user_prefs->example->put('title', __('Hello World!'), 'string');

Attention :

Pour stocker une chaîne de caractères avec plusieurs lignes, utilisez la fonction base64_encode() lors de l'enregistrement et base64_decode() lors de la lecture du paramètre. Ceci préservera les retours à la ligne lors de l'édition de about:config.

Lire une préférence

Une préférence est assignée à la variable $core→auth→user_prefs→nom du workspace→nom de la préférence, par exemple :

$string = $core->auth->user_prefs->example->title;

Effacer une préférence

Il faut utiliser la fonction drop() avec l'identifiant de la préférence comme argument :

$core->auth->user_prefs->addWorkspace('example');
 
# création de la préférence
$core->auth->user_prefs->example->put('title', __('Hello World!'), 'string');
 
# suppression de la préférence
$core->auth->user_prefs->example->drop('title');