Sometimes you would like to control the action a button will start when it is clicked. Maybe you want to add extra buttons, maybe you just want to control the behavior of existing ones. I will tell you in a moment how to do that, but first you should know something about how the default UI handles its buttons.
IMPORTANT: Recommendations involving changing ActionButton_GetPagedID do not work after WoW 2.0
Button Handling in the Default UI[]
World of Warcraft supplies the player with 6 action bars, each having 12 buttons. Some classes, like warriors, rogues and druids have a few more bars due to their stances. have you ever noticed that the lower left bar changes its actions when you go in stealth or in battle stance? When changing stances, there are no buttons hidden or shown. Whatever stance you are in, the buttons remain tight at their position. What's actually changing are the action slot IDs of the buttons. You can read a bit more about this here: ActionSlot API Type. Two buttons having the same action ID means they are twins. If you drag an action onto one of them, the other one will adopt this action, too. This is because the potions, spells, abilities, macros, etc. on your buttons are not bound to the button itself, but to its action ID.
So, how does a button know its action ID? Let's look at Blizzard's ActionButton.lua, which you can obtain by downloading the Blizzard Interface Customization Tools here: http://www.blizzard.com/support/wow/?id=aww01669p (after installing this, you can find ActionButton.lua in "/Blizzard Interface Data/FrameXML"). The functions in this file handle the behaviour of (guess what?) buttons. But not of any buttons. The methods there are used by the action buttons on your bars.
In the ActionButton.lua file, every time a function (i.e. API_UseAction) needs to know the action ID of a specific button, it calls
id = ActionButton_GetPagedID(button)
I wouldn't recommend looking at the code of this method, because your brain may explode (unless you are good at reading uncommented and foreign code in Lua), but I will summarize the method for you. Every Blizzard UI button has an ID, specified in the corresponding XML File:
<Button name="SomeName" ...someOtherValues... id="2"> ...some Code </Button>
This ID can be obtained by calling button:GetID(). Unfortunately, this ID ranges from only 1-12, and is then offset based on the type of button or action page page, so it's not very convenient if you want to create your own button.
Luckily, the blizzard code recognizes that AddOns need to create their own buttons so it provides special behaviour if you set the id of your Button to 0, using the "action" attribute of the button.
Controlling a Button's Action Slot ID[]
To make your own action button with a specific slot you simply have to set your button's ID to 0 (which is the default if you dont specify, but I recommend you set it anyway), and set the button's "action" attribute. You can do this in the XML, or in lua code afterwards.
XML:
<CheckButton name="customButton" inherits="ActionBarButtonTemplate" id="0">
<Attributes>
<Attribute name="action" value="101"/>
</Attributes>
</CheckButton>
LUA:
customButton:SetAttribute("action", 101);