Changes: Lawbringer Armor

Revision as of 18:20, 24 March 2011

Getting Started

Since this is a tutorial about using the Ace3 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: 40000
## Version: 0.1
## Title: Welcome Home
## Author: Your Name Here
## Notes: Displays a welcome message when you get to your home zone.

Core.lua

These are the basic metadata associated with your addon. There are many other attributes you can include in your TOC file, for a more comprehensive list see the TOC format.

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 Ace3 to the Party

Since this tutorial is about learning to create addons using Ace3, it is time for us to go ahead and bring those libraries into our addon. Ace3 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://www.wowace.com/addons/ace3/files/. Download Ace3. 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 and files except these:

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

You should now have a folder structure something like this:

WelcomeHome
 - Libs
    - AceAddon-3.0
         AceAddon-3.0.lua
         AceAddon-3.0.xml
    - AceConfig-3.0
         AceConfigCmd-3.0
         AceConfigDialog-3.0
         AceConfigDropdown-3.0
         AceConfigRegistry-3.0
         AceConfig-3.0.lua
         AceConfig-3.0.xml
    - AceConsole-3.0
         AceConsole-3.0.lua
         AceConsole-3.0.xml
    - AceDB-3.0
         AceDB-3.0.lua
         AceDB-3.0.xml
    - AceEvent-3.0
         AceEvent-3.0.lua
         AceEvent-3.0.xml
    - AceGUI-3.0
         widgets
         AceGUI-3.0.lua
         AceGUI-3.0.xml
    - CallbackHandler-1.0
         CallbackHandler-1.0.lua
         CallbackHandler-1.0.xml
    - LibStub
         LibStub.lua
   Core.lua
   WelcomeHome.toc

You now have the necessary Ace3 libraries in your addon's Libs folder, but if you were to launch WoW right now, they wouldn't be loaded. We need to tell WoW to load the files when it loads your addon and for that we're going to use a file called embeds.xml. So create a new file with the text below and save it as "embeds.xml" in the same folder as your .TOC file.

<Ui xmlns="http://www.blizzard.com/wow/ui/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/ ..\FrameXML\UI.xsd">

    <Script file="Libs\LibStub\LibStub.lua"/>
    <Include file="Libs\CallbackHandler-1.0\CallbackHandler-1.0.xml"/>
    <Include file="Libs\AceAddon-3.0\AceAddon-3.0.xml"/>
    <Include file="Libs\AceEvent-3.0\AceEvent-3.0.xml"/>
    <Include file="Libs\AceDB-3.0\AceDB-3.0.xml"/>
    <Include file="Libs\AceConsole-3.0\AceConsole-3.0.xml"/>
    <Include file="Libs\AceGUI-3.0\AceGUI-3.0.xml"/>
    <Include file="Libs\AceConfig-3.0\AceConfig-3.0.xml"/>
</Ui>

The first three lines are just some xml-voodoo, just copy and paste. Then it's a line each for all the libraries we want to load. It is vital that we load LibStub first, since all the other libs depend on that. Then CallbackHandler that is used by several of our libraries and AceGUI needs to be loaded before AceConfig. Otherwise the order isn't important. To be safe, the correct load order can be found in the Ace3.toc file. Notice that it's <Script /> to load lua files and <Include /> to load xml files.

Now let's update the .TOC file to include the embeds.xml. We include it above Core.lua to ensure that the libraries are loaded and available before the code in Core.lua is executed.

## Interface: 40000
## Version: 0.1
## Title: Welcome Home
## Author: Your Name Here
## Notes: Displays a welcome message when you get to your home zone.
## SavedVariables: WelcomeHomeDB
## OptionalDeps: Ace3
## X-Embeds: Ace3

embeds.xml

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 Ace3 instead of using the embedded libraries in your Libs folder and the X-Embeds is there to tell updaters what libs it needs to download separately if the user don't want to use the embedded libs.

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 = LibStub("AceAddon-3.0"):NewAddon("WelcomeHome", "AceConsole-3.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 Ace3 addon. The first line creates an instance of the AceAddon class using the NewAddon 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-3.0. Among other things, the AceConsole-3.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 OnDisable method since we won't be using it.

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.

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 addon. We need to change the line where we create our addon to include the AceEvent-3.0 mixin. Change your first line as shown here:

WelcomeHome = LibStub("AceAddon-3.0"):NewAddon("WelcomeHome", "AceConsole-3.0", "AceEvent-3.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-3.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 change 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.

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 with any of your addons or if you have the standalone version of Ace3, 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 with AceConfig-3.0:

WelcomeHome = LibStub("AceAddon-3.0"):NewAddon("WelcomeHome", "AceConsole-3.0", "AceEvent-3.0")

local options = {
    name = "WelcomeHome",
    handler = WelcomeHome,
    type = 'group',
    args = {
    },
}

function WelcomeHome:OnInitialize()
    -- Called when the addon is loaded
    LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome", options, {"welcomehome", "wh"})
end

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 AceConfig 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.

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

local options = { 
    name = "WelcomeHome",
    handler = WelcomeHome,
    type = "group",
    args = {
        msg = {
            type = "input",
            name = "Message",
            desc = "The message to be displayed when you get home.",
            usage = "<Your message>",
            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(info)
    return self.message
end

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

Note: You can find more information to the info argument here. Using the info argument is an advanced topic, for beginners it's enough to know that there is such an argument, so just ignore it until you get more familiar with AceConfig-3.0.

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 RegisterOptionsTable:

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.

GUI and Blizzard Interface Options

But why stop at chat commands? All cool addons have a Graphical User Interface these days so WelcomeHome shouldn't be any different! When Blizzard remade their Interface Options with patch 2.4 they introduced the ability for addons to add their options to the "Addons" tab. For this we need first to handle our chat commands slightly different.

function WelcomeHome:OnInitialize()
    -- Called when the addon is loaded
    LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome", options)
    self:RegisterChatCommand("welcomehome", "ChatCommand")
    self:RegisterChatCommand("wh", "ChatCommand")
    WelcomeHome.message = "Welcome Home!"
end

Now to include our addon options to the "Addons" tab, all we need to do is call the AceConfigDialog-3.0 method AddToBlizOptions. This method returns a frame we need to specify later to open the Blizzard Interface Options at the page for our options, so we save it in self.optionsFrame.

function WelcomeHome:OnInitialize()
    -- Called when the addon is loaded
    LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome", options)
    self.optionsFrame = LibStub("AceConfigDialog-3.0"):AddToBlizOptions("WelcomeHome", "WelcomeHome")
    self:RegisterChatCommand("wh", "ChatCommand")
    self:RegisterChatCommand("welcomehome", "ChatCommand")
    WelcomeHome.message = "Welcome Home!"
end

Here we use the AceConsole method RegisterChatCommand to make /welcomehome and /wh call our ChatCommand method instead. In this function we can do whatever we want. And we want AceConfigDialog to open a GUI for our options if there's no other input, otherwise we'll let AceConfigCmd handle the input like it would before. This way we have both a GUI and chat commands (using the same options table) so our users can use whatever they please.

function WelcomeHome:ChatCommand(input)
    if not input or input:trim() == "" then
        InterfaceOptionsFrame_OpenToCategory(self.optionsFrame)
    else
        LibStub("AceConfigCmd-3.0").HandleCommand(WelcomeHome, "wh", "WelcomeHome", input)
    end
end

Try it now 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 = {
    name = "WelcomeHome",
    handler = WelcomeHome,
    type = "group",
    args = {
        msg = {
            type = "input",
            name = "Message",
            desc = "The message text to be displayed",
            usage = "<Your message here>",
            get = "GetMessage",
            set = "SetMessage",
        },
        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(info)
    return self.showInChat
end

function WelcomeHome:ToggleShowInChat(info, value)
    self.showInChat = value
end

function WelcomeHome:IsShowOnScreen(info)
    return self.showOnScreen
end

function WelcomeHome:ToggleShowOnScreen(info, value)
    self.showOnScreen = value
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

Note: 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-3.0. We already have the library listed in our TOC file, and now it's time to use it.

local defaults = {
    profile = {
        message = "Welcome Home!",
        showInChat = false,
        showOnScreen = true,
    },
}

function WelcomeHome:OnInitialize()
    -- Called when the addon is loaded
    self.db = LibStub("AceDB-3.0"):New("WelcomeHomeDB", defaults, "Default")

    LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome", options)
    self.optionsFrame = LibStub("AceConfigDialog-3.0"):AddToBlizOptions("WelcomeHome", "WelcomeHome")
    self:RegisterChatCommand("wh", "ChatCommand")
    self:RegisterChatCommand("welcomehome", "ChatCommand")
end

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

The string "WelcomeHomeDB" refer to the SavedVariables definition in the TOC file. If you don't specify anything for the third argument all characters using the addon will get their own profile. Here we specify "Default". This means that unless you change profile manually all character will share the same "Default" profile.

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(info)
    return self.db.profile.message
end

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

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

function WelcomeHome:ToggleShowInChat(info, value)
    self.db.profile.showInChat = value
end

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

function WelcomeHome:ToggleShowOnScreen(info, value)
    self.db.profile.showOnScreen = value
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.)

With Ace3, we do this using the AceLocale-3.0 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-3.0 to the Project

Let's start by grabbing the AceLocale-3.0 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><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> WelcomeHome
 <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> Libs
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceAddon-3.0
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceAddon-3.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceAddon-3.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceConfig-3.0
     <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceConfigCmd-3.0
     <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceConfigDialog-3.0
     <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceConfigDropdown-3.0
     <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceConfigRegistry-3.0
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceConfig-3.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceConfig-3.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceConsole-3.0
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceConsole-3.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceConsole-3.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceDB-3.0
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceDB-3.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceDB-3.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceEvent-3.0
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceEvent-3.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceEvent-3.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceGUI-3.0
     <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> widgets
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceGUI-3.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceGUI-3.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> AceLocale-3.0
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceLocale-3.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> AceLocale-3.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> CallbackHandler-1.0
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> CallbackHandler-1.0.lua
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> CallbackHandler-1.0.xml
   <html><img src="/mediawiki/images/a/a4/Folder.png" alt="Image:Folder.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> LibStub
     <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:Folder.png" /></html> LibStub.lua
 <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> Core.lua
 <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> embeds.xml
 <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> Locale-enUS.lua
 <html><img src="/mediawiki/images/b/b0/File.png" alt="Image:File.png" width="16" height="16" longdesc="/wiki/Image:File.png" /></html> WelcomeHome.toc

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

<Ui xmlns="http://www.blizzard.com/wow/ui/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Script file="Libs\LibStub\LibStub.lua"/>
<Include file="Libs\CallbackHandler-1.0\CallbackHandler-1.0.xml"/>
<Include file="Libs\AceAddon-3.0\AceAddon-3.0.xml"/>
<Include file="libs\AceGUI-3.0\AceGUI-3.0.xml"/>
<Include file="libs\AceConfig-3.0\AceConfig-3.0.xml"/>
<Include file="Libs\AceConsole-3.0\AceConsole-3.0.xml"/>
<Include file="Libs\AceDB-3.0\AceDB-3.0.xml"/>
<Include file="Libs\AceEvent-3.0\AceEvent-3.0.xml"/>
<Include file="Libs\AceLocale-3.0\AceLocale-3.0.xml"/>
</Ui>

And our .TOC file:

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

embeds.xml

Locale-enUS.lua
Core.lua

Notice that the localization file comes before the Core.lua file. This is important or your localization database will 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 = LibStub("AceLocale-3.0"):NewLocale("WelcomeHome", "enUS", true)

-- Chat commands
L["welcomehome"] = true
L["wh"] = true

L["Welcome Home!"] = true -- default message

L["Message"] = true
L["The message to be displayed when you get home."] = true
L["<Your message>"] = true -- usage

L["Show in Chat"] = true
L["Toggles the display of the message in the chat window."] = true

L["Show on Screen"] = true
L["Toggles the display of the message on the screen."] = true

This file has two parts. The first part creates a new AceLocale instance with the name "WelcomeHome". "enUS" is the language code for US English and true as the third argument tells AceLocale that this is the default locale. The second part is the actual translations. 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

To use AceLocale in our addon now we ask AceLocale for an instance with translations and it will give us a table for the current locale or the default if the it don't have a translation for the language the user is playing in.

Now, add the following line to the top of Core.lua (be sure you add it above the options table definition).

local L = LibStub("AceLocale-3.0"):GetLocale("WelcomeHome")

Now we can use this anywhere we need a translated string by putting L[ ] around it. For example the first part of our options table now becomes this:

local options = {
    name = "WelcomeHome",
    handler = WelcomeHome,
    type = "group",
    args = {
        msg = {
            type = "input",
            name = L["Message"],
            desc = L["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.

Mixed-in variables

If you want to use text elements mixed with variables for different output you can also use functions in your locale table. So the word or text element order does not matter in your script and translations will sound more natural.

-- enUS/enGB:
L['We heartly welcome player X.'] = function(X)
  return 'We heartly welcome player ' .. X;
end

-- deDE:
L['We heartly welcome player X.'] = function(X)
  return 'Wir hei\195\159en Spieler ' .. X .. ' herzlich Willkommen';
end

-- script.lua:
self:Print(L['We heartly welcome player X.'](playername));

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 Ace3 development and leads you down the road to successful addon authoring. Best of luck!

Join the Ace Community

As you get more interested in Ace3 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 Ace3 addon at wowinterface.com in their Ace section.

Final Source Files

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

WelcomeHome.toc

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

embeds.xml

Locale-enUS.lua
Core.lua

embeds.xml

<Ui xmlns="http://www.blizzard.com/wow/ui/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Script file="Libs\LibStub\LibStub.lua"/>
<Include file="Libs\CallbackHandler-1.0\CallbackHandler-1.0.xml"/>
<Include file="Libs\AceAddon-3.0\AceAddon-3.0.xml"/>
<Include file="Libs\AceGUI-3.0\AceGUI-3.0.xml"/>
<Include file="Libs\AceConfig-3.0\AceConfig-3.0.xml"/>
<Include file="Libs\AceConsole-3.0\AceConsole-3.0.xml"/>
<Include file="Libs\AceDB-3.0\AceDB-3.0.xml"/>
<Include file="Libs\AceEvent-3.0\AceEvent-3.0.xml"/>
<Include file="Libs\AceLocale-3.0\AceLocale-3.0.xml"/>
</Ui>

Core.lua

WelcomeHome = LibStub("AceAddon-3.0"):NewAddon("WelcomeHome", "AceConsole-3.0", "AceEvent-3.0")
local L = LibStub("AceLocale-3.0"):GetLocale("WelcomeHome")


local options = {
    name = "WelcomeHome",
    handler = WelcomeHome,
    type = "group",
    args = {
        msg = {
            type = "input",
            name = L["Message"],
            desc = L["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["Toggles the display of the message in the chat window."],
            get = "IsShowInChat",
            set = "ToggleShowInChat",
        },
        showOnScreen = {
            type = "toggle",
            name = L["Show on Screen"],
            desc = L["Toggles the display of the message on the screen."],
            get = "IsShowOnScreen",
            set = "ToggleShowOnScreen",
        },
    },
}

local defaults = {
    profile =  {
        message = L["Welcome Home!"],
        showInChat = false,
        showOnScreen = true,
    },
}

function WelcomeHome:OnInitialize()
    -- Called when the addon is loaded
    self.db = LibStub("AceDB-3.0"):New("WelcomeHomeDB", defaults, "Default")

    LibStub("AceConfig-3.0"):RegisterOptionsTable("WelcomeHome", options)
    self.optionsFrame = LibStub("AceConfigDialog-3.0"):AddToBlizOptions("WelcomeHome", "WelcomeHome")
    self:RegisterChatCommand("wh", "ChatCommand")
    self:RegisterChatCommand("welcomehome", "ChatCommand")
end

function WelcomeHome:OnEnable()
    -- Called when the addon is enabled
    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:ChatCommand(input)
    if not input or input:trim() == "" then
        InterfaceOptionsFrame_OpenToCategory(self.optionsFrame)
    else
        LibStub("AceConfigCmd-3.0").HandleCommand(WelcomeHome, "wh", "WelcomeHome", input)
    end
end

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

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

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

function WelcomeHome:ToggleShowInChat(info, value)
    self.db.profile.showInChat = value
end

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

function WelcomeHome:ToggleShowOnScreen(info, value)
    self.db.profile.showOnScreen = value
end

Locale-enUS.lua

local L = LibStub("AceLocale-3.0"):NewLocale("WelcomeHome", "enUS", true)

-- Chat commands
L["welcomehome"] = true
L["wh"] = true

L["Welcome Home!"] = true -- default message

L["Message"] = true
L["The message to be displayed when you get home."] = true
L["<Your message>"] = true -- usage

L["Show in Chat"] = true
L["Toggles the display of the message in the chat window."] = true

L["Show on Screen"] = true
L["Toggles the display of the message on the screen."] = true

Attribution

This is an import from WelcomeHome - Your first Ace3 Addon, which is a continuation from WelcomeHome - Your first Ace2 Addon

Wowpedia