= Working with the Preferences module =
The preferences module aims to allow per-user control of output from the bot. Most notably logon spam.
Composition of a Preference
A BeBot preference consists of five elements that are stored in the database.
- module: The module element defines the preference group. Preferences with the same module value will be displayed in the same configuration page. - name: The names of the preference. - description: This is a description of the preference used in the interface. - default: This is the default value of the preference. - options: This is a semicolon (;) separated list of values for the preference.
In addition there is a table that links members to various settings and holds values for individual preferences.
Valid Default Options
The default option does not have to be one of the listed options, however it's not very useful to have a default that cannot be chosen after another option has been set.
Maximum lenghts for the preferences are module: 30 name: 30 description: 255 default value: 25 possible values: 255
This stipulates that no preference can have an option that is more than 25 characters long!
Spaces are not allowed in module and setting names. Spaces will be replaced with an underscore.
Calling prefs functions
$this -> bot -> core('prefs') -> function();
This function is used to create new preference. If the preference $name for $module already exists it doesn't overwrite or change it in any way.
create($module, $name, $description, $default, $options);
create function parameters:
* $module: Name of the module the setting is for, or group of settings that the setting should be in. * $name: Name of the preference. * $description: Description of the setting. * $default: The default value of the setting. * $options: A semicolon (;) separated list of possible options
Return value: None
mixed get(string $player, [string $module[, string $pref_name]])
Used to retrieve the value of a setting.
* $player: Name of the player whose prefference we are looking up. * $module: Name of the module the preference is for, or group of preferences that the setting should be in. * $pref_name: Name of the preference.
If $pref_name is omitted all preferences for the given module is returned. If $module is omitted all preferences are returned.
Return value: Value of the preference(s).
change(string $name, string $module, string $setting, string $value)
This function should not need to be called by coders as preferences should be altered by the players using the interface.
Creating a preference for a module:
$this -> bot -> core('prefs') -> create('MyModule', 'MySetting', 'This describes the preference', 'Option1', 'Option1;Option2;Option3');
Checking a preference:
$setting = $this -> bot -> core('prefs') -> get ($name, 'MyModule', 'MySetting');