These templates are defined in FrameXML/SecureHandlerTemplates.xml and FrameXML/SecureHandlers.lua

SecureHandlers (created by inheriting SecureHandlerBaseTemplate) enable the use of code snippets inside the RestrictedEnvironment. Each snippet is a string that behaves like the body of a Lua function, but it can only contain a subset of the World of Warcraft API.

Defined methods

All SecureHandlers have four common methods defined by SecureHandlerBaseTemplate:

  • SecureHandlerBaseTemplate:Execute(body) - Executes a code snippet in the widget's restricted environment.
  • SecureHandlerBaseTemplate:WrapScript(header, script, preBody [, postBody]) - Wraps a widget script with code snippets to execute in the restricted environment.
  • SecureHandlerBaseTemplate:UnwrapScript(frame, script) - Strips (and returns) the outermost-wrapped handler for the frame's script handler.
  • SecureHandlerBaseTemplate:SetFrameRef(id, refFrame) - Creates a frame reference that can be accessed inside the restricted environment.


  • The base template has an OnLoad widget script which adds the four defined methods.
  • All other secure handlers, listed in the table below, add another widget script that will execute a code snippet defined using Frame:SetAttribute()
Template Description Executed Snippets (arguments)
SecureHandlerBaseTemplate Enables use of defined methods on the frame. none
SecureHandlerStateTemplate Fires snippet when a state-xxx attribute changes. _onstate-xxx(self, stateid, newstate)
SecureHandlerAttributeTemplate Responds to attribute changes _onattributechanged(self, name, value)
SecureHandlerClickTemplate Responds to clicks _onclick(self, button, down)
SecureHandlerDoubleClickTemplate Responds to double clicks _ondoubleclick(self, button, down)
SecureHandlerDragTemplate Enables dragging _ondragstart(self, button), _onreceivedrag(self, button, kind, value, ...)
SecureHandlerMouseUpDownTemplate Mouse up/down events _onmouseup(self, button), _onmousedown(self, button)
SecureHandlerMouseWheelTemplate Mouse wheel _onmousewheel(self, delta)
SecureHandlerEnterLeaveTemplate Mouse entering/leaving frame _onenter(self), _onleave(self)
SecureHandlerShowHideTemplate Frame being shown/hidden _onshow(self), _onhide(self)


local frame = CreateFrame("Frame", nil, "SecureHandlerClickTemplate")
frame:SetAttribute("_onclick", [=[
	-- self, button, down
	if button == "RightButton" then

External links