====== User preferences ======

===== Save a preference =====

First you have to select the preference workspace using the ''addWorkSpace()'' function:

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

<note>''addWorkSpace()'' parameter must only contain digits or characters without accents.

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

It is recommended to use the plugin name as workspace to avoid 2 plugins have the same workspace.</note>

To save a preference, the function ''put()'' is used, with the following parameters:
  - preference name (a string containing only digits, characters without accents and ''_'')
  - its value
  - its type (a string) (optional bu recommended to avoid ambiguities)
  - its label (a string) (optional)
  - a boolean: replace the old value (default: yes) (optional)
  - a boolean: the parameter is global (default: no) (optional)

==== Example with a string with a label ====

<code php>
# workspace creation
$core->auth->user_prefs->addWorkSpace('example');
# the $core->auth->user_prefs->example object has been created

# saving the preference in the example workspace
$core->auth->user_prefs->example->put('pref_name', __('Hello World!'), 'string', 'My label');
</code>

It is possible to use [[http://php.net/manual/en/language.references.php|the assignation by reference]] to ease the access to preferences:

<code php>
# workspace creation
$core->auth->user_prefs->addWorkSpace('example');

# assigning by reference, $example_prefs points to the newly created workspace
$example_prefs =& $core->auth->user_prefs->example;

# saving the preference
$example_prefs->put('pref_name', __('Hello World!'), 'string', 'My label');
</code>

==== The different types of preferences ====

Saving a float:

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

Saving an integer:

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

Saving a boolean:

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

Saving a string:

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

<note warning>
To store a string with multiple lines, use the function ''[[http://php.net/manual/en/function.base64-encode.php|base64_encode()]]'' when saving and ''[[http://php.net/manual/en/function.base64-decode.php|base64_decode()]]'' when reading the parameter. This will preserve the carriage returns when editing [[:2.0:admin:aboutconfig|about:config]].
</note>

===== Read a preference =====

A preference is assigned to the $core->auth->user_prefs->**workspace name**->**preference name** variable, for instance:

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

===== Delete a preference =====

Use the ''drop()'' function with the preference identifier as argument:

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

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

# preference deletion
$core->auth->user_prefs->example->drop('title');
</code>