preferences

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
preferences [2008/04/21 13:38]
Blueeagle Updated for re-worked preferences core/module
preferences [2020/09/12 01:30] (current)
Line 1: Line 1:
 +======= Working with the Preferences module =======
 +
 +===== 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.
 +
 +
 +===== 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.
 +
 +===== Function Documentation =====
 +==== Calling prefs functions ====
 +<code php>
 +$this -> bot -> core('prefs') -> function();
 +</code>
 +
 +
 +==== 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.
 +<code php>
 +create($module, $name, $description, $default, $options);
 +</code>
 +
 +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
 +
 +<code php>
 +mixed get(string $player, [string $module[, string $pref_name]])
 +</code>
 +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).
 +
 +<code php>
 +change(string $name, string $module, string $setting, string $value)
 +</code>
 +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:
 +<code php>
 +$this -> bot -> core('prefs') -> create('MyModule', 'MySetting', 'This describes the preference', 'Option1', 'Option1;Option2;Option3');
 +</code>
 +
 +Checking a preference:
 +<code php>
 +$setting = $this -> bot -> core('prefs') -> get ($name, 'MyModule', 'MySetting');
 +</code>