Editing WoW:AddOn programming tutorial/Introduction (section)

=== The .xml or XML visual elements file ===
UI Elements, or Widgets, are all of the tiny bits of graphics that make up the User Interface. WoW uses XML to layout everything that you see on the screen. Additionally, when things happen (called Events, remember?) to the widgets on the screen, Widget Handlers can be called to perform whatever action you want. We will see shortly how we tell WoW which widgets we are interested in and which Events we want handled by which Widget Handler.

==== Blizzard XML format declared ====
For those of you who don't know, XML stands for eXtensible Markup Language and is a means of tagging content with identifiers. What the identifiers are and how they are organized can be defined in something called a Schema. In our case, we want to create XML documents that WoW will understand, so we will use the Schema provided by Blizzard for the Wow User Interface.

We declare that our document conforms to the Blizzard schema with the following bit of magic:

 <nowiki><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"></nowiki>
 
 </Ui>

The exact meaning of all of the above is beyond the scope of this tutorial. Consider it a magic formula that you always put in every .xml file you will create for the WoW user interface. For those of you that like to reformat things, the first three lines can be merged into one line (use spaces), but the fourth line (..\..\FrameXML\UI.xsd"> ) needs to be on a line by itself starting in column 1.

There are a few general notes that you need to know about concerning XML, particularly as it is used by WoW. The generalized format of a tag is:

 <tagname attribute="attribute value" anotherattribute="anotherattribute value">
 
 </tagname>

A tag must have a tagname, and it may have zero or more attributes along with the attributes' associated values in double quotes. The tag is everything between the ''''<tagname'''' and the trailing ''''>''''. The tag is closed by an end tag with the same name as tag: ''''</tagname>''''. Tagnames do not have spaces, are case sensitive, start with a capital letter, and additional words are also capitalized. A valid tagname might be 'BackgroundWidgets', while 'backgroundwidgets' would not be valid. Blizzard defines all valid tagnames in their UI.xsd. The [[XML user interface]] page has a good list under [[XML user interface#Widget Elements|Widget Elements]] which will aid you until we get further along.

Everything between the tag and the end tag is content to the tag. Everything. Even other tags along with their content. In the case where there is no content to a tag, the end of the tag has ''''/>'''' instead of just ''''>'''' and there is no separate end tag. A complete tag with no content looks like:

 <tagname attribute="attribute value" anotherattribute="anotherattribute value"/>

Using the below piece of magic as an example, we can see that it is a tag with the name ''''Ui'''' and it has three attributes (the funny fourth line is a part of the prior attribute). Content is represented by the space between the end of the tag (the ''''>'''' on the fourth line) and the ''''</Ui>'''' end tag.

==== HelloWorld.xml ====
Now to continue with our Hello, World XML example. Place the following into your HelloWorld.xml file and save it:

 <nowiki><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"></nowiki>
 
 </Ui>

Now before we create the frame for our add-on, we have to add a simple line of code that tells the WoW engine where to find our function in our .lua file. Notice this is a tag with no content, which gets a '/>' and no end tag. This is because this tag is solely for the engine.

  <Script File="HelloWorld.lua"/>

WoW connects everything to a frame, even other frames. So, in order to create something that WoW will interact with, we create a frame:

  <Frame name="HelloWorldFrame">
 
  </Frame>

The tagname is ''''Frame'''' and we have used the ''''name'''' attribute and given the attribute the value of ''''HelloWorldFrame''''.

Our frame tag is included as content to the Ui tag and so goes between the start Ui tag and the end Ui tag. To help keep track of what is surrounding what, we indent the content with respect to the enclosing tags like this:

 <nowiki><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"></nowiki>
   <Script File="HelloWorld.lua"/>
   <Frame name="HelloWorldFrame">
 
   </Frame>
 </Ui>

It is very important that you do not mix up the various end tags, and indenting helps keep things straight. Notice that the ''''Frame'''' and ''''Script'''' tag (and for the ''''Frame'''' both the start tag and the end tag) are completely surrounded by the ''''Ui'''' tag.

Inside the frame, one of the many things we can define are Scripts. Scripts are nothing more than small pieces of Lua code. Where we place the script determines when it will be invoked. Because Scripts live within a Frame, we include the ''''Scripts'''' tag inside the ''''Frame'''' tag. Notice the difference, in the ''''Scripts'''' tag, the 's' sets it apart from the ''''Script'''' tag.

  <Frame name="HelloWorldFrame">
   <Scripts>
 
   </Scripts>
  </Frame>

The various widgets have several Events that can occur; and if we want to declare a Widget Handler to process the event, we include the event name under the Scripts tag of the widget we are interested in. Not every widget has the same set of events. In this example, we are interested in an event named ''''OnLoad''''. The OnLoad event happens when the widget is loaded into the UI. For this example, we want the OnLoad event to run the script named HelloWorld. This script was defined in the HelloWorld.lua as a function.

   <Scripts>
    <OnLoad>
     HelloWorld();
    </OnLoad>
   </Scripts>

Take a look at the [[Widget handlers]] page for a list of widgets and the events you can write widget handlers for.

The complete HelloWorld.xml file should look like this:

 <nowiki><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"></nowiki>
   <Script File="HelloWorld.lua"/>
   <Frame name="HelloWorldFrame">
    <Scripts>
     <OnLoad>
      HelloWorld();
     </OnLoad>
    </Scripts>
   </Frame>
 </Ui>

There is an important item you should note in the above: the '''''HelloWorld();''''' is the only piece which is NOT a tag or an attribute. It is important to note that content in a WoW .xml UI document is always a piece of code if it is not another set of tags and their associated attributes. The only valid place for a piece of code is under the tag for an event.

Having gotten this far, it is time to run your new add-on.