User:Leethal/Dongle tutorial

From WoWWiki

Introduction

This tutorial covers the basics of creating a WoW addon. It assumes that you are familiar with Lua. If you're not, read this great online book on the subject.

My experience when following tutorials about coding, is that I scan through the tutorial and read the code samples. I don't really read the text. This tutorial therefore mostly consists of code examples.

The WoW Addon

A wow addon has at least two things - a .toc file (Table Of Contents) and a main script file. The .toc is an index file, containing information about which version of WoW the addon supports, the name of the addon, a short description etc. It looks like this:

## Interface: 20003
## Title: Your Addon Name
## Notes: A short description
## Author: Your Name
## Version: The version of the addon ("1.0", "0.3.25 beta" and so on)

YourAddon.lua
Localization.en.lua
Localization.de.lua

The only mandatory fields are Interface and Title. The other fields (there are also many fields available not listed in this example) is optional. To make WoW detect and load the addon, put it in "[wow directory] / Interface / AddOns / AddonName / AddonName.toc".

YourAddon.lua, Localization.en.lua etc is filenames. They are in the same directory as the .toc, and contains the Lua itself.

Making a Dongle addon - Hello, Dongle!

Download dongle from DOWNLOAD LOCATION OMG. Put it in the addon directory, and include it in the .toc. Create the HelloDongle.lua too.

## Interface: 20003
## Title: Hello, Dongle!
## Notes: A test addon

Dongle.lua
HelloDongle.lua

Edit HelloDongle.lua. Initialize dongle.

HelloDongle = DongleStub("Dongle-1.0"):New("HelloDongle")

The Enable event is called when the interface is fully loaded, and the addon itself is loaded.

function HelloDongle:Enable()
  self:Print("Hello Dongle initialized") -- :Print() is a Dongle function, printing a message to the chat frame.
end

When something happens in WoW, an event is fired. This can be hooked by the addon. A list of events: Events (API). This addon will use the CHAT_MSG_SAY event, fired every time you recieve a /s.

function HelloDongle:Enable()
  self:RegisterEvent(CHAT_MSG_SAY) -- :RegisterEvent()is another Dongle function

  self:Print("Hello Dongle initialized")
end
 
function HelloDongle:CHAT_MSG_SAY(event, message, author)
  if string.find(message, "hello") then
    self:Print(author.." said hello.")
  end
end

The first parameter in HelloDongle:CHAT_MSG_SAY() is the name of the event ("CHAT_MSG_SAY"). Any additional parameters is the "arg1", "arg2" etc globals associated with the event. What this is depends on the event itself (and it's all documented at Events (API)). In this situation, "arg1" is the message itself. "arg2" is the author and "arg3" is the language (orcish, common etc).