Table of Contents

User preferences

Save a preference

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

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

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.

To save a preference, the function put() is used, with the following parameters:

  1. preference name (a string containing only digits, characters without accents and _)
  2. its value
  3. its type (a string) (optional bu recommended to avoid ambiguities)
  4. its label (a string) (optional)
  5. a boolean: replace the old value (default: yes) (optional)
  6. a boolean: the parameter is global (default: no) (optional)

Example with a string with a label

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

It is possible to use the assignation by reference to ease the access to preferences: 

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

The different types of preferences

Saving a float: 

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

Saving an integer: 

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

Saving a boolean: 

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

Saving a string: 

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

Warning:

To store a string with multiple lines, use the function base64_encode() when saving and base64_decode() when reading the parameter. This will preserve the carriage returns when editing about:config.

Read a preference

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

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

Delete a preference

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

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