Shadowed51320@legacy41570690 (talk | contribs) (→Dongle Database Object: db.char is now "CharName - RealmName" as of Dongle 1.0.) |
Tekkub56883@legacy41576006 (talk | contribs) |
||
(4 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
Dongle provides a very powerful database system that easily enables the use of multiple and custom profiles. Each dongle object can have multiple databases associated with it, specified by a global variable name. Databases are registered with the core dongle object, which returns a database object. |
Dongle provides a very powerful database system that easily enables the use of multiple and custom profiles. Each dongle object can have multiple databases associated with it, specified by a global variable name. Databases are registered with the core dongle object, which returns a database object. |
||
+ | |||
+ | ''This API was introduced with Dongle-1.0'' |
||
==DongleObject Database API== |
==DongleObject Database API== |
||
Line 6: | Line 8: | ||
Initializes a database object and returns it. This function can be called anytime AFTER :Initialize(). If you call this function prior to that point, it will succeed but your results will be unpredictable, since the saved variables are not loaded until :Initialize(). |
Initializes a database object and returns it. This function can be called anytime AFTER :Initialize(). If you call this function prior to that point, it will succeed but your results will be unpredictable, since the saved variables are not loaded until :Initialize(). |
||
+ | {| class="darktable" |
||
− | '''Arguments''' |
||
⚫ | |||
− | {| style="{{CSS Darktable}}" |
||
+ | | |
||
− | |- style="{{CSS Darktable th}}" |
||
− | ! |
+ | ! Value !! Type !! Details |
|- |
|- |
||
+ | ! rowspan=3 | Arguments |
||
| name || string || The name of the global variable associated with this database. |
| name || string || The name of the global variable associated with this database. |
||
|- |
|- |
||
Line 16: | Line 19: | ||
|- |
|- |
||
| defaultProfile || string || (Optional) The default profile to use if the user hasn't selected one. |
| defaultProfile || string || (Optional) The default profile to use if the user hasn't selected one. |
||
⚫ | |||
− | |||
− | |||
⚫ | |||
− | {| style="{{CSS Darktable}}" |
||
− | |- style="{{CSS Darktable th}}" |
||
− | ! Return !! Type !! Details |
||
|- |
|- |
||
⚫ | |||
| db || table || The [[#Dongle_Database_Object|DongleDB Object]] encapsulating the new database. |
| db || table || The [[#Dongle_Database_Object|DongleDB Object]] encapsulating the new database. |
||
|} |
|} |
||
Line 38: | Line 35: | ||
* db.global - A global profile, available to all users |
* db.global - A global profile, available to all users |
||
− | Only the profile section is |
+ | Only the profile section is changeable by the user and most data should be stored there. If you have a specific reason for the other sections, they have been provided. Any empty sections are removed when logging off, to prevent unnecessary data storage. |
==Dongle Default Table== |
==Dongle Default Table== |
||
Line 81: | Line 78: | ||
====Returns==== |
====Returns==== |
||
tbl (table) - A list of the current profiles available, indexed by consecutive integers starting at 1. This table may contain other elements if it was specified as an argument to the function. |
tbl (table) - A list of the current profiles available, indexed by consecutive integers starting at 1. This table may contain other elements if it was specified as an argument to the function. |
||
+ | |||
+ | ===DongleDBObject:GetCurrentProfile()=== |
||
+ | Returns the current profile key being used. |
||
+ | ====Returns==== |
||
+ | profileKey (string) - Current profile key thats being used for the database configuration |
||
===DongleDBObject:DeleteProfile(name)=== |
===DongleDBObject:DeleteProfile(name)=== |
Latest revision as of 06:56, 20 August 2007
Dongle provides a very powerful database system that easily enables the use of multiple and custom profiles. Each dongle object can have multiple databases associated with it, specified by a global variable name. Databases are registered with the core dongle object, which returns a database object.
This API was introduced with Dongle-1.0
DongleObject Database API
DongleObject:InitializeDB(name[, defaults, defaultProfile])
Initializes a database object and returns it. This function can be called anytime AFTER :Initialize(). If you call this function prior to that point, it will succeed but your results will be unpredictable, since the saved variables are not loaded until :Initialize().
Value | Type | Details | |
---|---|---|---|
Arguments | name | string | The name of the global variable associated with this database. |
defaults | table | (Optional) A table of defaults to be used for the given database. Should be given as a Dongle Default Table | |
defaultProfile | string | (Optional) The default profile to use if the user hasn't selected one. | |
Returns | db | table | The DongleDB Object encapsulating the new database. |
Dongle Database Object
Each call to InitializeDB returns a new Dongle Database Object. These functions are all injected into the table, which can be used to store data in the various profiles. The profiles made available to each database object are:
- db.profile - Most data storage should happen here. The user is able to change their profile, so any "portable" data should wind up here.
- db.char - A character specific section ("CharName - RealmName")
- db.realm - A realm specific section ("RealmName").
- db.class - A class specific section ("LocalisedClassName").
- db.faction - A faction specific section ("Horde").
- db.factionrealm - A faction/realm specific section ("Horde - RealmName")
- db.global - A global profile, available to all users
Only the profile section is changeable by the user and most data should be stored there. If you have a specific reason for the other sections, they have been provided. Any empty sections are removed when logging off, to prevent unnecessary data storage.
Dongle Default Table
The defaults table has a specific format, which needs to match the sections in the actual database. The following is the general format which should be used:
local defaults = { profile = { fruits = { apple = true } }, char = {}, realm = {}, class = {}, faction = {}, factionrealm = {}, global = {}, }
You don't need to supply each and every section, only the ones you wish to establish defaults for. There is no harm is having sections missing, or having blank sections as above.
Dongle Database Object API
DongleDBObject:RegisterDefaults(defaults)
Registers a set of defaults with the database. This can be done after the database has been initialized. It will add the defaults given to the current defaults table (if it exists).
Arguments
- defaults (table) - A Dongle Default Table.
Behavior
Will add the defaults specified to the current database defaults table
DongleDBObject:SetProfile(name)
Changes the db object's active profile, creating it if it doesn't already exist
Arguments
- name (string) - The name of the new profile
Fires Message
DongleDBObject:GetProfiles([tbl])
Returns a table containing a list of profiles currently available to the user.
Arguments
tbl (table) - A table to use instead of creating a new table.
Returns
tbl (table) - A list of the current profiles available, indexed by consecutive integers starting at 1. This table may contain other elements if it was specified as an argument to the function.
DongleDBObject:GetCurrentProfile()
Returns the current profile key being used.
Returns
profileKey (string) - Current profile key thats being used for the database configuration
DongleDBObject:DeleteProfile(name)
Deletes the non-active profile specified. Does not allow the user to delete the current profile.
Arguments
name (string) - The name of the profile to delete
Fires Message
DongleDBObject:CopyProfile(name)
Copies the given profile into your current profile. Does not allow the user to have the same source and destination profiles. Cannot copy from a profile that doesn't exist.
Arguments
name (string) - The name of the profile to copy from
Fires Message
DongleDBObject:ResetProfile()
Resets the current profile by replacing it with an empty profile, and copying the defaults into the profile.
Fires Message
DongleDBObject:ResetDB([defaultProfile])
Completely clears the current database and reinitializes it using the defaults already registered. Optionally will set the profile to defaultProfile instead of the system default ("CharName of RealmName").
Arguments
- defaultProfile (string) - The default profile to use if the user hasn't selected one.