Working with the Settings Core module

The settings module aims to provide a common interface and structure for dealing with settings. To do this, it provides functions for creating, saving, retrieving, and modifying settings.

A BeBot setting consists of eight elements that are stored in the database.

1. module: The module element defines the settings group. Settings with the same module value will be displayed in the same configuration page.
2. setting: The setting element names the setting.
3. value: This is the actual value of the setting.
4. datatype: This is the PHP data type of the stetting.
5. longdesc: This is a description of the setting used in the settings interface.
6. defaultoptions: This is a semicolon (;) separated list of default values for the setting.
7. hidden: This is a boolean (tinyint(1)) flag that will hide the setting from the setting interface. The setting will still be in the global setting array, but cannot be configured via the standard setting interface.
8. disporder: This is the order to display the settings in for a paticular module. The deafult value is 1. If this is not changed or two settings have the same display order, settings will display in alphabetical order.

All PHP data types (bool, null, int, float, string, and arrays) except PHP Objects are supported by the settings interface. With the exception of array elements, the values of settings will have their proper data types when returned.

Saving an array using the settings interface has some special considerations:

• An array is always a hidden setting.
• The saved array will always be a numbered, not associative array.
• The data types of an array’s elements will always be string data.

When dealing with boolean values (true/fales), the default options should be On;Off. Other data types can have whatever default options you wish.

The module, setting, value, longdesc, and defaultoptions cannot be longer than 255 characters.

Spaces are not allowed in module and setting names. Spaces will be replaced with an underscore.

$this -> bot -> settings -> function();

array create (string $module, string $setting, mixed $value, string $longdesc [, string $defaultoptions] [, bool $hidden] [, int $disporder])

This function is used to create new settings. If the settings $setting for $module already exists it doesn’t overwrite or change it in any way.

create function parameters:

• $module: Name of the module the setting is for, or group of settings that the setting should be in.
• $setting: Name of the setting.
• $value: Default value for the setting.
• $longdesc: Description of the setting.
• $defaultoptions: Semicolon separated list of default options. ie: “On;Off”, “0;1;2;3;4;5;6;7;8;9;” (Optional, if not specified the settings interface will guess at what to display.)
• $hidden: Determines if the setting should be displayed on the settings interface. Default: false.
• $disporder: Order the setting should be displayed in the setting interface. Overrides default alphabetical sorting of settings.

Return value: Standard BeBot status array containing error, errormsg, and content elements.

array save(string $module, string $setting, mixed $value [, bool $noupdate])

This functions is used to update the values of existing settings.

save function parameters:

• $module: Name of the module the setting is for, or group of settings that the setting should be in.
• $setting: Name of the setting.
• $value: New value for the setting.
• $noupdate: Do not update setting if setting already exists. This is a compatibility parameter for modules using v1 of Glarawyn’s settings module. It should not be used in BeBot 0.4 modules.

Return value: Standard BeBot status array containing error, errormsg, and content elements.

null update(string $module, string $setting, string $what, mixed $to)

Used to update description, default options, hidden status, or display order of a setting.

update function parameters:

• $module: Name of the module the setting is for, or group of settings that the setting should be in.
• $setting: Name of the setting.
• $what: What property to update. (longdesc, defaultoptions, hidden, disporder)
• $to: New value for the property.

Return value: No returned value.

mixed get(string $module, string $setting)

Used to retrieve the value of a setting.

• $module: Name of the module the setting is for, or group of settings that the setting should be in.
• $setting: Name of the setting.

Return value: Value of the setting. If no setting exists, nothing will be returned and the bot will log an error message. Using the get function is the only supported way to retrieve a setting’s value.

Creating the default settings for TestModule:

$this -> bot -> settings -> create("TestModule", "Enabled", FALSE, "Turns the functionality of this module on and off.", "On;Off");
 
$this -> bot -> settings -> create("TestModule", "FavNum", 0, "Sets the bot's favorite number", "0;1;2;3;4;5;6;7;8;9");
 
$this -> bot -> settings -> create("TestModule", "Blurb", "Hey Guys! Watch this!", "The blurb on top of this modules text windows.");

When controlling the order of the settings, it’s generally a good idea to have large gaps between your settings. For example:

$this -> bot -> settings -> create ("ExampleModule", "ExampleSetting1", "ExampleValue", "ExampleSetting1", "Value1;Value2;Value3", FALSE, 10);
$this -> bot -> settings -> create ("ExampleModule", "ExampleSetting2", "ExampleValue", "ExampleSetting2", "Value1;Value2;Value3", FALSE, 20);
$this -> bot -> settings -> create ("ExampleModule", "ExampleSetting3", "ExampleValue", "ExampleSetting3", "Value1;Value2;Value3", FALSE, 30);
$this -> bot -> settings -> create ("ExampleModule", "ExampleSetting4", "ExampleValue", "ExampleSetting4", "Value1;Value2;Value3", FALSE, 40);
$this -> bot -> settings -> create ("ExampleModule", "ExampleSetting5", "ExampleValue", "ExampleSetting5", "Value1;Value2;Value3", FALSE, 50);

By incrementing the display order by 10, you can later add a setting that will display in the settings interface between ExampleSetting1 and ExampleSetting2 by setting the display order to 15.