Settings API

From BBlog

Software Requirements

The Settings API is planned for distribution for 0.7+ releases only.

The Settings API relies on the MySQL driver provided by the bBlog class. It uses the following statement, meaning that you have to get adequate rights on your database in order to let it work: "CREATE", "DROP", "INSERT", "UPDATE", "SELECT".

All plugin developers are urged to use function this API brings.

Settings API Definition

The Settings API is part of the new plugin infrastructure. It allows developpers to easily manage the configuration variables (the settings) of their plugins easily. A global administration interface for all plugins is provided, meaning plugin developpers don't have to create another admin plugin each time they need a small configuration variable.

In the new Plugin API that comes with the 0.7 release, the plugin infrastructure has changed a bit, especially regarding what we call a Plugin GUID (Global Unique IDentifier). This is used to define what belongs to a plugin (functions, variables ...). Please see the Plugin API section for more information.

Setting Structure

A setting is a row in an array or database table. It has five properties:

• Host Plugin GUID
  • A parent - the identifier of the plugin who owns the setting
• Plugin Name
  • A name - must be unique for the same plugin
• Plugin Value
  • A value - a variable that you can Set/Get it whenever you want
• Plugin Default Value
  • A default - also a variable, but you shouldn't update it after the plugin installation
• Description
  • A value - used maily for the administration panel, don't hesitate to be precise on this one, or your users might get lost in the list of the settings you registered

Code Requirements

The first requisite is a reference to the Settings API (available through the bBlog object - every plugin should have a reference to it, so it's not really a problem).

The second requisite is a plugin GUID. Your plugin should comply with the new PluginAPI - meaning that it has to have a unique global identifier. To get one, register your plugin with the bBlog Developers, and later, register it on a dedicated page of the webpage. Once you receive confirmation that your GUID is truly unique, you can go.

(You can also take a temp one like "Pamela-is-my-sister-and-nobody-will-use-a-GUID-like-this-one". It should work. NB: Stupid GUIDs like this one won't be accepted.) ===Mode Selection=== _This setting is available to users. Keep this in mind while coding !_

The Settings API supports two operational modes. Choose the right one that fit your needs:

• Unbuffered Mode

In unbuffered mode, all settings operation will be directly transmitted to the database. This will prevent any collision, but will really slow up your script.

• Buffered Mode

In buffered mode, all settings are retrieved from database while loading the SettingsAPI class, and then are stored in an array. This could be time consuming if you're running a lot of plugins. But, in buffered mode, all operations are buffered. That means that the internal array will be updated as long as needed, and finally, the database will be synchronized with the array (if you set a var A to 0, then to 1, then to 1, it will result in only 1 query - in unbuffered mode, it would have been 3 queries).

Function List

_Call them with pSettingsAPI->function !_

• BufferedMode (bool $mode)

FALSE for unbuffered, TRUE for buffered. Switch to a different buffered mode. Have to be made before anything else - if not, this operation will be ignored.

• InstallSettingsTable ()
• DropSettingsTable ()

Will create the table in your database, or drop it, as needed. - be careful, don't fuck up the system of your users ! -

• ClearSettingsTable ()

Clear all settings values, default values for all plugins. Clear the table. (

• InstallSetting($plugin_guid, $setting_name, $setting_value, $setting_default_value, $description = )

Register a setting in database. Note that you HAVE TO register each setting before using them. You can use the new handler to install/uninstall plugins in the PluginAPI v7

• UninstallSetting($plugin_guid, $setting_name)

_explicit uh ?_

• SetSetting($plugin_guid, $setting_name, $setting_value)

Change a setting value for a defined plugin.setting. _This function IS your friend_

• GetSetting($plugin_guid, $setting_name)

Get a setting value for a defined plugin.setting. _This function IS your best friend_

• SetSettingDefault($plugin_guid, $setting_name, $setting_default_value)

Change a setting's default value. _You shouldn't change this, except while updating plugin from another version_

• SetSettingDescription($plugin_guid, $setting_name, $description)

_explicit_

• SetSettingToDefault($plugin_guid, $setting_name)

Reset a setting.

• SetAllSettingsToDefault($plugin_guid)

Reset all settings for a plugin.

• GetSettingDefault($plugin_guid, $setting_name)

Get the default value for a plugin.setting.

• GetSettingDescription($plugin_guid, $setting_name)

Get the description for a giver plugin.setting. Get the default value for a plugin.setting.