You are on page 1of 12

3/7/2016

WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft
Help

Sign In Register

WelcomeHome ­ Your first Ace3 Addon
From Wowpedia

Contents
1 Introduction
2 Getting Started
3 Bringing Ace3 to the Party
4 Saying Hello
5 Responding to Events
6 Reloading Your Addon Without Restarting WoW
7 Working with the WoW API
8 Chat Commands and Configuration
9 GUI and Blizzard Interface Options
10 Making the Message More Prominent
11 Saving Configuration Between Sessions
12 Localizing Your Strings with AceLocale
12.1 Adding AceLocale­3.0 to the Project
12.2 Building the Localization Database
12.3 Using the Localized Strings in the Addon
12.4 Mixed­in variables
13 Conclusion
14 Join the Ace Community
15 Final Source Files
15.1 WelcomeHome.toc
15.2 embeds.xml
15.3 Core.lua
15.4 enUS.lua
16 Attribution

Main Menu
WoW API
Widget API
Macro API
Lua functions
Events
Widget handlers
Data types
XML UI
Changes
HOWTOs
Snippets
UI tech.
Category nav.
→ HOWTOs

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 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: 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 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
http://wow.gamepedia.com/WelcomeHome_­_Your_first_Ace3_Addon

1/12

 they wouldn't be loaded.xml"/>      <Include file="Libs\AceDB‐3. Then it's a line each for all the libraries we want to load. 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.0\AceConsole‐3. it is time for us to go ahead and bring those libraries (http://en.lua is executed.0.0.com/WelcomeHome_­_Your_first_Ace3_Addon 2/12 . since all the other libs depend on that.org/TR/xmlschema­1/#Schemas).lua              AceAddon‐3.0.com/addons/callbackhandler/) LibStub (http://www.wowace.xml          AceDB‐3.wowace.0\AceGUI‐3.wowace.toc (http://forums.lua"/>      <Include file="Libs\CallbackHandler‐1.xml" in the same folder as your .0              AceConfigRegistry‐3.0.0              AceConfigCmd‐3. Open a browser and go to http://www. Then CallbackHandler that is used by several of our libraries and AceGUI needs to be loaded before AceConfig.lua      Core.0.0              AceDB‐3.xml"/>      <Include file="Libs\AceGUI‐3.lua              AceConsole‐3.xml"/>  </Ui>  The first line is just some xml­voodoo (http://www.com/addons/ace3/pages/api/ace­addon­3­0/) AceDB­3. Unzip it into a folder called Libs in your addon's directory.0.0 (http://www.xml          AceGUI‐3.0 (http://www.0 (http://www.lua      WelcomeHome.xml          CallbackHandler‐1.wowace.0\AceConfig‐3.wowace.1  ## Title: Welcome Home  ## Author: Your Name Here  ## Notes: Displays a welcome message when you get to your home zone. Then go ahead and delete all of the new folders and files except these: AceAddon­3.0              CallbackHandler‐1.lua              AceGUI‐3.0              AceConfig‐3. Download Ace3.0\CallbackHandler‐1.lua              CallbackHandler‐1.wowace.org/2001/XMLSchema‐instance" xsi:schemaLocation="http://www. just copy and paste.0.0 (http://www. This means you need to get local copies of the libraries you intend to use.0.blizzard. but if you were to launch WoW right now.com/addons/ace3/pages/api/ace­config­3­0/) AceConsole­3. So create a new file with the text below and save it as "embeds.gamepedia.wowace.0 (http://www.0.xml.0              widgets              AceGUI‐3.com/wiki/WelcomeHome_­ _Your_first_Ace3_Addon#Adding_AceLocale­3.0.\FrameXML\UI.xml          AceConfig‐3. For more information on these libraries.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft Since this tutorial is about learning to create addons using Ace3. We include it above Core.xml          AceConsole‐3.0 (http://www.0.0. 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.w3.xml.com/addons/ace3/pages/api/ace­db­3­0/) AceConfig­3.0.org/wiki/Library_%28computing%29) into our addon. the correct load order can be found in the Ace3.wowace. It is vital that we load LibStub first.0.xml"/>      <Include file="Libs\AceEvent‐3.xml"/>      <Include file="Libs\AceConsole‐3. ## Interface: 40200  ## Version: 0.com/addons/libstub/) There are lots of Ace3 libraries for you to use.com/addons/ace3/pages/) You should now have a folder structure something like this: (See the original (http://old. This is the most recent build of the Ace libraries.xml"/>      <Include file="Libs\AceConfig‐3. please see the Ace3 API docs (http://www.  ## SavedVariables: WelcomeHomeDB  ## OptionalDeps: Ace3  http://wow.0.xml          LibStub              LibStub.0              AceAddon‐3.toc  You now have the necessary Ace3 libraries in your addon's Libs folder. Otherwise the order isn't important.wowace.0_to_the_Project) for a better view) WelcomeHome      Libs          AceAddon‐3.com/wow/ui/" xmlns:xsi="http://www.lua              AceConfig‐3.0              AceEvent‐3.. Notice that it's <Script /> to load Lua files and <Include /> to load XML files.0.0. 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          AceEvent‐3.wowace. Now let's update the .wowace.0.php?p=299390#post299390) file.com/showthread.0.0.0              AceConfigDropdown‐3.xsd">      <Script file="Libs\LibStub\LibStub. <Ui xmlns="http://www.w3.com/addons/ace3/pages/api/ace­console­3­0/) AceEvent­3.0\AceAddon‐3.xml"/>      <Include file="Libs\AceAddon‐3.wikipedia.TOC file to include the embeds.com/addons/ace3/files/.lua              AceDB‐3.TOC file.lua              AceEvent‐3.com/addons/ace3/pages/api/ace­gui­3­0/) CallbackHandler­1.blizzard.0.0\AceDB‐3. but for this tutorial we only need some of them.lua to ensure that the libraries are loaded and available before the code in Core.com/addons/ace3/pages/api/ace­event­3­0/) AceGUI­3.0              AceConfigDialog‐3. but to be safe.com/wow/ui/  .0 (http://www.0\AceEvent‐3.wowace.0              AceConsole‐3.

 you should be able to scroll up in the chat window and find your message.org/wiki/Mixin) are a concept common in many object oriented languages that allow you to bring additional functionality into your class. The first is executed only once when the UI loads and the next two are executed when the addon is enabled and disabled. Eventually.html#pdf­print) (with lowercase p). your addon would never even know what to do and when to start doing things. The first line creates an instance of the AceAddon class using the NewAddon (http://www. We're using LibStub (http://www. we will respond to one of the ZONE_CHANGED events which the game fires when the player enters a new zone. "AceEvent‐3.wowace. function WelcomeHome:OnEnable()      self:Print("Hello World!")  end  Go ahead and restart WoW and enter in to the game. 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. Once you are in. Too many addons do this already and there are other ways (http://www.com/addons/ace3/pages/api/ace­addon­3­0/#w­addon­enable) and Disable (http://www. this addon will give a welcome message to the player when they arrive in their home zone.com/addons/ace3/pages/api/ace­console­3­0/#w­ace­console­print­chatframe) method. There also is print (http://www. which is a basic Lua function Mixins (http://en.org/manual/5. Saying Hello This section is going to move a little faster than we have been moving. How will we know they are in their home zone? Simple.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. You will often have to choose which of these two method overrides to use.0")  http://wow.) It is important to note that OnEnable is called at the beginning if the addon is enabled when the UI loads. In fact.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft ## X‐Embeds: Ace3  embeds. Events are raised when things happen in the game and you can fire events when things happen in your code. More on this later. this will get us access to the Print (http://www.wowace. Generally.wowace. Before we go any further.0".gamepedia.wowace.com/addons/ace3/pages/api/ace­addon­3­0/#w­ace­addon­new­addon­object­name­lib) method. WoW is event driven. OnEnable. (You can Enable (http://www. Start by opening Core. without events. You are now the proud author of the WoW version of Hello World!.wowace. I've gone ahead and included the mixin for AceConsole. Before we can subscribe to events.lua  I've included a few other things in the . but we will need all of that eventually. everything your addon does is in response to an event.g.lua file. you should use the OnInitialize for those things that you don't need to undo and redo if the addon is disabled and enabled. we need to get event support into our addon by including another mixin into our addon. as I said. It appears that ZONE_CHANGED will be the one we want. go back over to your code and remove the print message..com/addons/ace3/pages/api/ace­addon­3­0/#w­ace­addon­iterate­addons) to find out what Ace addons have loaded. we will have the addon print "Hello World!" to the chat window by adding one line of code to the OnEnable method.lua. Change your first line as shown here: WelcomeHome = LibStub("AceAddon‐3.0"):NewAddon("WelcomeHome".1/manual..wowace.com/WelcomeHome_­_Your_first_Ace3_Addon 3/12 . I’m sure you are asking yourself “Events? What the heck are those?” It turns out that like many other programming environments. "AceConsole‐3.xml  Core.lua in a text editor and typing in the following code: WelcomeHome = LibStub("AceAddon‐3. "AceConsole‐3. Among other things. We need to change the line where we create our addon to include the AceEvent mixin. 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.wikipedia.com/wiki/Coding_Tips#Methods) overrides: OnInitialize. You can also remove the OnDisable method since we won't be using it. 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. SavedVariables). Since we will also be printing to the chat window and accepting slash commands. Responding to Events So. so let's hook that one by making a few changes to our Core.com/addons/libstub/) for embedding/mixing­in our libraries Following that are three method (http://old.TOC that aren't actually required yet (e. and OnDisable respectively.com/addons/ace3/pages/api/ace­ addon­3­0/#w­addon­disable) Ace addons at will. Just to demonstrate that the addon is loading.wowace.0"):NewAddon("WelcomeHome".

 we will find a function called GetSubZoneText that looks about right. You should see your message go by down in the chat area when you change zone. Change the event handler as follows. "AceConsole‐3.wowace.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.com/addons/ace3/pages/api/ace­config­3­0/): WelcomeHome = LibStub("AceAddon‐3.wowace.0")  local options = {      name = "WelcomeHome".wowace. Chat Commands and Configuration But there are still lots of interesting things we can do. Reloading Your Addon Without Restarting WoW Before we go any further. but switch over to your text editor. Now head back into the game and have your character leave the area he/she is presently in. 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.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft Once we've done that. It returns either an empty string (if you aren't in a subzone) or the name of the subzone you are in.g.. 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. Which message did you see? The old one. Leave the game up and running.0) loaded with any of your addons or if you have the standalone version of Ace3 (http://www. 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.      type = 'group'.      handler = WelcomeHome. This function returns the subzone name (e.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. 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. but when it comes back up you should now be able to switch zones and see the new message. 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.0". One way to get your addon reloaded is to restart the game. Next we need to figure out how to find what subzone we are in.0"):NewAddon("WelcomeHome". From now on you can use this technique to reload your mod when you have made changes. we will see the answer to the second question is a function called GetBindLocation. Why? Because WoW doesn't automatically reload your addon just because you made a change. 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 <font color="#DDA0DD">Core. Reload your UI and test it out.com/WelcomeHome_­_Your_first_Ace3_Addon 4/12 . 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. we will use the RegisterEvent (http://www.0 (http://www. but we don't have to do that because AceEvent does it for us. I want to show you a trick that will come in handy for you as you work on your addons.0 (http://old.com/wiki/AceConsole­2. Note: if you have AceConsole­2. "Tarren Mill") that contains the Inn where your hearthstone is set.wowace..com/addons/ace3/pages/api/ace­event­3­0/#w­ace­event­unregister­event­ event) from our OnDisable override.  http://wow. Ugh.gamepedia.com/addons/ace3/). If we look in the Location Functions section of the API docs. "AceEvent‐3.

 Notice that at this point there is no value for the message string.              name = "Message".message = newValue  end  Note: Using the info (http://www. Now lets add a command that lets the user change the text that is displayed by updating the options table: local options = {       name = "WelcomeHome".  }  function WelcomeHome:OnInitialize()      ‐‐ Called when the addon is loaded      LibStub("AceConfig‐3. "ChatCommand")      self:RegisterChatCommand("wh".com/addons/ace3/pages/api/ace­config­dialog­3­0/) method AddToBlizOptions (http://www. function WelcomeHome:OnInitialize()      ‐‐ Called when the addon is loaded      LibStub("AceConfig‐3.". 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 in Patch 2.com/addons/ace3/pages/api/ace­ config­3­0/#w­ace­config­register­options­table­app­name­options): WelcomeHome.com/addons/ace3/pages/api/ace­ config­dialog­3­0/#w­ace­config­dialog­add­to­bliz­options­app­name­name).              usage = "<Your message>". Then reload your UI and type /wh to see the command.0"):RegisterOptionsTable("WelcomeHome".0 Options Tables (http://www. so we save it in self. newValue)      self.com/WelcomeHome_­_Your_first_Ace3_Addon 5/12 . options.          }.message  end  function WelcomeHome:SetMessage(info. options)  http://wow. We can fix that by adding the following line right after the call to RegisterOptionsTable (http://www.message)      end  end  Play around with it for a little while and see how it works.wowace.wowace. description and available commands. If you reload the UI and type /welcomehome or /wh. {"welcomehome". options)      self:RegisterChatCommand("welcomehome".              desc = "The message to be displayed when you get home.4 they introduced the ability for addons to add their options to the "AddOns" tab.wowace.com/addons/ace3/pages/ace­config­3­0­options­tables/#w­callback­handling) argument is an advanced topic. That is because we didn't provide a default.message = "Welcome Home!"  end  Now to include our addon options to the "Addons" tab. all we need to do is call the AceConfigDialog­3.              get = "GetMessage". This method returns a frame we need to specify later to open the Blizzard Interface Options at the page for our options. so just ignore it until you get more familiar with AceConfig.com/addons/ace3/pages/ace­config­3­0­options­tables/) page.              set = "SetMessage".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.wowace. "ChatCommand")      WelcomeHome. For a complete rundown of the structure of the options table.0"):RegisterOptionsTable("WelcomeHome".      type = "group". for beginners it's enough to know that there is such an argument. Let's quickly write those methods: function WelcomeHome:GetMessage(info)      return self.gamepedia.  Page is safe     }.  }  Total Security 2015 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.0"):RegisterOptionsTable("WelcomeHome". For this we need first to handle our chat commands slightly different.optionsFrame.      handler = WelcomeHome.      args = {          msg = {              type = "input". function WelcomeHome:OnInitialize()      ‐‐ Called when the addon is loaded      LibStub("AceConfig‐3.0 (http://www.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft     args = {      }.wowace. you should now see a help message in your chat box that prints the Addon name. visit the AceConfig­3. "wh"})  end  At this point the options table is empty and we haven't provided any commands.

gamepedia.              desc = "The message text to be displayed".message = "Welcome Home!"  end  Here we use the AceConsole method RegisterChatCommand (http://www.      }. function WelcomeHome:ChatCommand(input)      if not input or input:trim() == "" then          InterfaceOptionsFrame_OpenToCategory(self.showOnScreen = true  Implementations of the new command's get/set methods: function WelcomeHome:IsShowInChat(info)      return self.0"):AddToBlizOptions("WelcomeHome".              desc = "Toggles the display of the message in the chat window. "WelcomeHome")      self:RegisterChatCommand("wh".showInChat  end  function WelcomeHome:ToggleShowInChat(info.              get = "IsShowOnScreen".          }. 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. This way we have both a GUI and chat commands (using the same options table) so our users can use whatever they please.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft     self. value)      self.showInChat = value  end  function WelcomeHome:IsShowOnScreen(info)      return self. Making the Message More Prominent Now that we have the addon working.0"):HandleCommand("wh".              set = "SetMessage". In this function we can do whatever we want. input)      end  end  Try it now and see how it works.              get = "IsShowInChat".showOnScreen then  http://wow.showInChat then              self:Print(self.showOnScreen = value  end  And finally the new event handler method: function WelcomeHome:ZONE_CHANGED()      if GetBindLocation() == GetSubZoneText() then          if self. otherwise we'll let AceConfigCmd handle the input like it would before.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.              get = "GetMessage".optionsFrame)      else          LibStub("AceConfigCmd‐3.  }  Then the new default values: WelcomeHome.showInChat = false  WelcomeHome.          showOnScreen = {              type = "toggle".".".              name = "Message".          }.message)          end          if self.      args = {          msg = {              type = "input".          showInChat = {              type = "toggle". "ChatCommand")      WelcomeHome.com/WelcomeHome_­_Your_first_Ace3_Addon 6/12 . "ChatCommand")      self:RegisterChatCommand("welcomehome".              name = "Show in Chat". let's tweak it a bit. Let's add a way to display the message somewhere that is a bit more prominent. "WelcomeHome". First the new options table: local options = {      name = "WelcomeHome". value)      self.              usage = "<Your message here>".optionsFrame = LibStub("AceConfigDialog‐3.              desc = "Toggles the display of the message on the screen.showOnScreen  end  function WelcomeHome:ToggleShowOnScreen(info. And we want AceConfigDialog to open a GUI for our options if there's no other input.wowace.              name = "Show on Screen".              set = "ToggleShowInChat".              set = "ToggleShowOnScreen"          }.      handler = WelcomeHome.      type = "group".

db. self. you will have the default settings again. This whole exercise was a bit silly. 1.db.0 (http://www.0. and now it's time to use it.      }. "ChatCommand")  end  (In this example we associate these variables with the Ace3 profile "data­type".db = LibStub("AceDB‐3. value)      self.profile. of course.db. defaults.0.0)          end      end  end  As you can see.profile.0. 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.com/addons/ace3/pages/api/ace­db­3­0/#w­ace­db­new­tbl­defaults­default­profile).com/WelcomeHome_­_Your_first_Ace3_Addon 7/12 .db.0.profile.db. faction. "ChatCommand")      self:RegisterChatCommand("welcomehome". WoW provides a way for you to do this called Saved Variables. This will require us to change the get/set methods referenced by our options table and our event handler. realm or global .message.db.showOnScreen then              UIErrorsFrame:AddMessage(self.showOnScreen  end  function WelcomeHome:ToggleShowOnScreen(info. This means that unless you change profile manually all character will share the same "Default" profile.db.profile. After that we need to replace all of the references to the old variables (e.message).0. self.message  end  function WelcomeHome:SetMessage(info.profile.profile. If you don't specify anything for the third argument all characters using the addon will get their own profile.<variablename> (e.db. Except now if you change any of the settings. "WelcomeHome")      self:RegisterChatCommand("wh". When you logout and back in.showInChat then              self:Print(self. 1. See the AceDB­3. because in a real world addon you would start out using AceDB for your configuration data.com/addons/ace3/pages/api/ace­db­3­0/) docs for more information on data­types. true)      LibStub("AceConfig‐3. it was just a simple substitution of the old variable with the new AceDB variable. options)      self.) The string "WelcomeHomeDB" refers to the SavedVariables definition in the TOC file.showOnScreen = value  end  And here is the new event handler: function WelcomeHome:ZONE_CHANGED()      if GetBindLocation() == GetSubZoneText() then          if self. Here are the new command get/set methods: function WelcomeHome:GetMessage(info)      return self.message) with self.message.db.profile.          end          if self.profile. Reload your UI and nothing should change. class.profile.wowace.db.0.0"):New("WelcomeHomeDB". This isn't ideal.gamepedia. 1.profile. value)      self.          showInChat = false. Here we pass the boolean true.message).TOC file.0)          end      end  end  Note: See ScrollingMessageFrame:AddMessage for more info.profile.showInChat  end  function WelcomeHome:ToggleShowInChat(info.optionsFrame = LibStub("AceConfigDialog‐3.showInChat = value  end  function WelcomeHome:IsShowOnScreen(info)      return self.wowace. We already have the library listed in our . 1.message = newValue  end  function WelcomeHome:IsShowInChat(info)      return self.profile. they will be persisted across restarts.0"):RegisterOptionsTable("WelcomeHome".message or WelcomeHome. New (http://www.          showOnScreen = true. http://wow. newValue)      self. 1. 5.g. We should be saving these settings somehow.db. but now you know what it is for and why you should be using it. race.  }  function WelcomeHome:OnInitialize()      ‐‐ Called when the addon is loaded      self. 1. local defaults = {      profile = {          message = "Welcome Home!". 5.g. but there is an Ace way to do it with the AceDB method.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft             UIErrorsFrame:AddMessage(self.0"):AddToBlizOptions("WelcomeHome". but you also can associate them with char.db.

com/addons/ace3/pages/api/ace­locale­3­0/) library. submit the localized strings to you so you can include them in your next release.0           AceConsole‐3.TOC file.lua     Core.xml"/>      <Include file="Libs\AceEvent‐3.lua and save it in the same folder as your . http://wow.lua     WelcomeHome.0.wowace.xml        AceLocale‐3..0_to_the_Project) for a better view) WelcomeHome     Libs        AceAddon‐3.0.0.blizzard. This is important or your localization database will not be initialized before it is used by the code in your addon.xml        AceDB‐3. This library is not a mixin like the other libraries we've used so far.0.0.lua"/>      <Include file="Libs\CallbackHandler‐1. (Or even better.0 as shown here: <Ui xmlns="http://www.lua  Notice that the localization file comes before the Core.blizzard.org/2001/XMLSchema‐instance" xsi:schemaLocation="http://www.0.0\AceGUI‐3.0\AceEvent‐3.xml"/>      <Include file="Libs\AceConsole‐3. we do this using the AceLocale­3.xml"/>      <Include file="Libs\AceAddon‐3.xml     enUS.0           AceConfig‐3.0.toc  Then.0.xml"/>      <Include file="Libs\AceLocale‐3.lua           AceAddon‐3.lua           AceConfig‐3. Since we have updated our .lua     embeds.xml"/>  </Ui>  And our .0           AceDB‐3.0. Once you've done that.xml"/>      <Include file="Libs\AceGUI‐3.xml"/>      <Include file="Libs\AceConfig‐3.0.0           AceConfigDropdown‐3.0\AceConsole‐3.w3.TOC file.com/wow/ui/  .lua file.gamepedia.0.com/wiki/WelcomeHome_­ _Your_first_Ace3_Addon#Adding_AceLocale­3.0. This means that there should be a nice easy way for them to localize the strings in your addon into their language. Adding AceLocale­3.0\AceLocale‐3.lua           AceLocale‐3. We also should create our first localization database file.TOC file: ## Interface: 40200  ## Version: 0.xml"/>      <Include file="Libs\AceDB‐3.lua           AceConsole‐3.xsd">      <Script file="Libs\LibStub\LibStub.0           AceAddon‐3.0.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft Localizing Your Strings with AceLocale One thing a lot of new addon developers (especially those in the U.lua           AceEvent‐3.xml        AceConsole‐3.0. so the way we use it is a bit different.lua           AceDB‐3.wowace.  ## SavedVariables: WelcomeHomeDB  ## OptionalDeps: Ace3  ## X‐Embeds: Ace3  embeds.0.0           AceConfigRegistry‐3.0           widgets           AceGUI‐3.0\CallbackHandler‐1. The /reload trick won't work this time.lua  Core.0           AceConfigCmd‐3.xml        AceConfig‐3.0.0.xml file to reference to the newly added AceLocale­3. go ahead and login and make sure everything is still working. At this point our folder structure should look like this: (See the original (http://old. you will need to restart WoW to get these changes loaded into the game.xml        CallbackHandler‐1.com/wow/ui/" xmlns:xsi="http://www.0 to the Project Let's start by grabbing the AceLocale­3.) forget about is how many people will be wanting to use their addon in a non­english version of the game client.0           AceLocale‐3.lua           CallbackHandler‐1.0.1  ## Title: Welcome Home  ## Author: Your Name Here  ## Notes: Displays a welcome message when you get to your home zone.0.com/WelcomeHome_­_Your_first_Ace3_Addon 8/12 .0.xml  enUS.0           AceEvent‐3.0 folder from the package that we downloaded earlier and putting it into our Libs folder.0.0.xml        AceEvent‐3.S.0.0.0\AceAddon‐3.) With Ace3.lua           AceGUI‐3.xml        AceGUI‐3.0           CallbackHandler‐1.0\AceDB‐3.\FrameXML\UI.0\AceConfig‐3.xml        LibStub           LibStub. we need to update our embeds.0 (http://www. Create an empty file called enUS.0           AceConfigDialog‐3.

com/WelcomeHome_­_Your_first_Ace3_Addon 9/12 .              get = "GetMessage"."] = true  L["<Your message>"] = true ‐‐ usage  L["Show in Chat"] = true  L["Toggles the display of the message in the chat window. 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. This means that in our code. ' herzlich Willkommen'. [1] (http://kb. X ."] = true  L["Show on Screen"] = true  L["Toggles the display of the message on the screen. For example the first part of our options table now becomes this: local options = {      name = "WelcomeHome". "enUS" is the language code for US English and true as the third argument tells AceLocale that this is the default locale.lua:  self:Print(L['We heartly welcome player X..wowace..0"):GetLocale("WelcomeHome")  Now we can use this anywhere we need a translated string by putting L[ ] around it.0"):NewLocale("WelcomeHome". (In your future addon work. ‐‐ enUS/enGB:  L['We heartly welcome player X. You can see the final source files at the end of the article to see if you got them all in your addon. So the word or text element order does not matter in your script and translations will sound more natural.   ."].wowace. add the following line to the top of Core. Now. we need to pass through the source code looking for strings that should be localizable.      type = "group".lua.              desc = L["The message to be displayed when you get home.'] = function(X)     return 'We heartly welcome player ' . or another string depending on the language."] = true  This file has two parts.      args = {          msg = {              type = "input". The first part creates a new AceLocale instance with the name "WelcomeHome". X..  end  ‐‐ deDE:  L['We heartly welcome player X.  Conclusion http://wow.'](playername))..lua. Using AceLocale is a simple way to get good localization support in your addon.              usage = L["<Your message>"].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).              name = L["Message"]. Having the values be true makes them the same as their keys. 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 it doesn't have a translation for the language the user is playing in.          }.  This process is pretty straightforward. this calls the GetLocale (http://www..              set = "SetMessage".  end  ‐‐ script.gamepedia.etc. when we ask for the localized version of "Welcome Home!".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.lua: local L = LibStub("AceLocale‐3.) After taking a pass through Core.'] = function(X)     return 'Wir hei\195\159en Spieler ' . so I won't bother showing all of it here. local L = LibStub("AceLocale‐3.      handler = WelcomeHome. The second part is the actual translations. 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. "enUS".3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft Building the Localization Database Now that we have a place to put the localized strings for the US English (enUS) version of our Addon. I added the following lines to enUS. we will get "Welcome Home!"...

0"):NewAddon("WelcomeHome".0")  local L = LibStub("AceLocale‐3. embeds.wowace.              set = "SetMessage".wowace.0.com/projects/packaging­an­addon/) Web­based forum (http://forums.com/wiki/Coding_Tips) page.lua  Core.      args = {          msg = {              type = "input".xml.com (http://www. "AceEvent‐3.xml <Ui xmlns="http://www."].          }.wowace.              set = "ToggleShowInChat".\FrameXML\UI.org/wiki/Revision_control) server for Subversion (http://en.              name = L["Show in Chat"].0\AceEvent‐3. Home of Uldaman!") You might also want to read WowAce's Coding Tips (http://old.0.xml"/>       <Include file="Libs\AceConsole‐3.com/tekkub/libdatabroker­1­1/wiki/) for in e.              name = L["Message"].xml"/>       <Include file="Libs\AceAddon‐3.wikipedia.com/wiki/What_is_the_SVN%3F)[4] (http://kb.0\AceGUI‐3.0\AceConsole‐3. Data Display AddOns [2] (http://forums.wowace. Core.com/wow/ui/" xmlns:xsi="http://www.com/irc­information/) Wiki (http://old. Hopefully that helps you get started with Ace3 development and leads you down the road to successful addon authoring.xml"/>  </Ui>  Core.0\CallbackHandler‐1.wowace. or Mercurial (http://en.lua in case you want to cheat and go right to the end.com)  There is a number of resources available: Version control (http://en. There are a number of interesting things you can do to this addon if you want to keep going. "AceConsole‐3.0.g. which can prove very useful.          showOnScreen = {  http://wow. Final Source Files Here is the final contents of WelcomeHome..0".wikipedia.org/wiki/Git_%28software%29).lua and enUS.gamepedia.      type = "group".3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft You have started from nothing and created a localizable addon that uses chat commands.wikipedia.0\AceConfig‐3.org/2001/XMLSchema‐instance" xsi:schemaLocation="http://www."]. in addition to slash commands Add support for LibDataBroker (https://github.  ## SavedVariables: WelcomeHomeDB  ## OptionalDeps: Ace3  ## X‐Embeds: Ace3  embeds.xml"/>       <Include file="Libs\AceEvent‐3.com/) IRC channel (http://kb.             get = "IsShowInChat".xml"/>       <Include file="Libs\AceConfig‐3.wowace.      handler = WelcomeHome.com/wiki/Main_Page) full of documentation and help You also should consider publishing your Ace3 addon at wowinterface. you should consider getting involved in the Ace community at wowace. "Welcome to The Badlands. WelcomeHome.1  ## Title: Welcome Home  ## Author: Your Name Here  ## Notes: Displays a welcome message when you get to your home zone.          }.              usage = L["<Your message>"].wowinterface.0\AceAddon‐3.0"):GetLocale("WelcomeHome")  local options = {      name = "WelcomeHome".wowace.lua"/>       <Include file="Libs\CallbackHandler‐1.toc ## Interface: 40200  ## Version: 0.0.              desc = L["The message to be displayed when you get home.0.          showInChat = {              type = "toggle".lua WelcomeHome = LibStub("AceAddon‐3.xsd">       <Script file="Libs\LibStub\LibStub.wikipedia. Git (http://en.toc.com/).php?t=14903) Show different messages when you zone into other areas (e. responds to events and provides feedback to the user in a couple of different ways.org/wiki/Apache_Subversion).xml"/>       <Include file="Libs\AceDB‐3.0.org/wiki/Mercurial) [3] (http://old. Best of luck! Join the Ace Community As you get more interested in Ace3 development.g. Some examples: Provide a configuration menu (http://www.xml"/>       <Include file="Libs\AceGUI‐3.lua  embeds.0.com/showthread.0\AceDB‐3.wowace.com (http://www.0\AceLocale‐3.w3.com/WelcomeHome_­_Your_first_Ace3_Addon 10/12 .com/addons/ace3/pages/ace­config­3­0­options­tables/).blizzard.0.blizzard.wowace.              get = "GetMessage".xml"/>       <Include file="Libs\AceLocale‐3.com/wow/ui/  .              desc = L["Toggles the display of the message in the chat window.xml  enUS.

com/index.db.0.message  end  function WelcomeHome:SetMessage(info.          showInChat = false.db. 1.showInChat  end  function WelcomeHome:ToggleShowInChat(info.optionsFrame = LibStub("AceConfigDialog‐3.profile.0"):HandleCommand("wh". true)      LibStub("AceConfig‐3.profile.showOnScreen then              UIErrorsFrame:AddMessage(self. "ChatCommand")      self:RegisterChatCommand("welcomehome".              get = "IsShowOnScreen".0"):AddToBlizOptions("WelcomeHome".profile.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft             type = "toggle". "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. 5."] = true  Attribution This is an import from WelcomeHome ­ Your first Ace3 Addon (http://old.gamepedia.db.profile. value)      self. "WelcomeHome")      self:RegisterChatCommand("wh".0"):RegisterOptionsTable("WelcomeHome".0)          end      end  end  function WelcomeHome:ChatCommand(input)      if not input or input:trim() == "" then          InterfaceOptionsFrame_OpenToCategory(self.0"):NewLocale("WelcomeHome". "enUS". 1.com/wiki/WelcomeHome_­_Your_first_Ace3_Addon). which is a continuation from WelcomeHome ­ Your first Ace2 Addon (http://old.optionsFrame)      else          LibStub("AceConfigCmd‐3.0.gamepedia.      }.php?title=WelcomeHome_­_Your_first_Ace3_Addon&oldid=2809447" http://wow.db.db.message.db.message = newValue  end  function WelcomeHome:IsShowInChat(info)      return self."] = true  L["Show on Screen"] = true  L["Toggles the display of the message on the screen.0"):New("WelcomeHomeDB". 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.wowace.com/wiki/WelcomeHome_­_Your_first_Ace2_Addon) Retrieved from "http://wow.      }.              set = "ToggleShowOnScreen". "WelcomeHome".db.profile.showOnScreen  end  function WelcomeHome:ToggleShowOnScreen(info.  }  function WelcomeHome:OnInitialize()      ‐‐ Called when the addon is loaded      self.              name = L["Show on Screen"].profile.  }  local defaults = {      profile =  {          message = L["Welcome Home!"].profile.          showOnScreen = true.          }.showInChat then              self:Print(self. input)      end  end  function WelcomeHome:GetMessage(info)      return self.lua local L = LibStub("AceLocale‐3.profile.db. defaults.db.wowace.db. options)      self.com/WelcomeHome_­_Your_first_Ace3_Addon 11/12 .              desc = L["Toggles the display of the message on the screen.showOnScreen = value  end  enUS. newValue)      self."] = true  L["<Your message>"] = true ‐‐ usage  L["Show in Chat"] = true  L["Toggles the display of the message in the chat window.message)          end          if self. value)      self.db = LibStub("AceDB‐3.profile."].0.showInChat = value  end  function WelcomeHome:IsShowOnScreen(info)      return self.profile. 1.

 at 22:11. Inc. Content is available under CC BY­SA 3.  World of Warcraft content and materials are trademarks and copyrights of Blizzard or its licensors.0 unless otherwise noted. All rights reserved. http://wow. Curse Inc.gamepedia. This site is a part of Curse. and is not affiliated with Blizzard.com/WelcomeHome_­_Your_first_Ace3_Addon 12/12 . Facebook  Sign In  About Curse  Twitter  Register  Advertise  Youtube  Careers  Terms of Service  Newsletter  Help  Privacy Policy  Copyright 2005-2016.3/7/2016 WelcomeHome ­ Your first Ace3 Addon ­ Wowpedia ­ Your wiki guide to the World of Warcraft Categories:  Tutorials HOWTOs This page was last modified on 8 November 2011.