WelcomeHome - Your first Ace2 Addon

From WowAce Wiki
Jump to: navigation, search

Introduction

Getting Started

Since this is a tutorial about using the Ace2 libraries, I will start by showing you what we need to do to get a barebones Addon loaded into the game.

Every addon is stored in a folder underneath the WoW main folder called <WoW>\Interface\Addons. Each addon goes in its own folder named after the addon. So to get started we will create a new folder called “WelcomeHome”.

When WoW finds a folder in the Addons directory, it looks inside that folder for a table of contents (TOC) file that has the same name as the folder. This TOC file contains a manifest of all the other files that make up the addon and is used by WoW to load your addon.

Let’s go ahead and create a barebones TOC file called WelcomeHome.toc:

## Interface: 20200
## Title: Welcome Home
## Notes: Displays a welcome message when you get to your home zone.
## Author: Your Name Here
## Version: 0.1
## X-Category: Interface Enhancements 

Core.lua

These are the basic metadata associated with your addon. For the X-Category option, it is recommended that you pick one of the Ace2 Categories to be consistent with the rest of Ace. There are many other attributes you can include in your TOC file, for a more comprehensive list see The TOC Format on wowwiki.com.

Then create an empty text file called Core.lua in the same directory and start up WoW. After logging in, you should be able to click the “Addons” button in the lower left and see that your addon is being recognized by the game. Go ahead and make sure that it is enabled before exiting out of that screen and then out of the game.

Step 1 complete! We are in the game. But we aren’t doing anything yet. That is next.

Bringing Ace2 to the Party

Since this tutorial is about learning to create addons using Ace2, it is time for us to go ahead and bring those libraries into our addon. Ace2 uses a concept called “Embedded Libraries” that allows mod developers to have the libraries in their codebase without actually duplicating the code when it is loaded along side other mods that use the same libraries.

This means you need to get local copies of the libraries you intend to use. At this point the easiest way to do this is to download them from the Ace SVN files mirror and put them on your system.

Open a browser and go to http://files.wowace.com/. Download Ace2. This is the most recent build of the Ace libraries. Unzip it into a folder called Libs in your Addon's directory. Then go ahead and delete all of the new folders except these:

There are lots of Ace2 libraries for you to use, but for this tutorial we only need a few. For more information on these libraries, please visit the Ace2 page.

You should now have a folder structure something like this:

<html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> WelcomeHome
 <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> Libs
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceAddon-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceAddon-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceConsole-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceConsole-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceDB-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceDB-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceEvent-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceEvent-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceLibrary
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceLibrary.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceOO-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceOO-2.0.lua
 <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> WelcomeHome.toc
 <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> Core.lua

You now have the necessary Ace2 libraries in your addon's Libs folder, but if you were to launch WoW right now, they wouldn't be loaded because they aren't listed in your .TOC file. So let's update the .TOC file to include them. We include them above Core.lua to ensure that they are loaded and available before the code in Core.lua is executed.

## Interface: 20100
## Title: Welcome Home
## Notes: Displays a welcome message when you get to your home zone.
## Author: Your Name Here
## Version: 0.1
## OptionalDeps: Ace2
## SavedVariables: WelcomeHomeDB
## SavedVariablesPerCharacter: WelcomeHomeDBPC
## X-Category: Interface Enhancements

Libs\AceLibrary\AceLibrary.lua
Libs\AceOO-2.0\AceOO-2.0.lua
Libs\AceAddon-2.0\AceAddon-2.0.lua
Libs\AceDB-2.0\AceDB-2.0.lua
Libs\AceConsole-2.0\AceConsole-2.0.lua
Libs\AceEvent-2.0\AceEvent-2.0.lua

Core.lua

I've included a few other things in the TOC that aren't actually required yet (e.g. SavedVariables), but we will need all of that eventually. The OptionalDeps part is there in case a user of your addon comes along later and chooses to use a standalone Ace2 instead of using the embedded libraries in your Libs folder.

Saying Hello

This section is going to move a little faster than we have been moving. Start by opening Core.lua in a text editor and typing in the following code:

WelcomeHome = AceLibrary("AceAddon-2.0"):new("AceConsole-2.0")

function WelcomeHome:OnInitialize()
    -- Called when the addon is loaded
end

function WelcomeHome:OnEnable()
    -- Called when the addon is enabled
end

function WelcomeHome:OnDisable()
    -- Called when the addon is disabled
end

This is the basic starting structure of an Ace2 addon. The first line creates an instance of the AceAddon class using the new() operator. Since we will also be printing to the chat window and accepting slash commands, I've gone ahead and included the mixin for AceConsole-2.0. Among other things, the AceConsole-2.0 mixin will get us access to the Print method.

Mixins are a concept common in many object oriented languages that allow you to bring additional functionality into your class. (For more on mixins, see the mixins page on Wikipedia.)

Following that are three method overrides. The first is executed only once when the UI loads and the next two are executed when the addon is enabled and disabled. (You can enable and disable Ace addons using /ace commands.)

It is important to note that OnEnable is called at the beginning if the addon is enabled when the UI loads. You will often have to choose which of these two method overrides to use. Generally, you should use the OnInitialize for those things that you don't need to undo and redo if the addon is disabled and enabled. Another important part of this decision has to do with what other things you will need and when you can be sure they are ready. More on this later...

Just to demonstrate that the addon is loading, we will have the addon print "Hello World!" to the chat window by adding one line of code to the OnEnable method.

function WelcomeHome:OnEnable()
    self:Print("Hello World!")
end

Go ahead and restart WoW and enter in to the game. Once you are in, you should be able to scroll up in the chat window and find your message. You are now the proud author of the WoW version of Hello World!.

Before we go any further, go back over to your code and remove the print message. It is generally considered bad Ace form for your addon to toss a bunch of text into the chat window just because it has loaded. Too many addons do this already and there are other ways ("/ace list") to find out what Ace addons have loaded. You can also remove the OnInitialize and the OnDisable method since we won't be using them.

Responding to Events

So, as I said, this addon will give a welcome message to the player when they arrive in their home zone. How will we know they are in their home zone? Simple, we will respond to one of the ZONE_CHANGED events which the game fires when the player enters a new zone.

I’m sure you are asking yourself “Events? What the heck are those?” It turns out that like many other programming environments, WoW is event driven. Events are raised when things happen in the game and you can fire events when things happen in your code. In fact, without events, your addon would never even know what to do and when to start doing things. Eventually, everything your addon does is in response to an event.

Looking at the events list, it appears that ZONE_CHANGED will be the one we want, so let's hook that one by making a few changes to our Core.lua file.

Before we can subscribe to events, we need to get event support into our addon by including another mixin into our class. We need to change the line where we create our addon to include the AceEvent-2.0 mixin. Change your first line as shown here:

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

Once we've done that, we will use the RegisterEvent method that is now available to us to subscribe to the ZONE_CHANGED event. We will replace the OnEnable override with the following code:

function WelcomeHome:OnEnable()
    -- Called when the addon is enabled
    self:RegisterEvent("ZONE_CHANGED")
end

We also need to add in the event handler for that event by adding the following code to our Core.lua file:

function WelcomeHome:ZONE_CHANGED()
    self:Print("You have changed zones!")
end

You might be wondering if we should call UnregisterEvent from our OnDisable override, but we don't have to do that because AceEvent-2.0 does it for us.

Now head back into the game and have your character leave the area he/she is presently in. You should see your message go by down in the chat area when you zone.

Reloading Your Addon Without Restarting WoW

Before we go any further, I want to show you a trick that will come in handy for you as you work on your addons.

Leave the game up and running, but switch over to your text editor. Change the event handler as follows...

function WelcomeHome:ZONE_CHANGED()
    self:Print("This is a different message!")
end

Make sure you save your changes and then go back over to the game and switch zones. Which message did you see? The old one.

Why? Because WoW doesn't automatically reload your addon just because you made a change. One way to get your addon reloaded is to restart the game. Ugh. much better way to get it reloaded is by using the ReloadUI() command from the command line using the /script chat command:

/script ReloadUI()

Your screen will freeze for a minute while the UI reloads itself and all your other addons reload, but when it comes back up you should now be able to switch zones and see the new message. You can also use "/console ReloadUI" but I had it fail once and don't know why. I've never had "/script ReloadUI()" fail me, so that is what I use.

From now on you can use this technique to reload your mod when you have made changes.

Note: if you have AceConsole-2.0 loaded, you can use the following command to reload your UI:

/rl

Working with the WoW API

We now have a method that we know will get called when the player changes zones. But what zone is he in? Where does he keep his hearthstone set?

If we head back over to the World of Warcraft API page and look in the Character Functions section, we will see the answer to the second question is a function called GetBindLocation. This function returns the subzone name (e.g. "Tarren Mill") that contains the Inn where your hearthstone is set.

Next we need to figure out how to find what subzone we are in. If we look in the Location Functions section of the API docs, we will find a function called GetSubZoneText that looks about right. It returns either an empty string (if you aren't in a subzone) or the name of the subzone you are in.

We should be able to simply compare these two values in our event handler to decide whether we are home or not:

function WelcomeHome:ZONE_CHANGED()
    if GetBindLocation() == GetSubZoneText() then
        self:Print("Welcome Home!")
    end
end

That's it! We should now have a functional addon doing what we want. Reload your UI and test it out.

Chat Commands and Configuration

But there are still lots of interesting things we can do. Let's start by adding support for the out-of-the-box slash commands by creating an options table at the top of the file and registering it after we create the addon object:

local options = { 
    type='group',
    args = {}
}

WelcomeHome = AceLibrary("AceAddon-2.0"):new("AceConsole-2.0", "AceEvent-2.0")
WelcomeHome:RegisterChatCommand("/welcomehome", "/wh", options)

At this point the options table is empty and we haven't provided any commands. For a complete rundown of the structure of the options table, visit the AceOptions data table docs.

If you reload the UI and type /welcomehome or /wh, you should now see a help message in your chat box that prints the Addon name, description and available commands, which at this point is just the built in 'about' command. Type '/wh about' to see what that command does.

Now lets add a command that lets the user change the text that is displayed by updating the options table:

local options = { 
    type='group',
    args = {
        msg = {
            type = 'text',
            name = 'msg',
            desc = 'The message text to be displayed',
            usage = "<Your message here>",
            get = "GetMessage",
            set = "SetMessage",
        },
    },
}

This will define a new slash command called 'msg' that takes a text argument and uses the functions named to get and set the underlying variables. Let's quickly write those methods:

function WelcomeHome:GetMessage()
    return self.message
end

function WelcomeHome:SetMessage(newValue)
    self.message = newValue
end

Then reload your UI and type "/wh" to see the command. Notice that at this point there is no value for the message string. That is because we didn't provide a default.

We can fix that by adding the following line right after the call to RegisterChatCommand:

WelcomeHome.message = "Welcome Home!"

The final step is to change the print line in our event handler to use the new message:

function WelcomeHome:ZONE_CHANGED()
    if GetBindLocation() == GetSubZoneText() then
        self:Print(self.message)
    end
end

Play around with it for a little while and see how it works.

Making the Message More Prominent

Now that we have the addon working, let's tweak it a bit. Let's add a way to display the message somewhere that is a bit more prominent. To do this we will show the message in a frame called UIErrorsFrame and add some new options to let the user decide what they want.

Note: I'm going to assume that you are starting to figure this out and can figure out where this code goes.

First the new options table:

local options = { 
    type='group',
    args = {
         msg = {
            type = 'text',
            name = 'Message',
            desc = 'The message text to be displayed',
            get = "GetMessage",
            set = "SetMessage",
            usage = "<Your message here>",
        },
        showInChat = {
            type = 'toggle',
            name = 'Show in Chat',
            desc = 'Toggles the display of the message in the chat window',
            get = "IsShowInChat",
            set = "ToggleShowInChat",
        },
        showOnScreen = {
            type = 'toggle',
            name = 'Show on Screen',
            desc = 'Toggles the display of the message on the screen',
            get = "IsShowOnScreen",
            set = "ToggleShowOnScreen"
        },
    },
}

Then the new default values:

WelcomeHome.showInChat = false
WelcomeHome.showOnScreen = true

Implementations of the new command's get/set methods:

function WelcomeHome:IsShowInChat()
    return self.showInChat
end

function WelcomeHome:ToggleShowInChat()
    self.showInChat = not self.showInChat
end

function WelcomeHome:IsShowOnScreen()
    return self.showOnScreen
end

function WelcomeHome:ToggleShowOnScreen()
    self.showOnScreen = not self.showOnScreen
end

And finally the new event handler method:

function WelcomeHome:ZONE_CHANGED()
    if GetBindLocation() == GetSubZoneText() then
        if self.showInChat then
            self:Print(self.message)
        end

        if self.showOnScreen then
            UIErrorsFrame:AddMessage(self.message, 1.0, 1.0, 1.0, 5.0)
        end
    end
end

(You can learn more about ScrollingMessageFrame:AddMessage on wowwiki.com.)

Saving Configuration Between Sessions

One thing you may have noticed is that your settings about where to show the message aren't persisted between sessions. When you logout and back in, you will have the default settings again. This isn't ideal. We should be saving these settings somehow.

WoW provides a way for you to do this called Saved Variables, but there is an Ace way to do it called AceDB-2.0. We already have the library listed in our TOC file, but we haven't included the mixin into our addon:

WelcomeHome = AceLibrary("AceAddon-2.0"):new("AceEvent-2.0", "AceConsole-2.0", "AceDB-2.0")

Next we will replace the code where we set our defaults with the AceDB way of specifying defaults:

WelcomeHome:RegisterDB("WelcomeHomeDB", "WelcomeHomeDBPC")
WelcomeHome:RegisterDefaults("profile", {
    message = "Welcome Home!",
    showInChat = false,
    showOnScreen = true,
} )

(In this example we associate these variables with the Ace2 profile, but you also can associate them with the char, class, realm or account. See AceDB-2.0 API Documentation for more information.)

The values "WelcomeHomeDB" and "WelcomeHomeDBPC" for RegisterDB refer to the SavedVariables and SavedVariablesPerCaharacter definition in the TOC-File.

After that we need to replace all of the references to the old variables (e.g. self.message or WelcomeHome.message) with self.db.profile.<variablename> (e.g. self.db.profile.message). This will require us to change the get/set methods referenced by our options table and our event handler.

Here are the new command get/set methods:

function WelcomeHome:GetMessage()
    return self.db.profile.message
end

function WelcomeHome:SetMessage(newValue)
    self.db.profile.message = newValue
end

function WelcomeHome:IsShowInChat()
    return self.db.profile.showInChat
end

function WelcomeHome:ToggleShowInChat()
    self.db.profile.showInChat = not self.db.profile.showInChat
end

function WelcomeHome:IsShowOnScreen()
    return self.db.profile.showOnScreen
end

function WelcomeHome:ToggleShowOnScreen()
    self.db.profile.showOnScreen = not self.db.profile.showOnScreen
end

And here is the new event handler:

function WelcomeHome:ZONE_CHANGED()
    if GetBindLocation() == GetSubZoneText() then
        if self.db.profile.showInChat then
            self:Print(self.db.profile.message);
        end

        if self.db.profile.showOnScreen then
            UIErrorsFrame:AddMessage(self.db.profile.message, 1.0, 1.0, 1.0, 5.0)
        end
    end
end

As you can see, it was just a simple substitution of the old variable with the new AceDB variable. Reload your UI and nothing should change. Except now if you change any of the settings, they will be persisted across restarts.

This whole exercise was a bit silly, of course, because in a real world addon you would start out using AceDB for your configuration data, but now you know what it is for and why you should be using it.

Localizing Your Strings with AceLocale

One thing a lot of new addon developers (especially those in the U.S.) forget about is how many people will be wanting to use their addon in a non-english version of the game client. This means that there should be a nice easy way for them to localize the strings in your addon into their language. (Or even better, submit the localized strings to you so you can include them in your next release.)

In Ace2, we do this using the new AceLocale-2.2 library. This library is not a mixin like the other libraries we've used so far, so the way we use it is a bit different.

Adding AceLocale-2.2 to the Project

Let's start by grabbing the AceLocale-2.2 folder from the package that we downloaded earlier and putting it into our Libs folder. We also should create our first localization database file. Create an empty file called Locale-enUS.lua and save it in the same folder as your TOC file.

At this point our folder structure should look like this:

<html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> WelcomeHome
 <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> Libs
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceAddon-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceAddon-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceConsole-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceConsole-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceDB-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceDB-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceEvent-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceEvent-2.0.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceLibrary
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceLibrary.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceLocale-2.2
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceLocale-2.2.lua
   <html><a href="/wiki/Image:Folder.png" class="image" title="Image:Folder.png"><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></a></html> AceOO-2.0
     <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> AceOO-2.0.lua
 <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> Core.lua
 <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> Locale-enUS.lua
 <html><a href="/wiki/Image:File.png" class="image" title="Image:File.png"><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></a></html> WelcomeHome.toc

Then, we need to update our TOC file to reference these new files as shown here:

## Interface: 20100
## Title: Welcome Home
## Notes: Displays a welcome message when you get to your home zone.
## Author: Your Name Here
## Version: 0.1
## OptionalDeps: Ace2
## SavedVariables: WelcomeHomeDB
## SavedVariablesPerCharacter: WelcomeHomeDBPC
## X-Category: Interface Enhancements

Libs\AceLibrary\AceLibrary.lua
Libs\AceOO-2.0\AceOO-2.0.lua
Libs\AceAddon-2.0\AceAddon-2.0.lua
Libs\AceDB-2.0\AceDB-2.0.lua
Libs\AceConsole-2.0\AceConsole-2.0.lua
Libs\AceEvent-2.0\AceEvent-2.0.lua
Libs\AceLocale-2.2\AceLocale-2.2.lua

Locale-enUS.lua
Core.lua

Notice that the localization file comes before the Core.lua file. This is important or your localization database may not be initialized before it is used by the code in your addon.

Since we have updated our TOC file, you will need to restart WoW to get these changes loaded into the game. The ReloadUI trick won't work this time. Once you've done that, go ahead and login and make sure everything is still working.

Building the Localization Database

Now that we have a place to put the localized strings for the US English (enUS) version of our Addon, we need to pass through the source code looking for strings that should be localizable. (In your future addon work, I would recommend going ahead and doing this step at the beginning of your development instead of waiting until the end as we did here.)

After taking a pass through Core.lua, I added the following lines to Locale-enUS.lua:

local L = AceLibrary("AceLocale-2.2"):new("WelcomeHome")

L:RegisterTranslations("enUS", function() return {
     ["Slash-Commands"] = { "/welcomehome", "/wh" },
     
     ["Welcome Home!"] = true, -- default message
     
     ["Message"] = true,
     ["Sets the message to be displayed when you get home."] = true,
     ["<your message>"] = true, -- usage
     
     ["Show in Chat"] = true,
     ["If set, your message will be displayed in the General chat window."] = true,
     
     ["Show on Screen"] = true,
     ["If set, your message will be displayed on the screen near the top of the game field."] = true,
} end)

This file has two parts. The first part creates a new AceLocale instance, or retrieves an existing one, with the name "WelcomeHome". The second part registers an anonymous function that returns the enUS versions of the logical string identifiers. Having the values be true makes them the same as their keys. This means that in our code, when we ask for the localized version of "Welcome Home!", we will get "Welcome Home!", or another string depending on the language.

Using the Localized Strings in the Addon

I told you at the beginning of this section that AceLocale isn't a mixin like the other libraries we've used so far. Instead we just access the instance we need for our addon and for the locale we want to support.

To do this, add the following line to the top of Core.lua (be sure you are above the opts table definition.

local L = AceLibrary("AceLocale-2.2"):new("WelcomeHome")

Now we can use this anywhere we need a string. For example the first part of our options table now becomes this:

local opts = { 
    type='group',
    args = {
         msg = {
            type = 'text',
            name = L["Message"],
            desc = L["Sets the message to be displayed when you get home."],
            usage = L["<your message>"],
            get = "GetMessage",
            set = "SetMessage",
        },
        ...etc...
    }
}

This process is pretty straightforward, so I won't bother showing all of it here. You can see the final source files at the end of the article to see if you got them all in your addon.

Using AceLocale is a simple way to get good localization support in your addon. AceLocale is capable of a lot of other interesting things like iterating the translations forward and backward, strict and loose lookups, and reverse lookups. Also in the works is support for dyanamic locales where your addon can switch the locale used for its strings on the fly. These topics are beyond the scope of this tutorial, but you should check out the AceLocale-2.2 API Documentation to see everything that is available.

Conclusion

You have started from nothing and created a localizable addon that uses chat commands, responds to events and provides feedback to the user in a couple of different ways. There are a number of interesting things you can do to this addon if you want to keep going. Some examples:

  • Integrate it with FuBar and provide a configuration menu in addition to slash commands
  • Provide different messages when you zone into other areas (e.g. Welcome to The Badlands, Home of Uldaman!")

Hopefully that helps you get started with Ace2 development and leads you down the road to successful addon authoring. Best of luck!

Join the Ace Community

As you get more interested in Ace2 development, you should consider getting involved in the Ace community at wowace.com. They have a Subversion server for version control, a web-based forum, an IRC channel and a great wiki full of documentation and help.

You also should consider publishing your Ace2 addon at wowinterface.com in their Ace section.

Final Source Files

Here is the final contents of WelcomeHome.toc, Core.lua, and Locale-enUS.lua in case you want to cheat and go right to the end.

WelcomeHome.toc

## Interface: 20200
## Title: Welcome Home
## Notes: Displays a welcome message when you get to your home zone.
## Author: Your Name Here
## Version: 0.1
## OptionalDeps: Ace2
## SavedVariables: WelcomeHomeDB
## SavedVariablesPerCharacter: WelcomeHomeDBPC
## X-Category: Interface Enhancements

Libs\AceLibrary\AceLibrary.lua
Libs\AceOO-2.0\AceOO-2.0.lua
Libs\AceAddon-2.0\AceAddon-2.0.lua
Libs\AceDB-2.0\AceDB-2.0.lua
Libs\AceConsole-2.0\AceConsole-2.0.lua
Libs\AceEvent-2.0\AceEvent-2.0.lua
Libs\AceLocale-2.2\AceLocale-2.2.lua

Locale-enUS.lua
Core.lua

Core.lua

local L = AceLibrary("AceLocale-2.2"):new("WelcomeHome")

local opts = { 
    type='group',
    args = {
         msg = {
            type = 'text',
            name = L["Message"],
            desc = L["Sets the message to be displayed when you get home."],
            usage = L["<your message>"],
            get = "GetMessage",
            set = "SetMessage",
        },
        showInChat = {
            type = 'toggle',
            name = L["Show in Chat"],
            desc = L["If set, your message will be displayed in the General chat window."],
            get = "IsShowInChat",
            set = "ToggleShowInChat",
        },
        showOnScreen = {
            type = 'toggle',
            name = L["Show on Screen"],
            desc = L["If set, your message will be displayed on the screen near the top of the game field."],
            get = "IsShowOnScreen",
            set = "ToggleShowOnScreen"
        },
    },
}

WelcomeHome = AceLibrary("AceAddon-2.0"):new("AceConsole-2.0", "AceEvent-2.0", "AceDB-2.0")
WelcomeHome:RegisterChatCommand(L["Slash-Commands"], opts)

WelcomeHome:RegisterDB("WelcomeHomeDB", "WelcomeHomeDBPC")
WelcomeHome:RegisterDefaults("profile", {
    message = L["Welcome Home!"],
    showInChat = false,
    showOnScreen = true,
} )

function WelcomeHome:OnEnable()
    self:RegisterEvent("ZONE_CHANGED")
end

function WelcomeHome:ZONE_CHANGED()
    if GetBindLocation() == GetSubZoneText() then
        if self.db.profile.showInChat then
            self:Print(self.db.profile.message)
        end

        if self.db.profile.showOnScreen then
            UIErrorsFrame:AddMessage(self.db.profile.message, 1.0, 1.0, 1.0, 5.0)
        end
    end
end

function WelcomeHome:GetMessage()
    return self.db.profile.message
end

function WelcomeHome:SetMessage(newValue)
    self.db.profile.message = newValue
end

function WelcomeHome:IsShowInChat()
    return self.db.profile.showInChat
end

function WelcomeHome:ToggleShowInChat()
    self.db.profile.showInChat = not self.db.profile.showInChat
end

function WelcomeHome:IsShowOnScreen()
    return self.db.profile.showOnScreen
end

function WelcomeHome:ToggleShowOnScreen()
    self.db.profile.showOnScreen = not self.db.profile.showOnScreen
end

Locale-enUS.lua

local L = AceLibrary("AceLocale-2.2"):new("WelcomeHome")

L:RegisterTranslations("enUS", function() return {
     ["Slash-Commands"] = { "/welcomehome", "/wh" },
     
     ["Welcome Home!"] = true, -- default message
     
     ["Message"] = true,
     ["Sets the message to be displayed when you get home."] = true,
     ["<your message>"] = true, -- usage
     
     ["Show in Chat"] = true,
     ["If set, your message will be displayed in the General chat window."] = true,
     
     ["Show on Screen"] = true,
     ["If set, your message will be displayed on the screen near the top of the game field."] = true,
} end)