3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
Help

Sign In Register

WelcomeHomeYourfirstAce3Addon
FromWowpedia

Contents
1Introduction
2GettingStarted
3BringingAce3totheParty
4SayingHello
5RespondingtoEvents
6ReloadingYourAddonWithoutRestartingWoW
7WorkingwiththeWoWAPI
8ChatCommandsandConfiguration
9GUIandBlizzardInterfaceOptions
10MakingtheMessageMoreProminent
11SavingConfigurationBetweenSessions
12LocalizingYourStringswithAceLocale
12.1AddingAceLocale3.0totheProject
12.2BuildingtheLocalizationDatabase
12.3UsingtheLocalizedStringsintheAddon
12.4Mixedinvariables
13Conclusion
14JointheAceCommunity
15FinalSourceFiles
15.1WelcomeHome.toc
15.2embeds.xml
15.3Core.lua
15.4enUS.lua
16Attribution

MainMenu
WoWAPI
WidgetAPI
MacroAPI
Luafunctions
Events
Widgethandlers
Datatypes
XMLUI
Changes
HOWTOs
Snippets
UItech.
Categorynav.
HOWTOs

Introduction
Ace3(http://old.wowace.com/wiki/Ace3)isanAddOndevelopmentframework,like(thenowabandoned)Rock(http://old.wowace.com/wiki/Rock),
Dongle,andSea.
Beforestartingthistutorial,it'srecommendedtoreadMakeitAce'd(http://old.wowace.com/wiki/Make_it_Ace%27d),andAce3Philosophy
(http://old.wowace.com/wiki/Ace3#Ace3_Philosophy)
Alternatively,thereisthemoreadvancedandofficialAce3GettingStarted(http://www.wowace.com/addons/ace3/pages/gettingstarted/)tutorial

GettingStarted
SincethisisatutorialaboutusingtheAce3libraries,Iwillstartbyshowingyouwhatweneedtodotogetabarebonesaddonloadedintothegame.
EveryaddonisstoredinafolderunderneaththeWoWmainfoldercalled<WoW>\Interface\AddOns.Eachaddongoesinitsownfoldernamedafterthe
addon.SotogetstartedwewillcreateanewfoldercalledWelcomeHome.
WhenWoWfindsafolderintheaddonsdirectory,itlooksinsidethatfolderforaTableofContents(TOC)filethathasthesamenameasthefolder.This
.TOCfilecontainsamanifestofalltheotherfilesthatmakeuptheaddonandisusedbyWoWtoloadyouraddon.
Letsgoaheadandcreateabarebones.TOCfilecalledWelcomeHome.toc:
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
Core.lua

Thesearethebasicmetadataassociatedwithyouraddon.Therearemanyotherattributesyoucanincludeinyour.TOCfile,foramorecomprehensivelist
seetheTOCFormat.
ThencreateanemptytextfilecalledCore.luainthesamedirectoryandstartupWoW.Afterloggingin,youshouldbeabletoclicktheAddOnsbuttonin
thelowerleftandseethatyourAddOnisbeingrecognizedbythegame.Goaheadandmakesurethatitisenabledbeforeexitingoutofthatscreenand
thenoutofthegame.
Step1complete!Weareinthegame.Butwearentdoinganythingyet.Thatisnext.

BringingAce3totheParty
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

1/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

SincethistutorialisaboutlearningtocreateaddonsusingAce3,itistimeforustogoaheadandbringthoselibraries
(http://en.wikipedia.org/wiki/Library_%28computing%29)intoouraddon.Ace3usesaconceptcalledEmbeddedLibrariesthatallowsmoddevelopersto
havethelibrariesintheircodebasewithoutactuallyduplicatingthecodewhenitisloadedalongsideothermodsthatusethesamelibraries.
Thismeansyouneedtogetlocalcopiesofthelibrariesyouintendtouse.AtthispointtheeasiestwaytodothisistodownloadthemfromtheAceSVN
filesmirrorandputthemonyoursystem.
Openabrowserandgotohttp://www.wowace.com/addons/ace3/files/.DownloadAce3.ThisisthemostrecentbuildoftheAcelibraries.Unzipitintoa
foldercalledLibsinyouraddon'sdirectory.Thengoaheadanddeleteallofthenewfoldersandfilesexceptthese:
AceAddon3.0(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/)
AceDB3.0(http://www.wowace.com/addons/ace3/pages/api/acedb30/)
AceConfig3.0(http://www.wowace.com/addons/ace3/pages/api/aceconfig30/)
AceConsole3.0(http://www.wowace.com/addons/ace3/pages/api/aceconsole30/)
AceEvent3.0(http://www.wowace.com/addons/ace3/pages/api/aceevent30/)
AceGUI3.0(http://www.wowace.com/addons/ace3/pages/api/acegui30/)
CallbackHandler1.0(http://www.wowace.com/addons/callbackhandler/)
LibStub(http://www.wowace.com/addons/libstub/)
TherearelotsofAce3librariesforyoutouse,butforthistutorialweonlyneedsomeofthem.Formoreinformationontheselibraries,pleaseseetheAce3
APIdocs(http://www.wowace.com/addons/ace3/pages/)
Youshouldnowhaveafolderstructuresomethinglikethis:(Seetheoriginal(http://old.wowace.com/wiki/WelcomeHome_
_Your_first_Ace3_Addon#Adding_AceLocale3.0_to_the_Project)forabetterview)
WelcomeHome
Libs
AceAddon3.0
AceAddon3.0.lua
AceAddon3.0.xml
AceConfig3.0
AceConfigCmd3.0
AceConfigDialog3.0
AceConfigDropdown3.0
AceConfigRegistry3.0
AceConfig3.0.lua
AceConfig3.0.xml
AceConsole3.0
AceConsole3.0.lua
AceConsole3.0.xml
AceDB3.0
AceDB3.0.lua
AceDB3.0.xml
AceEvent3.0
AceEvent3.0.lua
AceEvent3.0.xml
AceGUI3.0
widgets
AceGUI3.0.lua
AceGUI3.0.xml
CallbackHandler1.0
CallbackHandler1.0.lua
CallbackHandler1.0.xml
LibStub
LibStub.lua
Core.lua
WelcomeHome.toc

YounowhavethenecessaryAce3librariesinyouraddon'sLibsfolder,butifyouweretolaunchWoWrightnow,theywouldn'tbeloaded.Weneedtotell
WoWtoloadthefileswhenitloadsyouraddonandforthatwe'regoingtouseafilecalledembeds.xml.Socreateanewfilewiththetextbelowandsaveit
as"embeds.xml"inthesamefolderasyour.TOCfile.
<Uixmlns="http://www.blizzard.com/wow/ui/"xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Scriptfile="Libs\LibStub\LibStub.lua"/>
<Includefile="Libs\CallbackHandler1.0\CallbackHandler1.0.xml"/>
<Includefile="Libs\AceAddon3.0\AceAddon3.0.xml"/>
<Includefile="Libs\AceEvent3.0\AceEvent3.0.xml"/>
<Includefile="Libs\AceDB3.0\AceDB3.0.xml"/>
<Includefile="Libs\AceConsole3.0\AceConsole3.0.xml"/>
<Includefile="Libs\AceGUI3.0\AceGUI3.0.xml"/>
<Includefile="Libs\AceConfig3.0\AceConfig3.0.xml"/>
</Ui>

Thefirstlineisjustsomexmlvoodoo(http://www.w3.org/TR/xmlschema1/#Schemas),justcopyandpaste.Thenit'salineeachforallthelibrarieswe
wanttoload.Noticethatit's<Script/>toloadLuafilesand<Include/>toloadXMLfiles.
ItisvitalthatweloadLibStubfirst,sincealltheotherlibsdependonthat.ThenCallbackHandlerthatisusedbyseveralofourlibrariesandAceGUIneeds
tobeloadedbeforeAceConfig.Otherwisetheorderisn'timportant,buttobesafe,thecorrectloadordercanbefoundintheAce3.toc
(http://forums.wowace.com/showthread.php?p=299390#post299390)file.
Nowlet'supdatethe.TOCfiletoincludetheembeds.xml.WeincludeitaboveCore.luatoensurethatthelibrariesareloadedandavailablebeforethecode
inCore.luaisexecuted.
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
##SavedVariables:WelcomeHomeDB
##OptionalDeps:Ace3

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

2/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

##XEmbeds:Ace3
embeds.xml
Core.lua

I'veincludedafewotherthingsinthe.TOCthataren'tactuallyrequiredyet(e.g.SavedVariables),butwewillneedallofthateventually.The
OptionalDepspartisthereincaseauserofyouraddoncomesalonglaterandchoosestouseastandaloneAce3insteadofusingtheembeddedlibrariesin
yourLibsfolderandtheXEmbedsistheretotellupdaterswhatlibsitneedstodownloadseparatelyiftheuserdon'twanttousetheembeddedlibs.

SayingHello
Thissectionisgoingtomovealittlefasterthanwehavebeenmoving.StartbyopeningCore.luainatexteditorandtypinginthefollowingcode:
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0")
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
end
functionWelcomeHome:OnEnable()
Calledwhentheaddonisenabled
end
functionWelcomeHome:OnDisable()
Calledwhentheaddonisdisabled
end

ThisisthebasicstartingstructureofanAce3addon.ThefirstlinecreatesaninstanceoftheAceAddonclassusingtheNewAddon
(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/#waceaddonnewaddonobjectnamelib)method.Sincewewillalsobeprintingtothe
chatwindowandacceptingslashcommands,I'vegoneaheadandincludedthemixinforAceConsole.Amongotherthings,thiswillgetusaccesstothe
Print(http://www.wowace.com/addons/ace3/pages/api/aceconsole30/#waceconsoleprintchatframe)method.Therealsoisprint
(http://www.lua.org/manual/5.1/manual.html#pdfprint)(withlowercasep),whichisabasicLuafunction
Mixins(http://en.wikipedia.org/wiki/Mixin)areaconceptcommoninmanyobjectorientedlanguagesthatallowyoutobringadditionalfunctionalityinto
yourclass.We'reusingLibStub(http://www.wowace.com/addons/libstub/)forembedding/mixinginourlibraries
Followingthatarethreemethod(http://old.wowace.com/wiki/Coding_Tips#Methods)overrides:OnInitialize,OnEnable,andOnDisablerespectively.
ThefirstisexecutedonlyoncewhentheUIloadsandthenexttwoareexecutedwhentheaddonisenabledanddisabled.(YoucanEnable
(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/#waddonenable)andDisable(http://www.wowace.com/addons/ace3/pages/api/ace
addon30/#waddondisable)Aceaddonsatwill.)
ItisimportanttonotethatOnEnableiscalledatthebeginningiftheaddonisenabledwhentheUIloads.Youwilloftenhavetochoosewhichofthesetwo
methodoverridestouse.Generally,youshouldusetheOnInitializeforthosethingsthatyoudon'tneedtoundoandredoiftheaddonisdisabledand
enabled.Anotherimportantpartofthisdecisionhastodowithwhatotherthingsyouwillneedandwhenyoucanbesuretheyareready.Moreonthis
later...
Justtodemonstratethattheaddonisloading,wewillhavetheaddonprint"HelloWorld!"tothechatwindowbyaddingonelineofcodetotheOnEnable
method.
functionWelcomeHome:OnEnable()
self:Print("HelloWorld!")
end

GoaheadandrestartWoWandenterintothegame.Onceyouarein,youshouldbeabletoscrollupinthechatwindowandfindyourmessage.Youare
nowtheproudauthoroftheWoWversionofHelloWorld!.
Beforewegoanyfurther,gobackovertoyourcodeandremovetheprintmessage.ItisgenerallyconsideredbadAceformforyouraddontotossabunch
oftextintothechatwindowjustbecauseithasloaded.Toomanyaddonsdothisalreadyandthereareotherways
(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/#waceaddoniterateaddons)tofindoutwhatAceaddonshaveloaded.Youcanalso
removetheOnDisablemethodsincewewon'tbeusingit.

RespondingtoEvents
So,asIsaid,thisaddonwillgiveawelcomemessagetotheplayerwhentheyarriveintheirhomezone.Howwillweknowtheyareintheirhomezone?
Simple,wewillrespondtooneoftheZONE_CHANGEDeventswhichthegamefireswhentheplayerentersanewzone.
ImsureyouareaskingyourselfEvents?Whattheheckarethose?Itturnsoutthatlikemanyotherprogrammingenvironments,WoWiseventdriven.
Eventsareraisedwhenthingshappeninthegameandyoucanfireeventswhenthingshappeninyourcode.Infact,withoutevents,youraddonwould
neverevenknowwhattodoandwhentostartdoingthings.Eventually,everythingyouraddondoesisinresponsetoanevent.
ItappearsthatZONE_CHANGEDwillbetheonewewant,solet'shookthatonebymakingafewchangestoourCore.luafile.
Beforewecansubscribetoevents,weneedtogeteventsupportintoouraddonbyincludinganothermixinintoouraddon.Weneedtochangetheline
wherewecreateouraddontoincludetheAceEventmixin.Changeyourfirstlineasshownhere:
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0","AceEvent3.0")

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

3/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

Oncewe'vedonethat,wewillusetheRegisterEvent(http://www.wowace.com/addons/ace3/pages/api/aceevent30/#waceeventregistereventevent
callbackarg)methodthatisnowavailabletoustosubscribetotheZONE_CHANGEDevent.WewillreplacetheOnEnableoverridewiththefollowing
code:
functionWelcomeHome:OnEnable()
Calledwhentheaddonisenabled
self:RegisterEvent("ZONE_CHANGED")
end
Wealsoneedtoaddintheeventhandlerforthateventbyaddingthefollowingcodetoour<fontcolor="#DDA0DD">Core.lua</font>file:
functionWelcomeHome:ZONE_CHANGED()
self:Print("Youhavechangedzones!")
end

YoumightbewonderingifweshouldcallUnregisterEvent(http://www.wowace.com/addons/ace3/pages/api/aceevent30/#waceeventunregisterevent
event)fromourOnDisableoverride,butwedon'thavetodothatbecauseAceEventdoesitforus.
Nowheadbackintothegameandhaveyourcharacterleavetheareahe/sheispresentlyin.Youshouldseeyourmessagegobydowninthechatareawhen
youchangezone.

ReloadingYourAddonWithoutRestartingWoW
Beforewegoanyfurther,Iwanttoshowyouatrickthatwillcomeinhandyforyouasyouworkonyouraddons.
Leavethegameupandrunning,butswitchovertoyourtexteditor.Changetheeventhandlerasfollows...
functionWelcomeHome:ZONE_CHANGED()
self:Print("Thisisadifferentmessage!")
end

Makesureyousaveyourchangesandthengobackovertothegameandswitchzones.Whichmessagedidyousee?Theoldone.
Why?BecauseWoWdoesn'tautomaticallyreloadyouraddonjustbecauseyoumadeachange.Onewaytogetyouraddonreloadedistorestartthegame.
Ugh.Amuchbetterwaytogetitreloadedisbyentering:
/reload

YourscreenwillfreezeforaminutewhiletheUIreloadsitselfandallyourotheraddonsreload,butwhenitcomesbackupyoushouldnowbeableto
switchzonesandseethenewmessage.
Fromnowonyoucanusethistechniquetoreloadyourmodwhenyouhavemadechanges.
Note:ifyouhaveAceConsole2.0(http://old.wowace.com/wiki/AceConsole2.0)loadedwithanyofyouraddonsorifyouhavethestandaloneversionof
Ace3(http://www.wowace.com/addons/ace3/),youcanusethefollowingcommandtoreloadyourUI:
/rl

WorkingwiththeWoWAPI
Wenowhaveamethodthatweknowwillgetcalledwhentheplayerchangeszones.Butwhatzoneishein?Wheredoeshekeephishearthstoneset?
IfweheadbackovertotheWorldofWarcraftAPIpageandlookintheCharacterFunctionssection,wewillseetheanswertothesecondquestionisa
functioncalledGetBindLocation.Thisfunctionreturnsthesubzonename(e.g."TarrenMill")thatcontainstheInnwhereyourhearthstoneisset.
Nextweneedtofigureouthowtofindwhatsubzonewearein.IfwelookintheLocationFunctionssectionoftheAPIdocs,wewillfindafunctioncalled
GetSubZoneTextthatlooksaboutright.Itreturnseitheranemptystring(ifyouaren'tinasubzone)orthenameofthesubzoneyouarein.
Weshouldbeabletosimplycomparethesetwovaluesinoureventhandlertodecidewhetherwearehomeornot:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
self:Print("WelcomeHome!")
end
end

That'sit!Weshouldnowhaveafunctionaladdondoingwhatwewant.ReloadyourUIandtestitout.

ChatCommandsandConfiguration
Buttherearestilllotsofinterestingthingswecando.Let'sstartbyaddingsupportfortheoutoftheboxslashcommandsbycreatinganoptionstableat
thetopofthefileandregisteringitwithAceConfig3.0(http://www.wowace.com/addons/ace3/pages/api/aceconfig30/):
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0","AceEvent3.0")
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type='group',

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

4/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

args={
},
}
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options,{"welcomehome","wh"})
end

Atthispointtheoptionstableisemptyandwehaven'tprovidedanycommands.Foracompleterundownofthestructureoftheoptionstable,visitthe
AceConfig3.0OptionsTables(http://www.wowace.com/addons/ace3/pages/aceconfig30optionstables/)page.
IfyoureloadtheUIandtype/welcomehomeor/wh,youshouldnowseeahelpmessageinyourchatboxthatprintstheAddonname,descriptionand
availablecommands.
Nowletsaddacommandthatletstheuserchangethetextthatisdisplayedbyupdatingtheoptionstable:
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name="Message",
desc="Themessagetobedisplayedwhenyougethome.",
usage="<Yourmessage>",
get="GetMessage",
set="SetMessage",
},
Pageissafe
},
}

TotalSecurity2015

Thiswilldefineanewslashcommandcalledmsgthattakesatextargumentandusesthefunctionsnamedtogetandsettheunderlyingvariables.Let's
quicklywritethosemethods:
functionWelcomeHome:GetMessage(info)
returnself.message
end
functionWelcomeHome:SetMessage(info,newValue)
self.message=newValue
end

Note:Usingtheinfo(http://www.wowace.com/addons/ace3/pages/aceconfig30optionstables/#wcallbackhandling)argumentisanadvancedtopic,for
beginnersit'senoughtoknowthatthereissuchanargument,sojustignoreituntilyougetmorefamiliarwithAceConfig.
ThenreloadyourUIandtype/whtoseethecommand.Noticethatatthispointthereisnovalueforthemessagestring.Thatisbecausewedidn'tprovidea
default.WecanfixthatbyaddingthefollowinglinerightafterthecalltoRegisterOptionsTable(http://www.wowace.com/addons/ace3/pages/api/ace
config30/#waceconfigregisteroptionstableappnameoptions):
WelcomeHome.message="WelcomeHome!"

Thefinalstepistochangetheprintlineinoureventhandlertousethenewmessage:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
self:Print(self.message)
end
end

Playaroundwithitforalittlewhileandseehowitworks.

GUIandBlizzardInterfaceOptions
Butwhystopatchatcommands?AllcooladdonshaveaGraphicalUserInterfacethesedayssoWelcomeHomeshouldn'tbeanydifferent!WhenBlizzard
remadetheirInterfaceOptionsinPatch2.4theyintroducedtheabilityforaddonstoaddtheiroptionstothe"AddOns"tab.Forthisweneedfirsttohandle
ourchatcommandsslightlydifferent.
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)
self:RegisterChatCommand("welcomehome","ChatCommand")
self:RegisterChatCommand("wh","ChatCommand")
WelcomeHome.message="WelcomeHome!"
end

Nowtoincludeouraddonoptionstothe"Addons"tab,allweneedtodoiscalltheAceConfigDialog3.0
(http://www.wowace.com/addons/ace3/pages/api/aceconfigdialog30/)methodAddToBlizOptions(http://www.wowace.com/addons/ace3/pages/api/ace
configdialog30/#waceconfigdialogaddtoblizoptionsappnamename).ThismethodreturnsaframeweneedtospecifylatertoopentheBlizzard
InterfaceOptionsatthepageforouroptions,sowesaveitinself.optionsFrame.
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

5/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

self.optionsFrame=LibStub("AceConfigDialog3.0"):AddToBlizOptions("WelcomeHome","WelcomeHome")
self:RegisterChatCommand("wh","ChatCommand")
self:RegisterChatCommand("welcomehome","ChatCommand")
WelcomeHome.message="WelcomeHome!"
end

HereweusetheAceConsolemethodRegisterChatCommand(http://www.wowace.com/addons/ace3/pages/api/aceconsole30/#waceconsoleregister
chatcommandcommandfuncpersist)tomake/welcomehomeand/whcallourChatCommandmethodinstead.Inthisfunctionwecandowhateverwe
want.AndwewantAceConfigDialogtoopenaGUIforouroptionsifthere'snootherinput,otherwisewe'llletAceConfigCmdhandletheinputlikeit
wouldbefore.ThiswaywehavebothaGUIandchatcommands(usingthesameoptionstable)soouruserscanusewhatevertheyplease.
functionWelcomeHome:ChatCommand(input)
ifnotinputorinput:trim()==""then
InterfaceOptionsFrame_OpenToCategory(self.optionsFrame)
else
LibStub("AceConfigCmd3.0"):HandleCommand("wh","WelcomeHome",input)
end
end

Tryitnowandseehowitworks.

MakingtheMessageMoreProminent
Nowthatwehavetheaddonworking,let'stweakitabit.Let'saddawaytodisplaythemessagesomewherethatisabitmoreprominent.Todothiswewill
showthemessageinaframecalledUIErrorsFrameandaddsomenewoptionstolettheuserdecidewhattheywant.
Note:I'mgoingtoassumethatyouarestartingtofigurethisoutandcanfigureoutwherethiscodegoes.
Firstthenewoptionstable:
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name="Message",
desc="Themessagetexttobedisplayed",
usage="<Yourmessagehere>",
get="GetMessage",
set="SetMessage",
},
showInChat={
type="toggle",
name="ShowinChat",
desc="Togglesthedisplayofthemessageinthechatwindow.",
get="IsShowInChat",
set="ToggleShowInChat",
},
showOnScreen={
type="toggle",
name="ShowonScreen",
desc="Togglesthedisplayofthemessageonthescreen.",
get="IsShowOnScreen",
set="ToggleShowOnScreen"
},
},
}

Thenthenewdefaultvalues:
WelcomeHome.showInChat=false
WelcomeHome.showOnScreen=true

Implementationsofthenewcommand'sget/setmethods:
functionWelcomeHome:IsShowInChat(info)
returnself.showInChat
end
functionWelcomeHome:ToggleShowInChat(info,value)
self.showInChat=value
end
functionWelcomeHome:IsShowOnScreen(info)
returnself.showOnScreen
end
functionWelcomeHome:ToggleShowOnScreen(info,value)
self.showOnScreen=value
end

Andfinallytheneweventhandlermethod:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
ifself.showInChatthen
self:Print(self.message)
end
ifself.showOnScreenthen

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

6/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

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

Note:SeeScrollingMessageFrame:AddMessageformoreinfo.

SavingConfigurationBetweenSessions
Onethingyoumayhavenoticedisthatyoursettingsaboutwheretoshowthemessagearen'tpersistedbetweensessions.Whenyoulogoutandbackin,you
willhavethedefaultsettingsagain.Thisisn'tideal.Weshouldbesavingthesesettingssomehow.
WoWprovidesawayforyoutodothiscalledSavedVariables,butthereisanAcewaytodoitwiththeAceDBmethod,New
(http://www.wowace.com/addons/ace3/pages/api/acedb30/#wacedbnewtbldefaultsdefaultprofile).Wealreadyhavethelibrarylistedinour.TOC
file,andnowit'stimetouseit.
localdefaults={
profile={
message="WelcomeHome!",
showInChat=false,
showOnScreen=true,
},
}
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
self.db=LibStub("AceDB3.0"):New("WelcomeHomeDB",defaults,true)
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)
self.optionsFrame=LibStub("AceConfigDialog3.0"):AddToBlizOptions("WelcomeHome","WelcomeHome")
self:RegisterChatCommand("wh","ChatCommand")
self:RegisterChatCommand("welcomehome","ChatCommand")
end

(InthisexampleweassociatethesevariableswiththeAce3profile"datatype",butyoualsocanassociatethemwithchar,class,race,faction,realmor
global.SeetheAceDB3.0(http://www.wowace.com/addons/ace3/pages/api/acedb30/)docsformoreinformationondatatypes.)
Thestring"WelcomeHomeDB"referstotheSavedVariablesdefinitionintheTOCfile.Ifyoudon'tspecifyanythingforthethirdargumentallcharacters
usingtheaddonwillgettheirownprofile.Herewepassthebooleantrue.Thismeansthatunlessyouchangeprofilemanuallyallcharacterwillsharethe
same"Default"profile.
Afterthatweneedtoreplaceallofthereferencestotheoldvariables(e.g.self.messageorWelcomeHome.message)withself.db.profile.<variablename>
(e.g.self.db.profile.message).Thiswillrequireustochangetheget/setmethodsreferencedbyouroptionstableandoureventhandler.
Herearethenewcommandget/setmethods:
functionWelcomeHome:GetMessage(info)
returnself.db.profile.message
end
functionWelcomeHome:SetMessage(info,newValue)
self.db.profile.message=newValue
end
functionWelcomeHome:IsShowInChat(info)
returnself.db.profile.showInChat
end
functionWelcomeHome:ToggleShowInChat(info,value)
self.db.profile.showInChat=value
end
functionWelcomeHome:IsShowOnScreen(info)
returnself.db.profile.showOnScreen
end
functionWelcomeHome:ToggleShowOnScreen(info,value)
self.db.profile.showOnScreen=value
end

Andhereistheneweventhandler:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
ifself.db.profile.showInChatthen
self:Print(self.db.profile.message);
end
ifself.db.profile.showOnScreenthen
UIErrorsFrame:AddMessage(self.db.profile.message,1.0,1.0,1.0,5.0)
end
end
end

Asyoucansee,itwasjustasimplesubstitutionoftheoldvariablewiththenewAceDBvariable.ReloadyourUIandnothingshouldchange.Exceptnow
ifyouchangeanyofthesettings,theywillbepersistedacrossrestarts.
Thiswholeexercisewasabitsilly,ofcourse,becauseinarealworldaddonyouwouldstartoutusingAceDBforyourconfigurationdata,butnowyou
knowwhatitisforandwhyyoushouldbeusingit.

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

7/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

LocalizingYourStringswithAceLocale
Onethingalotofnewaddondevelopers(especiallythoseintheU.S.)forgetaboutishowmanypeoplewillbewantingtousetheiraddoninanonenglish
versionofthegameclient.Thismeansthatthereshouldbeaniceeasywayforthemtolocalizethestringsinyouraddonintotheirlanguage.(Oreven
better,submitthelocalizedstringstoyousoyoucanincludetheminyournextrelease.)
WithAce3,wedothisusingtheAceLocale3.0(http://www.wowace.com/addons/ace3/pages/api/acelocale30/)library.Thislibraryisnotamixinlike
theotherlibrarieswe'veusedsofar,sothewayweuseitisabitdifferent.

AddingAceLocale3.0totheProject
Let'sstartbygrabbingtheAceLocale3.0folderfromthepackagethatwedownloadedearlierandputtingitintoourLibsfolder.Wealsoshouldcreateour
firstlocalizationdatabasefile.CreateanemptyfilecalledenUS.luaandsaveitinthesamefolderasyour.TOCfile.
Atthispointourfolderstructureshouldlooklikethis:(Seetheoriginal(http://old.wowace.com/wiki/WelcomeHome_
_Your_first_Ace3_Addon#Adding_AceLocale3.0_to_the_Project)forabetterview)
WelcomeHome
Libs
AceAddon3.0
AceAddon3.0.lua
AceAddon3.0.xml
AceConfig3.0
AceConfigCmd3.0
AceConfigDialog3.0
AceConfigDropdown3.0
AceConfigRegistry3.0
AceConfig3.0.lua
AceConfig3.0.xml
AceConsole3.0
AceConsole3.0.lua
AceConsole3.0.xml
AceDB3.0
AceDB3.0.lua
AceDB3.0.xml
AceEvent3.0
AceEvent3.0.lua
AceEvent3.0.xml
AceGUI3.0
widgets
AceGUI3.0.lua
AceGUI3.0.xml
AceLocale3.0
AceLocale3.0.lua
AceLocale3.0.xml
CallbackHandler1.0
CallbackHandler1.0.lua
CallbackHandler1.0.xml
LibStub
LibStub.lua
Core.lua
embeds.xml
enUS.lua
WelcomeHome.toc

Then,weneedtoupdateourembeds.xmlfiletoreferencetothenewlyaddedAceLocale3.0asshownhere:
<Uixmlns="http://www.blizzard.com/wow/ui/"xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Scriptfile="Libs\LibStub\LibStub.lua"/>
<Includefile="Libs\CallbackHandler1.0\CallbackHandler1.0.xml"/>
<Includefile="Libs\AceAddon3.0\AceAddon3.0.xml"/>
<Includefile="Libs\AceEvent3.0\AceEvent3.0.xml"/>
<Includefile="Libs\AceDB3.0\AceDB3.0.xml"/>
<Includefile="Libs\AceLocale3.0\AceLocale3.0.xml"/>
<Includefile="Libs\AceConsole3.0\AceConsole3.0.xml"/>
<Includefile="Libs\AceGUI3.0\AceGUI3.0.xml"/>
<Includefile="Libs\AceConfig3.0\AceConfig3.0.xml"/>
</Ui>

Andour.TOCfile:
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
##SavedVariables:WelcomeHomeDB
##OptionalDeps:Ace3
##XEmbeds:Ace3
embeds.xml
enUS.lua
Core.lua

NoticethatthelocalizationfilecomesbeforetheCore.luafile.Thisisimportantoryourlocalizationdatabasewillnotbeinitializedbeforeitisusedbythe
codeinyouraddon.
Sincewehaveupdatedour.TOCfile,youwillneedtorestartWoWtogetthesechangesloadedintothegame.The/reloadtrickwon'tworkthistime.Once
you'vedonethat,goaheadandloginandmakesureeverythingisstillworking.

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

8/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

BuildingtheLocalizationDatabase
NowthatwehaveaplacetoputthelocalizedstringsfortheUSEnglish(enUS)versionofourAddon,weneedtopassthroughthesourcecodelookingfor
stringsthatshouldbelocalizable.(Inyourfutureaddonwork,Iwouldrecommendgoingaheadanddoingthisstepatthebeginningofyourdevelopment
insteadofwaitinguntiltheendaswedidhere.)
AftertakingapassthroughCore.lua,IaddedthefollowinglinestoenUS.lua:
localL=LibStub("AceLocale3.0"):NewLocale("WelcomeHome","enUS",true)
Chatcommands
L["welcomehome"]=true
L["wh"]=true
L["WelcomeHome!"]=truedefaultmessage
L["Message"]=true
L["Themessagetobedisplayedwhenyougethome."]=true
L["<Yourmessage>"]=trueusage
L["ShowinChat"]=true
L["Togglesthedisplayofthemessageinthechatwindow."]=true
L["ShowonScreen"]=true
L["Togglesthedisplayofthemessageonthescreen."]=true

Thisfilehastwoparts.ThefirstpartcreatesanewAceLocaleinstancewiththename"WelcomeHome"."enUS"isthelanguagecodeforUSEnglishand
trueasthethirdargumenttellsAceLocalethatthisisthedefaultlocale.Thesecondpartistheactualtranslations.Havingthevaluesbetruemakesthem
thesameastheirkeys.Thismeansthatinourcode,whenweaskforthelocalizedversionof"WelcomeHome!",wewillget"WelcomeHome!",oranother
stringdependingonthelanguage.

UsingtheLocalizedStringsintheAddon
TouseAceLocaleinouraddonnowweaskAceLocaleforaninstancewithtranslationsanditwillgiveusatableforthecurrentlocaleorthedefaultifit
doesn'thaveatranslationforthelanguagetheuserisplayingin.
Now,addthefollowinglinetothetopofCore.lua,thiscallstheGetLocale(http://www.wowace.com/addons/ace3/pages/api/acelocale30/#wacelocale
getlocaleapplicationsilent)method(besureyouadditabovetheoptionstabledefinition).
localL=LibStub("AceLocale3.0"):GetLocale("WelcomeHome")

NowwecanusethisanywhereweneedatranslatedstringbyputtingL[]aroundit.Forexamplethefirstpartofouroptionstablenowbecomesthis:
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name=L["Message"],
desc=L["Themessagetobedisplayedwhenyougethome."],
usage=L["<Yourmessage>"],
get="GetMessage",
set="SetMessage",
},
...etc...

Thisprocessisprettystraightforward,soIwon'tbothershowingallofithere.Youcanseethefinalsourcefilesattheendofthearticletoseeifyougot
themallinyouraddon.
UsingAceLocaleisasimplewaytogetgoodlocalizationsupportinyouraddon.[1](http://kb.wowace.com/projects/localizingyourproject/)

Mixedinvariables
Ifyouwanttousetextelementsmixedwithvariablesfordifferentoutputyoucanalsousefunctionsinyourlocaletable.Sothewordortextelementorder
doesnotmatterinyourscriptandtranslationswillsoundmorenatural.
enUS/enGB:
L['WeheartlywelcomeplayerX.']=function(X)
return'Weheartlywelcomeplayer'..X;
end

deDE:
L['WeheartlywelcomeplayerX.']=function(X)
return'Wirhei\195\159enSpieler'..X..'herzlichWillkommen';
end

script.lua:
self:Print(L['WeheartlywelcomeplayerX.'](playername));

Conclusion
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

9/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

Youhavestartedfromnothingandcreatedalocalizableaddonthatuseschatcommands,respondstoeventsandprovidesfeedbacktotheuserinacouple
ofdifferentways.Thereareanumberofinterestingthingsyoucandotothisaddonifyouwanttokeepgoing.Someexamples:
Provideaconfigurationmenu(http://www.wowace.com/addons/ace3/pages/aceconfig30optionstables/),inadditiontoslashcommands
AddsupportforLibDataBroker(https://github.com/tekkub/libdatabroker11/wiki/)forine.g.DataDisplayAddOns[2]
(http://forums.wowace.com/showthread.php?t=14903)
Showdifferentmessageswhenyouzoneintootherareas(e.g."WelcometoTheBadlands,HomeofUldaman!")
YoumightalsowanttoreadWowAce'sCodingTips(http://old.wowace.com/wiki/Coding_Tips)page,whichcanproveveryuseful.
HopefullythathelpsyougetstartedwithAce3developmentandleadsyoudowntheroadtosuccessfuladdonauthoring.Bestofluck!

JointheAceCommunity
AsyougetmoreinterestedinAce3development,youshouldconsidergettinginvolvedintheAcecommunityatwowace.com(http://www.wowace.com)
Thereisanumberofresourcesavailable:
Versioncontrol(http://en.wikipedia.org/wiki/Revision_control)serverforSubversion(http://en.wikipedia.org/wiki/Apache_Subversion),Git
(http://en.wikipedia.org/wiki/Git_%28software%29),orMercurial(http://en.wikipedia.org/wiki/Mercurial)[3]
(http://old.wowace.com/wiki/What_is_the_SVN%3F)[4](http://kb.wowace.com/projects/packaginganaddon/)
Webbasedforum(http://forums.wowace.com/)
IRCchannel(http://kb.wowace.com/ircinformation/)
Wiki(http://old.wowace.com/wiki/Main_Page)fullofdocumentationandhelp
YoualsoshouldconsiderpublishingyourAce3addonatwowinterface.com(http://www.wowinterface.com/).

FinalSourceFiles
HereisthefinalcontentsofWelcomeHome.toc,embeds.xml,Core.luaandenUS.luaincaseyouwanttocheatandgorighttotheend.

WelcomeHome.toc
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
##SavedVariables:WelcomeHomeDB
##OptionalDeps:Ace3
##XEmbeds:Ace3
embeds.xml
enUS.lua
Core.lua

embeds.xml
<Uixmlns="http://www.blizzard.com/wow/ui/"xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Scriptfile="Libs\LibStub\LibStub.lua"/>
<Includefile="Libs\CallbackHandler1.0\CallbackHandler1.0.xml"/>
<Includefile="Libs\AceAddon3.0\AceAddon3.0.xml"/>
<Includefile="Libs\AceEvent3.0\AceEvent3.0.xml"/>
<Includefile="Libs\AceDB3.0\AceDB3.0.xml"/>
<Includefile="Libs\AceLocale3.0\AceLocale3.0.xml"/>
<Includefile="Libs\AceConsole3.0\AceConsole3.0.xml"/>
<Includefile="Libs\AceGUI3.0\AceGUI3.0.xml"/>
<Includefile="Libs\AceConfig3.0\AceConfig3.0.xml"/>
</Ui>

Core.lua
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0","AceEvent3.0")
localL=LibStub("AceLocale3.0"):GetLocale("WelcomeHome")
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name=L["Message"],
desc=L["Themessagetobedisplayedwhenyougethome."],
usage=L["<Yourmessage>"],
get="GetMessage",
set="SetMessage",
},
showInChat={
type="toggle",
name=L["ShowinChat"],
desc=L["Togglesthedisplayofthemessageinthechatwindow."],
get="IsShowInChat",
set="ToggleShowInChat",
},
showOnScreen={

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

10/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

type="toggle",
name=L["ShowonScreen"],
desc=L["Togglesthedisplayofthemessageonthescreen."],
get="IsShowOnScreen",
set="ToggleShowOnScreen",
},
},
}
localdefaults={
profile={
message=L["WelcomeHome!"],
showInChat=false,
showOnScreen=true,
},
}
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
self.db=LibStub("AceDB3.0"):New("WelcomeHomeDB",defaults,true)
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)
self.optionsFrame=LibStub("AceConfigDialog3.0"):AddToBlizOptions("WelcomeHome","WelcomeHome")
self:RegisterChatCommand("wh","ChatCommand")
self:RegisterChatCommand("welcomehome","ChatCommand")
end
functionWelcomeHome:OnEnable()
Calledwhentheaddonisenabled
self:RegisterEvent("ZONE_CHANGED")
end
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
ifself.db.profile.showInChatthen
self:Print(self.db.profile.message)
end
ifself.db.profile.showOnScreenthen
UIErrorsFrame:AddMessage(self.db.profile.message,1.0,1.0,1.0,5.0)
end
end
end
functionWelcomeHome:ChatCommand(input)
ifnotinputorinput:trim()==""then
InterfaceOptionsFrame_OpenToCategory(self.optionsFrame)
else
LibStub("AceConfigCmd3.0"):HandleCommand("wh","WelcomeHome",input)
end
end
functionWelcomeHome:GetMessage(info)
returnself.db.profile.message
end
functionWelcomeHome:SetMessage(info,newValue)
self.db.profile.message=newValue
end
functionWelcomeHome:IsShowInChat(info)
returnself.db.profile.showInChat
end
functionWelcomeHome:ToggleShowInChat(info,value)
self.db.profile.showInChat=value
end
functionWelcomeHome:IsShowOnScreen(info)
returnself.db.profile.showOnScreen
end
functionWelcomeHome:ToggleShowOnScreen(info,value)
self.db.profile.showOnScreen=value
end

enUS.lua
localL=LibStub("AceLocale3.0"):NewLocale("WelcomeHome","enUS",true)
Chatcommands
L["welcomehome"]=true
L["wh"]=true
L["WelcomeHome!"]=truedefaultmessage
L["Message"]=true
L["Themessagetobedisplayedwhenyougethome."]=true
L["<Yourmessage>"]=trueusage
L["ShowinChat"]=true
L["Togglesthedisplayofthemessageinthechatwindow."]=true
L["ShowonScreen"]=true
L["Togglesthedisplayofthemessageonthescreen."]=true

Attribution
ThisisanimportfromWelcomeHomeYourfirstAce3Addon(http://old.wowace.com/wiki/WelcomeHome__Your_first_Ace3_Addon),whichisa
continuationfromWelcomeHomeYourfirstAce2Addon(http://old.wowace.com/wiki/WelcomeHome__Your_first_Ace2_Addon)
Retrievedfrom"http://wow.gamepedia.com/index.php?title=WelcomeHome__Your_first_Ace3_Addon&oldid=2809447"
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

11/12

3/7/2016

WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft

Categories: Tutorials HOWTOs

Thispagewaslastmodifiedon8November2011,at22:11.
ContentisavailableunderCCBYSA3.0unlessotherwisenoted.
WorldofWarcraftcontentandmaterialsaretrademarksandcopyrightsofBlizzardoritslicensors.Allrightsreserved.ThissiteisapartofCurse,
Inc.andisnotaffiliatedwithBlizzard.

Facebook

Sign In

About Curse

Twitter

Register

Advertise

Youtube

Careers

Terms of Service

Newsletter

Help

Privacy
Policy

Copyright 2005-2016, Curse Inc.

http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon

12/12