Preferences

Introduction

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.

As simple user, !preferences will show you a list of modules in which you may set your prefered choice for each available parameter.

But if you do !preferences from a character that is ranked high enough in the bot, you ALSO obtain default bot values in middle of [brackets].

In both cases, the current value set is simple text, while the settable value is a link you may click to change for.

Preferences Policy

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();

Preferences Functions

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.

Example Usage

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