3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 1/12

Main MenuWoW APIWidget APIMacro APILua functionsEventsWidget handlersData typesXML UIChanges

HOWTOsSnippetsUI tech.

Category nav.

→ HOWTOs

WelcomeHome ­ Your first Ace3 AddonFrom Wowpedia

Contents

1 Introduction2 Getting Started3 Bringing Ace3 to the Party4 Saying Hello5 Responding to Events6 Reloading Your Addon Without Restarting WoW7 Working with the WoW API8 Chat Commands and Configuration9 GUI and Blizzard Interface Options10 Making the Message More Prominent11 Saving Configuration Between Sessions12 Localizing Your Strings with AceLocale

12.1 Adding AceLocale­3.0 to the Project12.2 Building the Localization Database12.3 Using the Localized Strings in the Addon12.4 Mixed­in variables

13 Conclusion14 Join the Ace Community15 Final Source Files

15.1 WelcomeHome.toc15.2 embeds.xml15.3 Core.lua15.4 enUS.lua

16 Attribution

Introduction

Ace3 (http://old.wowace.com/wiki/Ace3) is an AddOn development framework, like (the now abandoned) Rock (http://old.wowace.com/wiki/Rock),Dongle, and Sea.

Before starting this tutorial, it's recommended to read Make it Ace'd (http://old.wowace.com/wiki/Make_it_Ace%27d), and Ace3 Philosophy(http://old.wowace.com/wiki/Ace3#Ace3_Philosophy)

Alternatively, there is the more advanced and official Ace3 Getting Started (http://www.wowace.com/addons/ace3/pages/getting­started/) tutorial

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 theaddon. 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: 40200 ## 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 listsee 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 inthe 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 andthen 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

Help Sign In Register

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 2/12

Since this tutorial is about learning to create addons using Ace3, it is time for us to go ahead and bring those libraries(http://en.wikipedia.org/wiki/Library_%28computing%29) into our addon. Ace3 uses a concept called “Embedded Libraries” that allows mod developers tohave 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 SVNfiles 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 afolder called Libs in your addon's directory. Then go ahead and delete all of the new folders and files except these:

AceAddon­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­addon­3­0/)AceDB­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­db­3­0/)AceConfig­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­config­3­0/)AceConsole­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­console­3­0/)AceEvent­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­event­3­0/)AceGUI­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­gui­3­0/)CallbackHandler­1.0 (http://www.wowace.com/addons/callbackhandler/)LibStub (http://www.wowace.com/addons/libstub/)

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 see the Ace3API docs (http://www.wowace.com/addons/ace3/pages/)

You should now have a folder structure something like this: (See the original (http://old.wowace.com/wiki/WelcomeHome_­_Your_first_Ace3_Addon#Adding_AceLocale­3.0_to_the_Project) for a better view)

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 tellWoW 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 itas "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 line is just some xml­voodoo (http://www.w3.org/TR/xmlschema­1/#Schemas), just copy and paste. Then it's a line each for all the libraries wewant to load. Notice that it's <Script /> to load Lua files and <Include /> to load XML files.

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 needsto be loaded before AceConfig. Otherwise the order isn't important, but to be safe, the correct load order can be found in the Ace3.toc(http://forums.wowace.com/showthread.php?p=299390#post299390) file.

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 codein Core.lua is executed.

## Interface: 40200 ## 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 

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 3/12

## 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. TheOptionalDeps 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 inyour 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(http://www.wowace.com/addons/ace3/pages/api/ace­addon­3­0/#w­ace­addon­new­addon­object­name­lib) method. Since we will also be printing to thechat window and accepting slash commands, I've gone ahead and included the mixin for AceConsole. Among other things, this will get us access to thePrint (http://www.wowace.com/addons/ace3/pages/api/ace­console­3­0/#w­ace­console­print­chatframe) method. There also is print(http://www.lua.org/manual/5.1/manual.html#pdf­print) (with lowercase p), which is a basic Lua function

Mixins (http://en.wikipedia.org/wiki/Mixin) are a concept common in many object oriented languages that allow you to bring additional functionality intoyour class. We're using LibStub (http://www.wowace.com/addons/libstub/) for embedding/mixing­in our libraries

Following that are three method (http://old.wowace.com/wiki/Coding_Tips#Methods) overrides: OnInitialize, OnEnable, and OnDisable respectively.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(http://www.wowace.com/addons/ace3/pages/api/ace­addon­3­0/#w­addon­enable) and Disable (http://www.wowace.com/addons/ace3/pages/api/ace­addon­3­0/#w­addon­disable) Ace addons at will.)

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 twomethod 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 andenabled. 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 thislater...

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

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 arenow 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 bunchof text into the chat window just because it has loaded. Too many addons do this already and there are other ways(http://www.wowace.com/addons/ace3/pages/api/ace­addon­3­0/#w­ace­addon­iterate­addons) to find out what Ace addons have loaded. You can alsoremove 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 wouldnever 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 linewhere we create our addon to include the AceEvent mixin. Change your first line as shown here:

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

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 4/12

Once we've done that, we will use the RegisterEvent (http://www.wowace.com/addons/ace3/pages/api/ace­event­3­0/#w­ace­event­register­event­event­callback­arg) method that is now available to us to subscribe to the ZONE_CHANGED event. We will replace the OnEnable override with the followingcode:

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 <font color="#DDA0DD">Core.lua</font> file: 

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

You might be wondering if we should call UnregisterEvent (http://www.wowace.com/addons/ace3/pages/api/ace­event­3­0/#w­ace­event­unregister­event­event) from our OnDisable override, but we don't have to do that because AceEvent 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 whenyou 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. A much better way to get it reloaded is by entering:

/reload 

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 toswitch 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 (http://old.wowace.com/wiki/AceConsole­2.0) loaded with any of your addons or if you have the standalone version ofAce3 (http://www.wowace.com/addons/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 afunction 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 calledGetSubZoneText 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 atthe top of the file and registering it with AceConfig­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­config­3­0/):

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

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

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 5/12

    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 theAceConfig­3.0 Options Tables (http://www.wowace.com/addons/ace3/pages/ace­config­3­0­options­tables/) page.

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 andavailable 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'squickly write those methods:

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

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

Note: Using the info (http://www.wowace.com/addons/ace3/pages/ace­config­3­0­options­tables/#w­callback­handling) argument is an advanced topic, forbeginners it's enough to know that there is such an argument, so just ignore it until you get more familiar with AceConfig.

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 adefault. We can fix that by adding the following line right after the call to RegisterOptionsTable (http://www.wowace.com/addons/ace3/pages/api/ace­config­3­0/#w­ace­config­register­options­table­app­name­options):

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 Blizzardremade their Interface Options in Patch 2.4 they introduced the ability for addons to add their options to the "AddOns" tab. For this we need first to handleour 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(http://www.wowace.com/addons/ace3/pages/api/ace­config­dialog­3­0/) method AddToBlizOptions (http://www.wowace.com/addons/ace3/pages/api/ace­config­dialog­3­0/#w­ace­config­dialog­add­to­bliz­options­app­name­name). This method returns a frame we need to specify later to open the BlizzardInterface 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) 

Total Security 2015Page is safe

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 6/12

    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 (http://www.wowace.com/addons/ace3/pages/api/ace­console­3­0/#w­ace­console­register­chat­command­command­func­persist) to make /welcomehome and /wh call our ChatCommand method instead. In this function we can do whatever wewant. 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 itwould 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("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 willshow 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 

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 7/12

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

Note: See ScrollingMessageFrame:AddMessage for more info.

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, youwill 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 with the AceDB method, New(http://www.wowace.com/addons/ace3/pages/api/ace­db­3­0/#w­ace­db­new­tbl­defaults­default­profile). We already have the library listed in our .TOCfile, 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, true) 

    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 "data­type", but you also can associate them with char, class, race, faction, realm orglobal . See the AceDB­3.0 (http://www.wowace.com/addons/ace3/pages/api/ace­db­3­0/) docs for more information on data­types.)

The string "WelcomeHomeDB" refers to the SavedVariables definition in the TOC file. If you don't specify anything for the third argument all charactersusing the addon will get their own profile. Here we pass the boolean true. This means that unless you change profile manually all character will share thesame "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 nowif 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 youknow what it is for and why you should be using it.

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 8/12

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­englishversion 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 evenbetter, 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 (http://www.wowace.com/addons/ace3/pages/api/ace­locale­3­0/) library. This library is not a mixin likethe 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 ourfirst localization database file. Create an empty file called enUS.lua and save it in the same folder as your .TOC file.

At this point our folder structure should look like this: (See the original (http://old.wowace.com/wiki/WelcomeHome_­_Your_first_Ace3_Addon#Adding_AceLocale­3.0_to_the_Project) for a better view)

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       AceLocale‐3.0          AceLocale‐3.0.lua          AceLocale‐3.0.xml       CallbackHandler‐1.0          CallbackHandler‐1.0.lua          CallbackHandler‐1.0.xml       LibStub          LibStub.lua    Core.lua    embeds.xml    enUS.lua    WelcomeHome.toc 

Then, we need to update our embeds.xml file to reference to the newly added AceLocale­3.0 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\AceEvent‐3.0\AceEvent‐3.0.xml"/>     <Include file="Libs\AceDB‐3.0\AceDB‐3.0.xml"/>     <Include file="Libs\AceLocale‐3.0\AceLocale‐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> 

And our .TOC file:

## Interface: 40200 ## 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 

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 thecode 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 /reload trick won't work this time. Onceyou've done that, go ahead and login and make sure everything is still working.

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 9/12

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 forstrings that should be localizable. (In your future addon work, I would recommend going ahead and doing this step at the beginning of your developmentinstead of waiting until the end as we did here.)

After taking a pass through Core.lua, I added the following lines to 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 andtrue 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 themthe 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 anotherstring 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 itdoesn't have a translation for the language the user is playing in.

Now, add the following line to the top of Core.lua, this calls the GetLocale (http://www.wowace.com/addons/ace3/pages/api/ace­locale­3­0/#w­ace­locale­get­locale­application­silent) method (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 gotthem all in your addon.

Using AceLocale is a simple way to get good localization support in your addon. [1] (http://kb.wowace.com/projects/localizing­your­project/)

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 orderdoes 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

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 10/12

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 coupleof different ways. There are a number of interesting things you can do to this addon if you want to keep going. Some examples:

Provide a configuration menu (http://www.wowace.com/addons/ace3/pages/ace­config­3­0­options­tables/), in addition to slash commandsAdd support for LibDataBroker (https://github.com/tekkub/libdatabroker­1­1/wiki/) for in e.g. Data Display AddOns [2](http://forums.wowace.com/showthread.php?t=14903)Show different messages when you zone into other areas (e.g. "Welcome to The Badlands, Home of Uldaman!")

You might also want to read WowAce's Coding Tips (http://old.wowace.com/wiki/Coding_Tips) page, which can prove very useful.

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 (http://www.wowace.com) There is a number of resources available:

Version control (http://en.wikipedia.org/wiki/Revision_control) server for Subversion (http://en.wikipedia.org/wiki/Apache_Subversion), Git(http://en.wikipedia.org/wiki/Git_%28software%29), or Mercurial (http://en.wikipedia.org/wiki/Mercurial) [3](http://old.wowace.com/wiki/What_is_the_SVN%3F)[4] (http://kb.wowace.com/projects/packaging­an­addon/)Web­based forum (http://forums.wowace.com/)IRC channel (http://kb.wowace.com/irc­information/)Wiki (http://old.wowace.com/wiki/Main_Page) full of documentation and help

You also should consider publishing your Ace3 addon at wowinterface.com (http://www.wowinterface.com/).

Final Source Files

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

WelcomeHome.toc

## Interface: 40200 ## 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 

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\AceEvent‐3.0\AceEvent‐3.0.xml"/>      <Include file="Libs\AceDB‐3.0\AceDB‐3.0.xml"/>      <Include file="Libs\AceLocale‐3.0\AceLocale‐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> 

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 = { 

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 11/12

            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, true) 

    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("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 

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 (http://old.wowace.com/wiki/WelcomeHome_­_Your_first_Ace3_Addon), which is acontinuation from WelcomeHome ­ Your first Ace2 Addon (http://old.wowace.com/wiki/WelcomeHome_­_Your_first_Ace2_Addon)

Retrieved from "http://wow.gamepedia.com/index.php?title=WelcomeHome_­_Your_first_Ace3_Addon&oldid=2809447"

3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft

http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon 12/12

Categories:  Tutorials HOWTOs

This page was last modified on 8 November 2011, at 22:11.Content is available under CC BY­SA 3.0 unless otherwise noted. World of Warcraft content and materials are trademarks and copyrights of Blizzard or its licensors. All rights reserved. This site is a part of Curse,Inc. and is not affiliated with Blizzard.

Facebook

Twitter

Youtube

Newsletter

Sign In

Register

Careers

Help

About Curse

Advertise

Terms of Service

Privacy Policy

Copyright 2005-2016, Curse Inc.