Hermes

Plugin API Documentation

What is the Plugin API?

A Hermes plugin is created by utilizing the Plugin API. Plugins provide the following benefits that the Event API itself does not:

  • Plugins are automatically enabled and disabled by Hermes as needed.
  • Plugins are listed in the "Registered Plugins" section of Hermes' configuration tabs, where users can enable and disable them completely.
  • Plugin profile db (if specified) can be managed by Hermes.
  • Plugin configuration windows (AceConfigDialog) can be displayed within Hermes configuration windows. A separate tab gets created for each plugin configured to support it.

The main advantage of plugin are how it allows a user to configure them from Hermes without having to dig for other options somewhere else. If none of these features seem useful to you, then there's no need to create a plugin.

The latest documentation can be found in the file PluginAPI.lua that ships with Hermes. There it lists all events and Hermes methods.

Getting Started

These are the steps required to make your addon a Hermes plugin:

Step 1: Update your TOC file

In the RequiredDeps section of your TOC file, add Hermes as a dependency. This ensures that all Hermes dependencies (such as Ace, LibStub, etc.) are loaded before your addon is loaded.

## RequiredDeps: Hermes

Step 2: Create a reference to Hermes In Your Lua file

Ideally near the top of your Lua file, get a reference to the Hermes addon. This will be used everywhere else in your addon.

local Hermes = LibStub("AceAddon-3.0"):GetAddon("Hermes")

Step 3: Register your addon as a Hermes plugin

The best place to do this is inside the OnInitialize event (if our addon uses AceAddon) or after your addon is loaded from the ADDON_LOADED event.

function Hermes:RegisterHermesPlugin(
    PluginName,		--a name that uniquely identifies your plugin.
    OnEnableCallback,	--event fired when Hermes enables your plugin.
    OnDisableCallback,	--event fired when Hermes disables your plugin.
    OnSetProfileCallback,	--event fired when Hermes profile is changed.
    OnGetBlizzOptionsTable	--called when loading the configuration options of your plugin.
    )
PluginName

The name provided is what Hermes exposes to the user in the Registered Plugins area. Just make sure it's unique and represents your addon correctly.

OnEnableCallback

Hermes will call the function your provide here when it enables your plugin. This will fire initially after Hermes loads, and subsequently any time Hermes is reset (such as the user toggling the "Enable Hermes" option in the main config window or the user changing profiles). It can be set to nil if you don't need to react to this. Typically however this is where you would want to initialize any objects as if your addon was starting from scratch.

Function definition:

-- OnEnableCallback is always called immediately after OnSetProfileCallback
function OnEnableCallback() -- no return value
OnDisableCallback

Hermes will call the function your provide here when it disables your plugin. This fires any time Hermes is disabled (such as the user toggling the "Enable Hermes" option in the main config window or the user changing profiles). It can be set to nil if you don't need to react to this. Typically however this is where you would want to reset any values and put your addon into a "fresh" state in preparation for another OnEnableCallback function call.

Function definition:

function OnDisableCallback() -- no return value
OnSetProfileCallback

If you do not want Hermes to manage any Saved Variables for you, then set this to nil. If a valid function is provided, it will be called every time Hermes enables your plugin.

Function definition:

-- OnSetProfileCallback is always called immediately before OnEnableCallback
function OnSetProfileCallback (dbplugins) -- no return value

dbplugins is the root table for all plugin options managed by Hermes. You cannot assume that options for your plugin exist. You should check first and potentially create them if needed.

Here is an example to demonstrate:

...
local dbp = nil -- a local table you keep around that remembers the last set profile table
...

-- assume your OnSetProfileCallback is wired up to call this following function.
-- you can see how to check for existing profile info for your plugin.
-- you can see how to initialize profile info if it doesn't exist.
-- and you can see how to get a reference to the options once done.

function MyAddon:OnSetMyAddonPluginProfile(dbplugins)
    if not dbplugins[MyAddonName] then
        dbplugins[MyAddonName] = { }
    end
    dbp = dbplugins[MyAddonName]
end
OnGetBlizzOptionsTable

Hermes calls this when it wants to load your AceConfig option table. Set to nil if you don't want Hermes to display a configuration tab for your plugin inside of Hermes. If you DO want Hermes to display configuration options, then the return value of this function should return a properly configured AceConfig options table. If your function itself returns nil, then a configuration tab will also not be displayed.

Function definition:

function OnGetBlizzOptionsTable () -- returns nil or an AceConfig options table

Example:

function MyAddon:GetBlizzOptionsTable()
    local options = {
        name = "MyAddon",
        type="group",
        inline = false,
        args = {
            FancyOption = {
                type = "toggle",
                name = "Some Fancy Option",
                get = function(info) return dbp.FancyOption end,
                order = 0,
                set = function(info, value) dbp.FancyOption = value end,
            },
        },
    }

    return options
}

Complete Example

The best idea is to locate existing plugins to see how they do it. However, here is a simplified version of the code for the Hermes_SCT plugin:

local AddonName, Hermes_SCT = ...

-- get a reference to LIB_AceAddon
local LIB_AceAddon = LibStub("AceAddon-3.0") or error("Required library AceAddon-3.0 not found")

-- get a reference to Hermes
local Hermes = LibStub("AceAddon-3.0"):GetAddon("Hermes")

-- register this addon as an AceAddon
_G[AddonName] = LIB_AceAddon:NewAddon(Hermes_SCT, AddonName)

-- called after the addon is loaded by AceAddon
function Hermes_SCT:OnInitialize()
    --register this addon as a hermes plugin
    Hermes:RegisterHermesPlugin(
        AddonName,
        function() return self:OnEnablePlugin() end, -- will get called when the plugin is enabled
        function () return self:OnDisablePlugin() end, -- will get called when the plugin is disabled
        nil, -- profile options are not used
        nil -- AceConfig option tables are not used
    )
end

-- our enable function that we wired up above
function Hermes_SCT:OnEnablePlugin()
        SCT = LIB_AceAddon:GetAddon("SCT", true)

    --register a couple Hermes events using the Event API
    Hermes:RegisterHermesEvent("OnAbilityInstanceStartCooldown", AddonName, function(instance) Hermes_SCT:OnAbilityInstanceStartCooldown(instance) end)
    Hermes:RegisterHermesEvent("OnAbilityInstanceStopCooldown", AddonName, function(instance) Hermes_SCT:OnAbilityInstanceStopCooldown(instance) end)
end

-- our disable function that we wired up above
function Hermes_SCT:OnDisablePlugin()
    Hermes:UnregisterHermesEvent("OnAbilityInstanceStartCooldown", AddonName)
    Hermes:UnregisterHermesEvent("OnAbilityInstanceStopCooldown", AddonName)
end

-- our function for the OnAbilityInstanceStartCooldown event
function Hermes_SCT:OnAbilityInstanceStartCooldown(instance)
        -- something just went on cooldown!
end

-- our function for the OnAbilityInstanceStopCooldownevent
function Hermes_SCT:OnAbilityInstanceStopCooldown(instance)
        -- a cooldown just finished!
end

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