WowAce

Extending Boss Notes with Provider Modules

Boss Notes is based on a modular design and can be extended with provider modules. A provider module is a seperate add-on that follows the conventions described on this page. It provides sources to Boss Notes. Each source is a structured information that can be displayed in Boss Notes.

Data Structures

The following data structures are used by Boss Notes in the communication with provider modules. These data structures are regular Lua tables.

Instance

An instance is a dungeon or raid.

Encounter

An encounter is a boss encounter in a dungeon or raid.

Source

A source is a structured information that is displayed by Boss Notes.

NOTE: All keys are optional. Provider modules may specify custom keys in addition to the ones from the table above. These custom keys are not interpreted by Boss Notes and passed back transparently to the provider module in callbacks. The avoid naming conflicts, custom keys should begin with a lower-case x, for example xCustomInformation.

TOC

Provider modules generally declare a dependency on Boss Notes resulting in a TOC like this:

## Interface: 30000
## Title: Boss Notes [|cffe76f00Example|r]
## Notes: Exemplary Boss Notes module.
## Dependencies: BossNotes

Registering the Provider

A extension module is registered as a provider in Boss Notes. Boss Notes includes the method BossNotes:RegisterProvider(key, callbacks) for that purpose. This method receives a unique key that identifies the provider module as well as a table of callbacks. The method BossNotes:UnregisterProvider(key) may be used to to remove a registered provider.

An extension module can optionally merge its Ace3 options with the ones of Boss Notes. Boss Notes provides the method BossNotes:MergeOptions(key, opts) for that purpose.

If an extension module is written using Ace3, the corresponding code might look like this:

local ACE_OPTS = {
	name = L["EXAMPLE"],
	desc = L["EXAMPLE_DESC"],
	handler = BossNotesExample,
	type = "group",
	args = {
		dummy = {
			name = L["DUMMY"],
			order = 1,
			type = "toggle",
			get = "GetDummy",
			set = "SetDummy"
		},
		silly = {
			name = L["SILLY"],
			order = 2,
			type = "toggle",
			get = "GetSilly",
			set = "SetSilly"
		}
	}
}
BossNotes:MergeOptions("example", ACE_OPTS)

BOSS_NOTES_EXAMPLE_PROVIDER = "EXAMPLE"

function BossNotesExample:OnEnable ()
	BossNotes:RegisterProvider(BOSS_NOTES_EXAMPLE_PROVIDER, {
		OnSources = function (instance, encounter)
			return self:OnSources(instance, encounter)
		end,
		OnRefresh = function (instance, encounter)
			self:OnRefresh(instance, encounter)
		end,
		OnClick = function (instance, encounter, source, button)
			self:OnClick(instance, encounter, source, button)
		end
	})
end

function BossNotesExample:OnDisable ()
	BossNotes:UnregisterProvider(BOSS_NOTES_EXAMPLE_PROVIDER)
end

Callbacks

Boss Notes communicates with the provider module by means of the callbacks specified in the registration. The following callbacks are invoked by Boss Notes:

These callbacks are described in the following sections.

OnSources

Description: Queries sources from the provider module.

Arguments:

Return Value: An array of sources.

Example: This example returns two distinct, hardcoded sources.

function BossNotesExample:OnSources (instance, encounter)
	return {
		{
			title = "Note 1",
			content = "This is the content of the first source."
		},
		{
			color = { r = 1.0, g = 0.0, b = 0.0 },
			title = "Note 2",
			tag = "Important",
			content = "A very important second source."
		}
	}
end

OnRefresh

Description: Notifies the provider module that the user has requested a refresh of the sources.

Arguments:

Return Value: None.

Example: This example first converts the instance and encounter into the context key format by invoking BossNotes:GetContextKey(instance, encounter). Next, it uses the key to check whether the data for that key needs refreshing. If so, it refreshes the data and invokes BossNotes:InvalidateContextKey(key, immediate) to cause a refresh of the information in Boss Notes. Boss Notes later invokes the regular OnSources callback to query the updated sources. Since the argument immediate is set to false, the display is only refreshed after a few seconds, allowing other provider modules a chance to refresh their data as well and allowing Boss Notes to collect all refreshed sources in a single pass. This is prefered to an an immediate refresh.

function BossNotesExample:OnRefresh (instance, encounter)
	local key = BossNotes:GetContextKey(instance, encounter)
	if self:NeedsRefresh(key) then
		self:Refresh(key)
		BossNotes:InvalidateContextKey(key, false)
	end
end

OnClick

Description: Notifies the provider module that one its sources has been clicked. For the header area, only right-clicks are sent. For the content area, all clicks are sent.

Arguments:

Return Value: None.

Example: This example prints to the chat when a click occurs.

function BossNotesExample:OnClick (instance, encounter, source, button)
	BossNotes:Print(string.format("Note \"%s\" clicked using %s",
			source.title, button))
end

OnHyperlinkClick

Description: Notifies the provider module that a hyperlink in one of its sources has been clicked.

Arguments:

Return Value: None.

Example: This example prints to the chat when a hyperlink click occurs.

function BossNotesExample:OnHyperlinkClick (instance, encounter, source, link, text, button)
	BossNotes:Print(string.format("A hyperlink in note \"%s\" clicked using %s",
			source.title, button))
end

API

The following Boss Notes methods are provided for developing provider modules.

BossNotes:Print(message)

Description: Prints a message to the chat.

Arguments:

Return Value: None.

Example:

BossNotes:Print("Hello, world!")

BossNotes:MergeOptions(key, opts)

Description: Merges provider module Ace options with the Boss Notes Ace options. Note that this method must be invoked when the provider module is loaded. Invoking the method during the OnInitialize() method is too late.

Arguments:

Return Value: None.

Example: See the section Registering the Provider above.

BossNotes:RegisterProvider(name, callbacks)

Description: Registers a provider module in Boss Notes.

Arguments:

Return Value: None.

Example: See the section Registering the Provider above.

BossNotes:UnregisterProvider(name)

Description: Unregisters a provider module in Boss Notes.

Arguments:

Return Value: None.

Example: See the section Registering the Provider above.

BossNotes:GetInstances()

Description: Returns all enabled instances.

Arguments: None.

Return Value: An array of instances.

Example:

local instances = BossNotes:GetInstances()
for _, instance in ipairs(instances) do
	BossNotes:Print(instance.name)
end

BossNotes:GetInstanceAndEncounter(npcId)

Description: Returns the instance and an encounter for an NPC ID.

Arguments:

Return Value: The instance (first return value) and encounter (second return value). If the instance is nil, the NPC has no associated instance. If the encounter is nil, the NPC is part of the instance trash.

Example:

local instance, encounter = BossNotes:GetInstanceAndEncounter(15956)
if instance then
	if encounter then
		-- Encounter NPC
		BossNotes:Print(encounter.name)
	else
		-- Trash NPC
		BossNotes:Print(instance.name)
	end
else
	-- Unassociated NPC
	BossNotes:Print("Not associated with an instance or encounter")
end

BossNotes:GetContextKey(instance, encounter)

Description: Returns a context key for an instance and encounter.

Arguments:

Return Value: The context key for the specified instance and encounter.

Example:

local instances = BossNotes:GetInstances()
for _, instance in ipairs(instances) do
	local encounters = instance.encounters
	for _, encounter in ipairs(encounters) do
		local key = BossNotes:GetContextKey(instance, encounter)
		BossNotes:Print(string.format("(%s, %s) -> %s",
				instance.name, encounter.name, key))
	end
end

BossNotes:GetContextText(instance, encounter)

Description: Returns a text representation for an instance and encounter.

Arguments:

Return Value: The text representation. If the encounter is specified, it is the name of the encounter. Else, if the instance is specified, it is the name of the instance. Else it is the string General (localized).

Example:

local instances = BossNotes:GetInstances()
for _, instance in ipairs(instances) do
	local encounters = instance.encounters
	for _, encounter in ipairs(encounters) do
		local text = BossNotes:GetContextText(instance, encounter)
		BossNotes:Print(string.format("(%s, %s) -> %s",
				instance.name, encounter.name, text))
	end
end

BossNotes:InvalidateContextKey(key, immediate)

Description: Invalidates an instance and encounter pair identified by a context key. If the context key corresponds with the current UI selection, Boss Notes queries all provider modules for sources on the instance and encounter pair and updates the UI. Depending on the value of the immediate parameter, this update occurs immediately, or is deferred for a few seconds, thus allowing Boss Notes to queue up multiple invalidations.

Arguments:

Return Value: None.

Example:

-- Force a deferred update of the General category
local key = BossNotes:GetContextKey(nil, nil)
BossNotes:InvalidateContextKey(key, false)