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.

localHermes=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.

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 OnSetProfileCallbackfunctionOnEnableCallback()-- 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:

functionOnDisableCallback()-- 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 OnEnableCallbackfunctionOnSetProfileCallback(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:

...localdbp=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.functionMyAddon:OnSetMyAddonPluginProfile(dbplugins)ifnotdbplugins[MyAddonName]thendbplugins[MyAddonName]={}enddbp=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.

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:

localAddonName,Hermes_SCT=...-- get a reference to LIB_AceAddonlocalLIB_AceAddon=LibStub("AceAddon-3.0")orerror("Required library AceAddon-3.0 not found")-- get a reference to HermeslocalHermes=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 AceAddonfunctionHermes_SCT:OnInitialize()--register this addon as a hermes pluginHermes:RegisterHermesPlugin(AddonName,function()returnself:OnEnablePlugin()end,-- will get called when the plugin is enabledfunction()returnself:OnDisablePlugin()end,-- will get called when the plugin is disablednil,-- profile options are not usednil-- AceConfig option tables are not used)end-- our enable function that we wired up abovefunctionHermes_SCT:OnEnablePlugin()SCT=LIB_AceAddon:GetAddon("SCT",true)--register a couple Hermes events using the Event APIHermes: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 abovefunctionHermes_SCT:OnDisablePlugin()Hermes:UnregisterHermesEvent("OnAbilityInstanceStartCooldown",AddonName)Hermes:UnregisterHermesEvent("OnAbilityInstanceStopCooldown",AddonName)end-- our function for the OnAbilityInstanceStartCooldown eventfunctionHermes_SCT:OnAbilityInstanceStartCooldown(instance)-- something just went on cooldown!end-- our function for the OnAbilityInstanceStopCooldowneventfunctionHermes_SCT:OnAbilityInstanceStopCooldown(instance)-- a cooldown just finished!end