Boss Notes

Boss Notes Provider Modules

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.

KeyDescription
instanceIdThe non-localized, alphanumeric ID of the instance.
nameThe localized name of the instance.
npcIdsAn array with NPC IDs of trash mobs in the instance.
encountersAn array of encounters in the instance.

Encounter

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

KeyDescription
encounterIdThe non-localized, numeric ID of the encounter.
nameThe localized name of the encounter.
npcIdsAn array with NPC IDs of mobs that are part of the encounter.

Source

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

KeyDescriptionDefault
orderThe sorting order, normally one of BOSS_NOTES_ORDER_PERSONAL, BOSS_NOTES_ORDER_COLLECTION, BOSS_NOTES_ORDER_COMMUNITY.BOSS_NOTES_ORDER_COLLECTION
colorTable with keys r, g, b and corresponding values in [0.0, 1.0] specifying the color of the informationBoss Notes default color.
titleThe title of the information.Provider key.
tagA tag that appears in round brackets to the right of the title.No tag.
contentThe content of the information (plain text or simple HTML, including UI escape sequences).No content.
placeholderA placeholder text that is displayed if the content is empty, such as <Click to edit.>.No placeholder.
showHyperlinkTooltipIndicates whether a GameTooltip should be displayed when hyperlinks in the content are mouseovered.No tooltip.
timeA timestamp in seconds since January 1, 1970 GMT indicating when the information was last updated.No timestamp.
clientVersionThe version of the game client at the time the information was last updated.No client version.

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:

CallbackImplementationDescription
OnSourcesrequiredQueries sources from the provider module.
OnRefreshoptionalNotifies the provider module that the user has requested a refresh of the sources.
OnClickoptionalNotifies the provider module that one its sources has been clicked.
OnHyperlinkClickoptionalNotifies the provider module that a hyperlink in one of its sources has been clicked.

These callbacks are described in the following sections.

OnSources

Description: Queries sources from the provider module.

Arguments:

ArgumentDescription
instanceThe selected instance, or nil if none.
encounterThe selected encounter, or nil if none.

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:

ArgumentDescription
instanceThe selected instance, or nil if none.
encounterThe selected encounter, or nil if none.

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:

ArgumentDescription
instanceThe selected instance, or nil if none.
encounterThe selected encounter, or nil if none.
sourceThe source that has been clicked.
buttonThe mouse button, for example "LeftButton".

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

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

Arguments:

ArgumentDescription
instanceThe selected instance, or nil if none.
encounterThe selected encounter, or nil if none.
sourceThe source that has been clicked.
linkThe link that has been clicked.
textThe text of the link that has been clicked.
buttonThe mouse button, for example "LeftButton".

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:

ArgumentDescription
messageThe message to print.

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:

ArgumentDescription
keyAn Ace options key. The key is set in the args table of a group type option.
optsAn Ace options table which is set as the value of the key and has its order key set automatically.

Return Value: None.

Example: See the section Registering the Provider above.

BossNotes:RegisterProvider(name, callbacks)

Description: Registers a provider module in Boss Notes.

Arguments:

ArgumentDescription
nameThe provider module key.
callbacksA table of callbacks.

Return Value: None.

Example: See the section Registering the Provider above.

BossNotes:UnregisterProvider(name)

Description: Unregisters a provider module in Boss Notes.

Arguments:

ArgumentDescription
nameThe provider module key.

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:

ArgumentDescription
npcIdThe ID of the NPC to query.

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:

ArgumentDescription
instanceThe instance, or nil if none.
encounterThe encounter, or nil if none.

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:

ArgumentDescription
instanceThe instance, or nil if none.
encounterThe encounter, or nil if none.

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:

ArgumentDescription
keyThe context key identifying the instance and encounter, see BossNotes:GetContextKey().
immediateWhether the UI update is immediate or deferred for a few seconds.

Return Value: None.

Example:

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

You must login to post a comment. Don't have an account? Register to get one!