Below is the full list of all Database class methods. An instance of this class is returned using the CreateDatabase
MayronDB method.
OnStartUp(func)
- @param func (function): Assign a callback function to the database
StartUp
event. The function will receive a reference to the database as its first argument.
Example:
db:OnStartUp(function(self)
-- self is a reference to the Database instance object.
-- It is useful to assign this to a global variable:
MyUI.db = self;
if (not self.global.isInstalled)
ShowInstaller();
end
end);
OnProfileChange(callback)
- @param callback (function): The function to be called after the database's profile has changed.
Hooks a callback function onto the ProfileChange
event to be called when the database changes profile. This is only changed by the user using db:SetProfile()
or db:RemoveProfile(currentProfile)
.
MayronDB executes this callback function with three arguments:
- 1st argument =
self
; a reference to the database object
- 2nd argument = the new profile name
- 3rd argument = the old profile name
AddToDefaults(path, value)
- @param path (string): The path to locate a new value being added into the database defaults table.
- @param value (any): The new value to be added into the database defaults table.
- @return (boolean): Whether a key and value pair was added successfully.
Adds default values that are used if there is no value for the given path in the saved variables table. You can use this method before and after MayronDB starts the database.
Example:
db:AddToDefaults("profile.aModule['red theme'][10].object", value);
PrintDefaults(depth, path)
- @param depth (optional int): A value greater than 1 to represent the depth of tables to print. If 1, only the root-level table will be printed. If 2, nested tables of the root-table will also be printed, and so on.
- @param path (optional string): Used to print a table within the defaults table rather than the whole thing.
A helper method to print the defaults table.
SetProfile(name)
- @param name (string): The name of the profile to assign to the character.
Sets the addon profile for the currently logged in character. Creates a new profile if the named profile does not exist.
GetProfiles()
- @return (table): A table containing string profile names for all profiles associated with the addon.
Gets a table of all profile names associated with the addon's database.
IterateProfiles()
Similar to db:GetProfiles()
except usable in a for loop to loop through all profiles associated with the addon.
Each loop returns values: id, profileName, profile
- (
int
) id: current loop iteration
- (
string
) profileName: the name of the profile
- (
table
) profile: the profile data
GetNumProfiles()
- @return (int): The number of profiles associated with the addon.
ResetProfile(name)
- @param name (string): The name of the profile to reset.
A helper method to reset a profile.
RenameProfile(oldName, newName)
- @param oldName (string): The old profile name.
- @param newName (string): The new profile name.
Renames an existing profile to a new profile name. If the new name already exists, it appends a number to avoid clashing: 'example (1)'
. This method will trigger the OnProfileChange
event, which will trigger any callback associated with this event (see the db:OnProfileChange(callback)
documentation above).
RemoveProfile(name)
- @param name (string): The name of the profile to move to the bin.
Moves the profile to the bin. The profile cannot be accessed from the bin.
Use db:RestoreProfile(name)
to restore the profile.
RestoreProfile(name)
- @param name (string): The name of the profile to restore from the bin.
Profiles will remain in the bin until a reload of the UI occurs. If the bin contains a profile, this method can restore it.
GetProfilesInBin()
- @return (table): An index table containing the names of all profiles in the bin.
Gets all profiles that can be restored from the bin.
GetCurrentProfile()
- @return (string): The current profile associated with the currently logged in character.
ParsePathValue(path)
- @param path (string): A string representing the path to traverse in the database to locate a value. The path should start with "global" or "profile".
- @return (any): The value found at the location specified by the path address. Might return
nil
if the path address is invalid or no value is located at the specified path address.
Searches a path address and returns the located value if found.
Example:
local value = db:ParsePathValue("global.core.settings[".. moduleName .. "[5]");
SetPathValue(path, value)
- @param path (string): The path address to indicate where the value should be stored in the database (e.g.
"db.profile.table.myValue"
).
- @param value (optional any): The value to be stored. This method will replace any existing value, so if the value is
nil
, then this will remove the existing value.
Adds a value to the database at the specified path address.
Example:
db:SetPathValue("profile.aModule.aSubTable[".. attributeName .."][5]", 123)
AppendOnce(rootObserver, path, appendKey, value)
- @param rootObserver (Observer): The root database observer (e.g.
profile
or global
, or a nested table/observer) to append the value to, relative to the path address provided.
- @param path (optional string): The path address to specify where the value should be appended.
- @param appendKey (optional string): An optional key that can be used instead of the path for registering an appended value inside the
appended
history table (found in the saved variable table).
- @param value (table): The table of values to be appended to the database.
- @return boolean @Returns whether the value was successfully added.
Adds a new value to the saved variable table only once. Adds to a special appended history table.
Example:
The following will inject a "defaultFields" key and table value into the current profile saved variable table only once. If the "defaultFields" key/value is removed, MayronObjects will never reinject it unless the appended key is removed from the appended history table (found in the saved variables table).
db:AppendOnce(db.profile, nil, "defaultFields", {
fieldNames = {
"Player";
};
fields = {
Player = {
unitID = "player";
};
};
});
RemoveAppended(path, rootTable, path)
- @param rootTable (string): The root database table (observer) to append the value to relative to the path address provided.
- @param path (string): The path address to specify the location of the value that should be removed.
- @return (boolean): Returns whether the value was successfully removed.
Removes the appended history (i.e., the registry key and appended data).
GetDatabaseName()
- @return (string): The name of the database
Returns the name of the database, which will be the addon name and the saved variable name joined together: MyAddOn:MY_ADDON_SV
RegisterUpdateFunctions(path, updateFunctions, manualFunc)
- @param path (string): A database path string, such as
myTable.mySubTable[2]
.
- @param updateFunctions (table or function): A table containing functions, or a function, to attach to a database path.
- @param manualFunc (optional function): When
TriggerUpdateFunction
is called, the manualFunc
will be called and is passed the update function to allow the user to decide how it should be called.
Register an update function to be triggered when a database value changes based on its path address. You can also register many update functions by passing a table of update functions reflecting the saved variables table's structure with nested tables.
Example:
db:RegisterUpdateFunctions("profile.myModule", {
width = function(newValue) ... end;
height = function(newValue) ... end;
appearance = {
color = function(newValue, path)
print(path) -- "db.profile.myModule.appearance.color"
end;
}
}
TriggerUpdateFunction(path)
- @param fullPath (string): A database path address, such as
profile.myTable.mySubTable[2]
.
Locates the database value found at the path address provided and executes the update function registered with that path address if one exists.
GetUpdateFunctions(path)
- @param path (string): A database path address, such as
myTable.mySubTable[2]
.
- @return (table or function): A table containing update functions, or a single update function, associated with the path address.
Returns a table of update functions registered with the corresponding path address.