Data Specifications

Provided below are two suggested data specs. These specs are very open to modification and enhancement by display addons, but plugins providing data should not expect that anything except the required fields are supported in the display.

For examples on how to implement these specs, see How to provide a dataobject.

Data Display

Data display addons provide a LDB “feed” for an always-up addon to display. These addons can be thought of like RSS feeds, where the display addon is similar to an RSS reader. Display addons could include FuBar, Titan Panel, StatBlocks, LegoBlocks, or any other design out there.

Fields

Field	Type	Description
type Required	string	Set to “data source”, indicates that this data object is a fubar-ish data source
text Required	string	The text to be shown.
value	string	Raw value from the text, for example text “75.0 FPS” would have value “75.0”
suffix	string	The “unit” appended to the end of text. For example text “75.0 FPS” would have the suffix “FPS”
label	string	A title for your feed, often shown to the left of the text, user might choose to hide this. If missing, the dataobject’s name may be used instead.
icon	string	Full path to a texture, often shown to the left of the label or text.
OnClick	function	An OnClick script handler to be directly attached to the display frame. Receives the usual args an OnClick receives (self, button).
tooltiptext	string	A string for the display addon to pass directly to GameTooltip:SetText() when a tooltip is needed.
OnTooltipShow	function	A function to call when the display wants to show a tooltip. The display will manage positioning, clearing and showing the tooltip, all this handler needs to do is populate the tooltip using :AddLine or similar. The display should pass the tooltip to this callback, in case it isn’t using GameTooltip.
OnEnter	function	An OnEnter script handler to be directly attached to the display frame. Usually used to display a tooltip. This handler should check the position of the frame it is passed and anchor the tooltip to that frame accordingly.
OnLeave	function	An OnLeave script handler to be directly attached to the display frame. Usually used to hide the toolip.
tooltip	frame	A frame to be displayed when the display frame is entered. The display addon is responsible for anchoring, showing and hiding this frame as needed. The tooltip frame’s OnShow can be used to refresh the frame. Note that this frame doesn’t have to be a GameTooltip.

Handling tooltips

The different tooltip specs might seem a bit overboard, but they each have their reasons. So, to clear up a bit of the confusion…

tooltiptext

This attribute is intended to only be set once, probably when the dataobject is registered. This is meant for small addons that don’t need a dynamic tooltip and therefore don’t want to manage a tooltip. The display addon could handle this case fairly easily:

local function OnEnter(self)
	GameTooltip:SetOwner(self, "ANCHOR_NONE")
	GameTooltip:SetPoint("TOPLEFT", self, "BOTTOMLEFT")
	GameTooltip:SetText(dataobj.tooltiptext)
	GameTooltip:Show()
end

OnTooltipShow(tooltip)

This method is designed for displays that want control over how the tooltip is anchored and displayed. This is probably the most frequent case. In this design, the display handles everything except filling the tooltip with data. Naturally, it must pass the tooltip to be filled to the callback, some display addons might use their own tooltip instead of the global GameTooltip.

-- Don't let the mixed use of dot- (.) and colon-notation (:) confuse you here! --

-- In the data source addon...
function dataobj:OnTooltipShow()
	self:AddLine("This is a test!")
	self:AddLine("Don't mind me...")
end

-- In the dsilpay addon...
local function OnEnter(self)
	GameTooltip:SetOwner(self, "ANCHOR_NONE")
	GameTooltip:SetPoint("TOPLEFT", self, "BOTTOMLEFT")
	GameTooltip:ClearLines()
	dataobj.OnTooltipShow(GameTooltip)
	GameTooltip:Show()
end

OnEnter/OnLeave

This design is needed by plugins that wish to provide a clickable tooltip. Because the clickable tip is more complex, the plugin needs to manage when it is hidden, it can’t simply hide the tip when the base frame loses mouse focus. These functions should be attached directly to the display frame’s OnEnter and OnLeave scripts.

tooltip

This option is a bit of a merge between the OnEnter/OnLeave and OnTooltipShow designs. Here the plugin provides a frame (it’s likely not a GameTooltip) for the display to anchor and show. The plugin can use the frame’s OnShow to refresh the data in the frame when it is shown. This allows the plugin to use a custom frame instead of a GameTooltip, but still allows the display control over how the frame is anchored and shown.

Tooltips and display addons

It’s possible that a source addon may provide more that one tooltip method. The display addon should only use one of these (even if it support all four in the spec). The generally preferred order is: tooltip > OnEnter/OnLeave > OnTooltipShow > tooltiptext.

Generally speaking, tooltip and tooltiptext are not likely to be implemented along with another render method. OnEnter may also provide (and use) OnTooltipShow, in this case it’s usually preferred that the display simply set the OnEnter handler directly to the frame, thus bypassing the display’s tooltip handling code and never calling OnTooltipShow from the display.

Quicklauncher

A quicklauncher is a LDB object that does not provide any data, but instead provides an OnClick handler to allow fast access to config panels, toggle settings, or perform other actions.

Quicklaunchers should never expect a secure frame to be used, therefore actions like spellcasting are not possible.

Fields

type Required	Set to “launcher”, indicates that this data object is a launcher and does not provide any data to be rendered in an always-up frame.
icon Required	Full path to a texture for display.
OnClick Required	An OnClick script handler to be directly attached to the display frame. Receives the usual args an OnClick receives (self, button).
tocname	The name of the addon providing the launcher, if it’s name does not match the dataobject’s name. Used by displays to get TOC metadata about the addon.
label	A label to use for the launcher, overriding the dataobject name.

Creating your own custom spec

LDB is designed to be very generic. If you wish you can create your own custom spec to allow the plugin-display design within your own addons. The only requirement for these custom specs is to set the type attribute to a unique string so that other display addons will not try to render your custom dataobjects. For example, the Quicklauncher spec sets this attribute to “launcher”.