AceAddon-2.0

From WowAce Wiki
Jump to: navigation, search

AceAddon-2.0 is a basis for Addons to use that provides an easy interface for mixins to plug in to and that handles simple initialization events.

What it does

AceAddon-2.0 doesn't do too much on its own. It mainly functions through mixins such as AceHook-2.1, AceEvent-2.0, and AceConsole-2.0.

On its own, AceAddon does a few things:

  • Automatically injects data into fields by getting data from the TOC at ADDON_LOADED.
    • Name -> .name
    • Title -> .title
    • Notes -> .notes
    • Version -> .version
    • X-Category -> .category (see Ace2 Categories)
    • X-Date -> .date
    • X-eMail -> .email
    • X-Website -> .website
  • It calls :OnInitialize(name) at ADDON_LOADED
  • It calls OnEnable() at PLAYER_LOGIN
    • Note: if PLAYER_LOGIN has already occurred, calls this right away.
  • Provides :PrintAddonInfo(), which prints out the 8 points of data as listed above.
  • Provides :ToString(), which returns the title or name of the addon if available.

Example

A technically full addon would be as follows:

 MyAddon = AceLibrary("AceAddon-2.0"):new()
 
 function MyAddon:OnInitialize()
   -- code here, executed only once.
 end
 
 function MyAddon:OnEnable(first)
   -- code here, executed after everything is loaded.
   -- Note: AceDB-2.0 will also call this when standby is toggled.
 end

Mixins make up the meat of an addon, without them, it's quite bare.

API Documentation

:new(...) [Static]

Returns a new instance of AceAddon with the specified mixins.

Args

... 
list of mixins. (up to 20)
Mixins can either be strings (e.g. "AceEvent-2.0") or references (e.g. AceLibrary("AceEvent-2.0"))

Returns

A new instance of AceAddon

Example

 MyAddon = AceLibrary("AceAddon-2.0"):new("AceEvent-2.0", "AceConsole-2.0", "AceHook-2.0")

:OnInitialize("name")

Method to optionally override to be called on ADDON_LOADED.

Args

"name" 
string - name of the AddOn

Remarks

For each mixin you have, it will call :OnEmbedInitialize(addon, "name") if available.

Saved variables for the addon will be available at this point.
Also, never call this manually.

Example

 function MyAddon:OnInitialize(name)
   -- do fun stuff here
 end

:OnEnable(first)

Method to optionally override to be called either on PLAYER_LOGIN, or a manually specified event. (specify in OnInitialize)

Args

first 
boolean - whether this is the first time :OnEnable is called.

Remarks

For each mixin you have, it will call :OnEmbedEnable(addon, first) if available.

Aside from being called on PLAYER_LOGIN, this will also be called by AceDB-2.0 when coming out of standby mode. If you start off in standby mode, this will not be called on PLAYER_LOGIN.

If PLAYER_LOGIN has already been triggered (such as with LoadOnDemand addons), this will fire right after :OnInitialize()

Example

 function MyAddon:OnEnable(first)
   -- do fun stuff here
 end

:OnDisable()

Method to optionally override to be called when AceDB-2.0 puts the addon on standby.

Remarks

This will only be worthwhile if you have AceDB-2.0 as a mixin. Some Mixins will unregister at this point, e.g. AceEvent-2.0 will automatically unregister all events and AceHook-2.0 will automatically unregister all hooks.

Example

 function MyAddon:OnDisable()
   -- do fun stuff here
 end

:ToString()

Returns a string representation of the addon, either its title, its name, or "<AceAddon instance>".

Returns

string - A string representation of the addon

Example

 local text = MyAddon:ToString()
 -- or
 local text = tostring(MyAddon)

:Inject(t)

Injects the addon with fields from a given table.

Args

table - table containing fields to be injected

Remarks

It is typically a better practice to manually add fields to the addon proper instead of through :Inject().

Example

 MyAddon:Inject({
   MyMethod = function(self)
       -- fun code here
   end
 })
 MyAddon:MyMethod()

:PrintAddonInfo()

Prints out addon info to DEFAULT_CHAT_FRAME. This will print out the title, version, author, date, category, e-mail address, website, and notes.

Remarks

If you have AceConsole-2.0, this would be accessed through `/myaddon about`

Example

 MyAddon:PrintAddonInfo()

The following fields are all populated at ADDON_LOADED, before OnInitialize(). They will not be overridden if already specified

name

string - Folder name of the addon.

title

string - Title of the addon. In the TOC, Title.

version

string - Version of the addon. In the TOC, Version. If you have an svn revision string, e.g. $Revision: 256 $, it will be automatically stripped for the number. e.g. 1.2.$Revision: 256 $ => 1.2.256

notes

string - Notes for the addon. In the TOC, Notes.

author

string - Author(s) of the addon. In the TOC, Author.

date

string - Release date of the addon. In the TOC, X-Date (alternatively X-ReleaseDate). If you have an svn revision string, e.g. $Date: 2006-06-26 $, it will be automatically stripped for the date.

category

string - Category of the addon. In the TOC, X-Category. Always state in English, from the [[Ace2_Category_List" title="Ace2 Category List">Ace2 Category List]]. If not in the list of categories, will assume nil/Other/Unknown

email

string - email address of the author(s). In the TOC, X-eMail. (alternatively X-Email)

website

string - Website of the addon. In the TOC, X-Website. Include the full url, including http://

Event: Ace2_AddonInitialized

Triggered right after an addon has been initialized.

Args

addon 
table - the addon that was initialized

Example

 self:RegisterEvent("Ace2_AddonInitialized")

Event: Ace2_AddonEnabled

Triggered right after an addon has been enabled.

Args

addon 
table - the addon that was enabled
first 
boolean - whether this is the first time :OnEnable is called.

Example

 self:RegisterEvent("Ace2_AddonEnabled")