How to create custom links

From ESOUI Wiki

Jump to: navigation, search

The chat link system in ESO is actually quite flexible from an addon perspective. Here's a guide on how to create custom links and handlers for them. -- Aiiane 16:03, 5 May 2014 (CDT)

Contents

Link format

Links are encoded in text via the following formatting codes:

|H<style>:<type>[:<data>...]|h<text>|h
style
LINK_STYLE_DEFAULT (0) or LINK_STYLE_BRACKETS (1). Defines if text should be shown with or without square brackets.
type
An arbitrary string indicating what kind of link this is. The built-in link types in ESO are:
ITEM_LINK_TYPE = "item"
ACHIEVEMENT_LINK_TYPE = "achievement"
CHARACTER_LINK_TYPE = "character"
CHANNEL_LINK_TYPE = "channel"
BOOK_LINK_TYPE = "book"
DISPLAY_NAME_LINK_TYPE = "display"
URL_LINK_TYPE = "url"
Any other type will result in a UI error about invalid tooltips if clicked on a stock client.
Special case is URL_LINK_TYPE. This link type only is handled only in pregame GUI (login screen, character selection screen), ingame GUI doesn't handle this link type.
data (optional)
After the link type, any number of colon-separated pieces of data can follow.
These are passed on to the link handler functions as strings when the link is clicked.
For "item" links, see ZO_LinkHandler_CreateLink for examples of data fields.
text
The actual text displayed in the chat window, including brackets, if any.
(The client will not automatically add brackets to links - thus, it is possible to link non-bracketed text as well.)

Thus, the following code will create a link with the text "[Test]" with link type "foo" plus data "bar" and "baz":

|H1:foo:bar:baz|h[Test]|h

Chat message length limits

All of the internal strings in a link still count toward the 750 character limit for chat messages!

Links with significant amounts of data will drastically reduce the other text that can be sent as part of a chat message to other players.

Links that are just added to the local chat window, rather than being sent over the network, have no such length restriction.

Link handlers

Of course, custom link types aren't very useful if you can't write handlers for them, since the default behavior for any unrecognized link type is to throw a UI error. Note that this also means custom links won't be usable by anyone who doesn't have the proper addon to recognize them - users without the addon will see the link in chat but clicking it will give them a UI error.

All link handling is routed through (perhaps unsurprisingly) LINK_HANDLER, which is a ZO_CallbackObject - in other words, it's a callback manager. In order to create a link handler, you need to register for the callback event that fires when a link is clicked:

LINK_HANDLER:RegisterCallback(LINK_HANDLER.LINK_MOUSE_UP_EVENT, MyAddon.HandleClickEvent) --as for Update 4 default ingame GUI uses this event
LINK_HANDLER:RegisterCallback(LINK_HANDLER.LINK_CLICKED_EVENT, MyAddon.HandleClickEvent)  --this event still can be used, so the best practise is registering both events
 
function MyAddon.HandleClickEvent(rawLink, mouseButton, linkText, linkStyle, linkType, ...) --where ... is the data
  if linkType == "foo" then
    -- Example handling for the foo link type
    d("A foo link was clicked!")
 
    -- Returning true means that the link type was handled
    -- and shouldn't use the default tooltip functionality.
    return true
  end
end
rawLink string
The string encoding of the entire link, including the |H and |h control characters.
mouseButton int
The mouse button that was used to click on the link. 1 = MOUSE1, 2 = MOUSE2, 3 = MOUSE3, etc.
linkText string
The displayed text portion of the link.
linkStyle string
it is "0" for LINK_STYLE_DEFAULT or "1" for LINK_STYLE_BRACKETS.
linkType string
The type of link, e.g. "achievement" or "item".
... (vararg)
Any further data specified in the link will be passed as additional string arguments.

Return values

It's important to return true from the handler for a custom link type - otherwise the default handler will also be invoked, resulting in a UI error.

However, you should only return true when the linkType matches the type of link you're handling. Otherwise you'll disable the handler for all sorts of tooltips that aren't the ones you're trying to handle.

A note on self

If you want self available in your link handler function, you can take advantage of the fact that ZO_CallbackObject allows specifying prefix arguments to registered callbacks:

LINK_HANDLER:RegisterCallback(LINK_HANDLER.LINK_MOUSE_UP_EVENT, MyAddon.HandleClickEvent, MyAddon)
 
function MyAddon:HandleClickEvent(rawLinkString, mouseButton, linkText, linkStyle, linkType, ...)
  -- this handler will have self defined (the passed in MyAddon from the registration)
end

You can also use this to pass other fixed arguments to your handler function, if you so desire. Any arguments added to the end of the RegisterCallback call will be prefixed to the argument list when calling your handler.

Personal tools
Namespaces
Variants
Actions
Menu
Wiki
Toolbox