====== 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()'' :

<code php>
$core->auth->user_prefs->addWorkSpace('example');
</code>

<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//.</note>

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

<code php>
# 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');
</code>

Il est possible d'utiliser [[http://php.net/manual/fr/language.references.php|l'assignation par référence]] pour faciliter l'accès aux préférences :

<code php>
# 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');
</code>

==== Les différents types de préférence ====

Enregistrer un nombre flottant :

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

Enregistrer un nombre entier :

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

Enregistrer un booléen :

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

Enregistrer une chaîne de caractères :

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

<note warning>
Pour stocker une chaîne de caractères avec plusieurs lignes, utilisez la fonction ''[[http://fr.php.net/manual/fr/function.base64-encode.php|base64_encode()]]'' lors de l'enregistrement et ''[[http://fr.php.net/manual/fr/function.base64-decode.php|base64_decode()]]'' lors de la lecture du paramètre. Ceci préservera les retours à la ligne lors de l'édition de [[:2.0:admin:aboutconfig|about:config]].
</note>

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

<code php>
$string = $core->auth->user_prefs->example->title;
</code>

===== Effacer une préférence =====

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

<code php>
$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');
</code>