Preferences - Revision history

B3b0tUzR at 22:39, 1 August 2024

2024-08-01T22:39:13Z

B3b0tUzR at 22:38, 1 August 2024

2024-08-01T22:38:29Z

B3b0tUzR: Created page with '======= Working with the Preferences module ======= ===== Introduction ===== The preferences module aims to allow per-user control of output from the bot. Most notably logon spa…'

2020-09-16T22:46:55Z

Created page with '======= Working with the Preferences module ======= ===== Introduction ===== The preferences module aims to allow per-user control of output from the bot. Most notably logon spa…'

New page

======= 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>

@@ Line 19: / Line 19: @@
 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 values in middle of [brackets].
+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 case, the current value set is simple text, while the settable value is a link you may click to change for.
+In both cases, the current value set is simple text, while the settable value is a link you may click to change for.

← Older revision		Revision as of 22:38, 1 August 2024
Line 16:		Line 16:
	===== Valid Default Options =====		===== 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.		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 values in middle of [brackets].
		+
		+	In both case, the current value set is simple text, while the settable value is a link you may click to change for.