API

tekkub edited this page Sep 14, 2010 · 35 revisions

LibDataBroker is designed to be embedded into the addons that use it.
The user should never have to worry about what version of the library they have, or even really be aware of the library’s existence.

Embedding the library is a fairly simple task. Simply include LibDataBroker-1.1.lua in your addon’s files and add it into your TOC to be loaded.
Make sure that you include LibStub and CallbackHandler-1.0 as well, and that they load before LDB.
If you use Ace3 in your addon, you probably already have LibStub and CallbackHandler, just make sure they’re loaded before LDB.

For more help on how to use LDB, see How to provide a dataobject.

Pulling the library into your addon

Retrieving a local reference to the library is done with a simple call to LibStub.

local ldb = LibStub:GetLibrary("LibDataBroker-1.1")

Dataobject registry

Naturally the first thing we need is a place to store and retrieve all the dataobjects used by addons. LDB provides a few simple functions for this.

ldb:NewDataObject(name[, dataobject]) → dataobject

Creates a new dataobject with the name given, fires a callback to inform listeners of the new dataobject, and returns the object for future use. If a table is passed for the second arg, it’s values are stored in the new dataobject before the callback is fired.

ldb:GetDataObjectByName(dataobjectname) → dataobject

Retrieve a dataobject by name.

ldb:GetNameByDataObject(dataobject) → name

Look up the name of a dataobject.

ldb:DataObjectIterator()

Iterate over all dataobjects. Works like pairs()

for name,dataobj in ldb:DataObjectIterator() do ... end

Registering callback functions

So, how do we pull it into an addon and know when to update things? Easy! LDB uses Ace3’s CallbackHandler to trigger callbacks in nearly the exact same way as AceEvent3 does.

ldb.RegisterCallback(myTable or “myAddonID”, “eventName”[, method[, arg]])

To receive updates from the library, we must register a callback function. There are three ways you can do this.

myTable.RegisterLDBCallback = ldb.RegisterCallback

myTable:RegisterLDBCallback("eventName"[, method[, arg]])
ldb.RegisterCallback(myTable, "eventName"[, method[, arg]])
ldb.RegisterCallback("myAddonID", "eventName"[, method[, arg]])
Arg Type Description
self table Your addon object. Do not pass the library’s self (for example, by calling ldb:RegisterCallback(...)). If method is a string, this value will be passed to the function when called.
“myAddonID” string A unique identifier for your callback, if you don’t wish to pass self.
“eventName” string The name of the event you want to listen to.
method string or function Which method to call. If string, self[“method”] will be called. If left out (nil), self[“eventName”] will be called.
arg optional If present (even nil), this value will be passed to the receiving function.

Callback arguments

If method is a function, it will be called as:

method("eventName", (arguments to the event)) -- if "arg" was not passed, or...
method(arg, "eventName", (arguments to the event)) -- if "arg" was passed

If method is a string (method name), it will be called as:

self["method"](self, "eventName", (arguments to the event)) -- if "arg" was not passed, or...
self["method"](self, arg, "eventName", (arguments to the event)) -- if "arg" was passed

Callback events

LDB provides 5 basic callbacks, one that is fired for for new dataobject registrations, and 4 that are fired any time a dataobject attribute is changed.

LibDataBroker_DataObjectCreated(name, dataobj)

Fires when a new dataobject is created. Passes the DO’s name and object.

local ldb = LibStub:GetLibrary("LibDataBroker-1.1")
local function mycallback(event, name, dataobj)
	ChatFrame1:AddMessage("LDB: New dataobject '"..name.. "' created")
end
ldb.RegisterCallback("MyAnonCallback", "LibDataBroker_DataObjectCreated", mycallback)

LibDataBroker_AttributeChanged(name, attr, value, dataobj)

Fires for ALL attribute changes across ALL dataobjects. Passes the DO name, name of the attribute changed, new value of the attribute, and the dataobject.

local ldb = LibStub:GetLibrary("LibDataBroker-1.1")
local function mycallback(event, name, key, value, dataobj)
	ChatFrame1:AddMessage("LDB: "..name.. ".".. key.. " was changed to ".. tostring(value))
end
ldb.RegisterCallback("MyAnonCallback", "LibDataBroker_AttributeChanged", mycallback)

LibDataBroker_AttributeChanged_<name>(name, attr, value, dataobj)

Fires for ALL attribute changes on the named dataobject. Passes the same args as LibDataBroker_AttributeChanged

local ldb = LibStub:GetLibrary("LibDataBroker-1.1")
local function mycallback(event, name, key, value, dataobj)
	ChatFrame1:AddMessage("LDB: myDataAddon.".. key.. " was changed to ".. tostring(value))
end
ldb.RegisterCallback("MyAnonCallback", "LibDataBroker_AttributeChanged_myDataAddon",
	mycallback)

LibDataBroker_AttributeChanged_<name>_<attr>(name, attr, value, dataobj)

Fires for changes to the named attribute on the named dataobject. Passes the same args as LibDataBroker_AttributeChanged

local ldb = LibStub:GetLibrary("LibDataBroker-1.1")
local function mycallback(event, name, key, value, dataobj)
	ChatFrame1:AddMessage("LDB: myDataAddon.text was changed to ".. tostring(value))
end
ldb.RegisterCallback("MyAnonCallback", "LibDataBroker_AttributeChanged_myDataAddon_text", 
	mycallback)

LibDataBroker_AttributeChanged__<attr>(name, attr, value, dataobj)

Fires for changes to the named attribute across ALL dataobjects. Passes the same args as LibDataBroker_AttributeChanged

local ldb = LibStub:GetLibrary("LibDataBroker-1.1")
local function mycallback(event, name, key, value, dataobj)
	ChatFrame1:AddMessage("LDB: ".. name.. ".text was changed to ".. tostring(value))
end
ldb.RegisterCallback("MyAnonCallback", "LibDataBroker_AttributeChanged__text", mycallback)