Download
(10 Kb)
Download
Updated: 03/22/24 04:02 PM
Compatibility:
Scions of Ithelia (9.3.0)
Updated:03/22/24 04:02 PM
Created:05/28/19 09:18 AM
Monthly downloads:75,875
Total downloads:1,701,320
Favorites:1,256
MD5:
Categories:Libraries, Data Mods
9.3.0
LibChatMessage  Updated this week!  Popular! (More than 5000 hits)
Version: 1.2.1
by: sirinsidiator [More]
For years addon authors have abused the debug methods d(), df() and CHAT_SYSTEM:AddMessage() to show messages in chat or even added text directly to the chat buffer, preventing other addons from interacting with the output. LibChatMessage offers an easy alternative that uses the same method as the vanilla UI to print system messages.

Features

Chat Messages
The main purpose of the library is to provide an easy API that can be used to print messages in chat. This is done via so called chat proxy objects. Each addon can create their own proxy and call the Print and Printf method (similar to d() and df()).

Addon Tag
The library will automatically prefix each message with a tag provided to each chat proxy instance by their addon. Users can choose if they want the tag to be the full addon name or a shortened string.

Time Prefix
The library can also print the current time in front of each chat message. This is disabled by default to avoid compatibility issues with other chat addons, but can be enabled via the settings explained below.

Chat History
Another feature of the library is to store all incoming chat messages and restore them again at UI load. This is also disabled by default to avoid compatibility problems (especially with pChat). Unlike with pChat the history is saved in raw form, meaning that any modifications to the message made by addons are not stored and instead applied when the messages are restored. This also means that information like the guild name is lost when the player leaves a guild and can lead to restored messages showing no or even a different guild name.

Custom Chat Links
Starting with version 1.2.0, the library offers a way for addons to send arbitrary data links in chat.

Known Issue/Drawback
  • If you register a chat link, but do not handle it, an error will occur, if the user clicks it.
  • Chat bubbles will show raw data. We can not modify them.
  • In order to display custom links in the chat input box, the lib sets all types of markup as allowed. this means that the text shown in the box may look different from what is actually being sent or visible to users without the library. For example a single | (pipe) character won't show until the message is sent and using color markup will change the text color in the input field, but show up as raw text in the chat once sent.

Quick Start
Add LibChatMessage as a dependency to your addon manifest:
Code:
## DependsOn: LibChatMessage
Afterwards you can create a chat proxy and print messages like so:
Lua Code:
  1. local chat = LibChatMessage("MyAddon", "MA") -- long and short tag to identify who is printing the message
  2. chat:Print("Simple message") -- instead of d()
  3. chat:Printf("Formatted %s", "message") -- instead of df()
  4. chat:SetTagColor("ff0000"):Print("Message with a different tag color") -- To change the tag color for e.g. warnings. The message itself can be colored with a color tag, although I can't really recommend doing that
  5. chat:SetEnabled(false) -- in case the output of this ChatProxy should be enabled. Could be used when a settings is supposed to disable chat messages for an addon
  6. chat:Print("Ignored message") -- won't show up

Settings
LibChatMessage offers several settings to allow players to control the look of the output. The settings can be changed via the "/chatmessage" slash command, or via the libraries API. Using the slash command with an invalid command will print the following message to chat:
Code:
/chatmessage <command> [argument]
<time>      [on/off]           Enables or disables the time prefix
<chat>      [on/off]           Controls the time prefix on regular chat
<format>    [auto/12h/24h]     Changes the used time format
<tag>       [off/short/long]   Changes the length of the used tag
<history>   [on/off]           Restore old chat after login
<age>       [seconds]          The maximum age of restored chat
Example: /chatmessage tag short
Using a command without an argument will print the current state of the setting to chat.

API Reference

Create
Returns a new instance of ChatProxy with the given tags.
Code:
local chat = LibChatMessage.Create(longTag, shortTag)
or
Code:
local chat = LibChatMessage(longTag, shortTag)
ChatProxy:SetTagColor
Sets the color of the message tag for the next printed message (resets afterwards). Can be either a hex string ("ff0000") or a ZO_ColorDef object. Returns the ChatProxy instance so the call can be chained as shown in the quick start example.
Code:
local chat = chat:SetTagColor(color)
ChatProxy:Print
Method to a print regular messages to chat. The message will automatically be prefixed with the time and tag based on user preferences.
Code:
chat:Print(message)
ChatProxy:Printf
Method to print a message formatted via string.format to chat. The message will automatically be prefixed with the time and tag based on user preferences.
Code:
chat:Printf(formatString, ...)
ChatProxy:SetEnabled
Setter to turn this proxy off, so it no longer prints anything to chat when one of its methods is called. Can be used to easily enable or disable chat messages for an addon based on user preferences.
Code:
chat:SetEnabled(enabled)
ClearChat
Removes all messages from all chat windows.
Code:
LibChatMessage:ClearChat()
ClearHistory
Removes all stored messages from the chat history.
Code:
LibChatMessage:ClearHistory()
GetHistory
Returns the current chat history table.
Code:
LibChatMessage:GetHistory()
SetTimePrefixEnabled
Sets the time prefix feature enabled or disabled. Disabled by default as it may cause problems with other chat addons that have similar features.
Code:
LibChatMessage:SetTimePrefixEnabled(enabled)
IsTimePrefixEnabled
Returns true if the time prefix feature is enabled.
Code:
local enabled = LibChatMessage:IsTimePrefixEnabled()
SetRegularChatMessageTimePrefixEnabled
Sets the time prefix feature for player chat channels enabled or disabled. Enabled by default, but only counts if the time prefix feature itself is turned on.
Code:
LibChatMessage:SetTimePrefixEnabled(enabled)
IsRegularChatMessageTimePrefixEnabled
Returns true if the time prefix feature is enabled for player chat channels.
Code:
local enabled = LibChatMessage:IsTimePrefixEnabled()
TIME_FORMATS
An array containing the time formats passed to os.date for the time prefix.
  1. TIME_FORMAT_AUTO = "[%X]" - uses locale dependent formatting
  2. TIME_FORMAT_12 = "[%I:%M:%S %p]" - 12h time format
  3. TIME_FORMAT_24 = "[%T]" - 24h time format (ISO 8601)

SetTimePrefixFormat
Sets the format for the time prefix feature. Can be either one contained in TIME_FORMATS, or a custom format string. Custom strings should be wrapped in brackets.
Code:
LibChatMessage:SetTimePrefixFormat(format)
GetTimePrefixFormat
Returns the time prefix formatting string.
Code:
local format = LibChatMessage:GetTimePrefixFormat()
SetTagPrefixMode
Sets the mode used for the proxy tag for addon messages.
Available modes are:
  1. TAG_PREFIX_OFF - Disables showing a tag. The long tag will still be stored in the history in case it is enabled.
  2. TAG_PREFIX_LONG - Prints the long tag provided by an addon in front of the message
  3. TAG_PREFIX_SHORT - Prints the short tag provided by an addon in front of the message
Code:
LibChatMessage:SetTagPrefixMode(mode)
GetTagPrefixMode
Returns the current message tag mode.
Code:
local mode = LibChatMessage:GetTagPrefixMode()
SetChatHistoryEnabled
Sets the chat history feature enabled or disabled on the next UI load. This feature is not compatible with pChat and disabled by default.
Code:
LibChatMessage:SetChatHistoryEnabled(enabled)
IsChatHistoryEnabled
Returns true if the message history will be enabled on the next UI load.
Code:
local enabled = LibChatMessage:IsChatHistoryEnabled()
IsChatHistoryActive
Returns true if the message history is active right now.
Code:
local enabled = LibChatMessage:IsChatHistoryActive()
SetChatHistoryMaxAge
Sets the maximum age for chat messages to be restored on UI load in seconds. Default is 3600s (= 1h).
Code:
LibChatMessage:SetChatHistoryMaxAge(maxAge)
GetChatHistoryMaxAge
Returns the maximum age for chat messages in the history.
Code:
local maxAge = LibChatMessage:GetChatHistoryMaxAge()
RegisterCustomChatLink
Register a link type to be valid. Optional with a reformatter function.
All unregistered chat links will be change to an "unknown" link with all data stripped off upon receiving them from chat channel.
If someone is posting a chat link to someone, not having the addon it belongs to, a message is shown in the upper right corner instead of causing an error.

Code:
LibChatMessage:RegisterCustomChatLink(YOUR_LINK_TYPE)
LibChatMessage:RegisterCustomChatLink(YOUR_LINK_TYPE, reformatLinkFunc)
The reformatter has the following signature:
Code:
local function reformatLink(linkStyle, linkType, data, displayText)
    return ZO_LinkHandler_CreateLinkWithFormat(displayText, nil, linkType, linkStyle, data)
end
LibChatMessage:RegisterCustomChatLink(YOUR_LINK_TYPE, reformatLink)
displayText - Text shown to the user
linkTyype - Your link type (YOUR_LINK_TYPE)
linkStyle - Built-in values: LINK_STYLE_BRACKETS, LINK_STYLE_DEFAULT (number)
data - remaining part of the chat link containing the data your provided. (string)

The reformatter function can be used to localize the displayText.
Your chat link must provide at least one data column.

After registering a link type, you MUST add a link click handler.
See https://wiki.esoui.com/How_to_create_custom_links.

Example
Code:
function addon:OnLinkClicked(link, button, text, color, linkType, ...)
    if linkType ~= YOUR_LINK_TYPE then
        return
    end
    if button == MOUSE_BUTTON_INDEX_LEFT then
        -- Do your stuff
    elseif button == MOUSE_BUTTON_INDEX_MIDDLE then
        -- Do your stuff
    end
    return true -- link has been handled
end

function addon:InitLinkHandler()
    LINK_HANDLER:RegisterCallback(LINK_HANDLER.LINK_CLICKED_EVENT, self.OnLinkClicked, self)
    LINK_HANDLER:RegisterCallback(LINK_HANDLER.LINK_MOUSE_UP_EVENT, self.OnLinkClicked, self)
end
The value of the "unknown" link type can be found here:
LibChatMessage.UNKNOWN_LINK_TYPE
v1.2.1
- fixed error on chat history restore due to corrupted saved variable after a very long addon generated message was printed
- updated for Scions of Ithelia

v1.2.0
- added support for custom chat links (thanks votan)
- updated for Blackwood

v1.1.3
- fixed error when events are received before saved variables are loaded

v1.1.2
- updated for chat system changes in game version 5.3.5 (temporary workaround has been removed)

v1.1.1
- fixed error when an addon tries to print a message during initialization

v1.1.0
- added temporary workaround for chat formatters not working. See description for details.
- updated for Harrowstorm

v1.0.1
- added missing IsLibrary flag
Archived Files (7)
File Name
Version
Size
Uploader
Date
1.2.0
10kB
sirinsidiator
04/22/21 01:33 PM
1.1.3
5kB
sirinsidiator
03/02/20 01:26 PM
1.1.2
5kB
sirinsidiator
03/02/20 12:10 PM
1.1.1
6kB
sirinsidiator
02/25/20 01:55 PM
1.1.0
6kB
sirinsidiator
02/24/20 02:43 AM
1.0.1
5kB
sirinsidiator
06/01/19 05:15 AM
1.0.0
5kB
sirinsidiator
05/28/19 09:18 AM


Post A Reply Comment Options
Unread 03/22/24, 06:28 PM  
sirinsidiator
 
sirinsidiator's Avatar
AddOn Author - Click to view AddOns

Forum posts: 1567
File comments: 1120
Uploads: 41
Originally Posted by Jysoul
v1.2.1 release, change log references it as v1.2.0.
Not anymore. Thanks!
Report comment to moderator  
Reply With Quote
Unread 03/22/24, 06:12 PM  
Jysoul

Forum posts: 2
File comments: 20
Uploads: 0
v1.2.1 release, change log references it as v1.2.0.
Report comment to moderator  
Reply With Quote
Unread 10/29/22, 12:51 PM  
stifu

Forum posts: 0
File comments: 1
Uploads: 0
Option to block all chat output

Hi, would it be possible to add an option for the player to block all chat messages passed through this lib?

The reason why I am asking for this is as follows: I would like my UI to be as immersive as possible and seeing how there is no way to completely hide the chat window, I usually just let it fade into transparency. However, as you might guess, everytime one of my addon posts a new chat message, the chat window becomes visible again.
Report comment to moderator  
Reply With Quote
Unread 01/26/22, 03:26 PM  
ownedbynico
AddOn Author - Click to view AddOns

Forum posts: 9
File comments: 110
Uploads: 15
Re: Re: Version variable

Originally Posted by sirinsidiator
Originally Posted by ownedbynico
Hey, it would be nice if there was a variable that returns the version of the lib.
Im using it for custom links in Wizard's Wardrobe and people with a old version of this lib get UI errors (obviously). This way I could check if its 1.2.0 or newer and tell them to update.

Edit: Nvm, a simple way would be to check function RegisterCustomChatLink() exists. lul
You can also tell the game that you require a specific version of the library like so:
Code:
## DependsOn: LibChatMessage>=105
That way the game won't load your addon unless the dependency is loaded and at least of the specified AddOnVersion
Oh, interesting. How exactly is this formatted? I often give my local "beta versions" of the addon versions like "1.7-beta-4". And I dont really see how the game would interpret this.

Edit: I was once too fast typing. Just saw there are two different version "types". Version and AddOnVersion.

Thanks for your help!
Last edited by ownedbynico : 01/26/22 at 03:29 PM.
Report comment to moderator  
Reply With Quote
Unread 01/26/22, 03:17 PM  
sirinsidiator
 
sirinsidiator's Avatar
AddOn Author - Click to view AddOns

Forum posts: 1567
File comments: 1120
Uploads: 41
Re: Version variable

Originally Posted by ownedbynico
Hey, it would be nice if there was a variable that returns the version of the lib.
Im using it for custom links in Wizard's Wardrobe and people with a old version of this lib get UI errors (obviously). This way I could check if its 1.2.0 or newer and tell them to update.

Edit: Nvm, a simple way would be to check function RegisterCustomChatLink() exists. lul
You can also tell the game that you require a specific version of the library like so:
Code:
## DependsOn: LibChatMessage>=105
That way the game won't load your addon unless the dependency is loaded and at least of the specified AddOnVersion
Report comment to moderator  
Reply With Quote
Unread 01/26/22, 02:01 PM  
ownedbynico
AddOn Author - Click to view AddOns

Forum posts: 9
File comments: 110
Uploads: 15
Version variable

Hey, it would be nice if there was a variable that returns the version of the lib.
Im using it for custom links in Wizard's Wardrobe and people with a old version of this lib get UI errors (obviously). This way I could check if its 1.2.0 or newer and tell them to update.

Edit: Nvm, a simple way would be to check function RegisterCustomChatLink() exists. lul
Last edited by ownedbynico : 01/26/22 at 02:09 PM.
Report comment to moderator  
Reply With Quote
Unread 06/08/21, 09:43 AM  
sirinsidiator
 
sirinsidiator's Avatar
AddOn Author - Click to view AddOns

Forum posts: 1567
File comments: 1120
Uploads: 41
Re: Questions...

Originally Posted by Phinix
Can someone explain in a bit more detail why using d() or CHAT_SYSTEM:AddMessage() is bad practice? I am not clear on how this is actually a problem.
d() is a debug utility. Using debug utilities to do things that are not intended for debugging is generally a bad idea, as they are usually not made with the intention to be used for anything other than debugging. They can be buggy when used outside of their intended purpose, cause performance issued, etc.
In the specific case of printing messages to chat, it also means that when someone used d() to show the user a message in chat, it is no longer possible to separate them from actual debug messages done by other addons. For example DebugLogViewer takes all d() messages and instead of showing them in chat, shows them in the debug log, since they are supposed to be debug messages.

As for CHAT_SYSTEM:AddMessage(), that function was actually split up into two new function and only exists as a compatibility alias.
d() now uses CHAT_ROUTER:AddDebugMessage(messageText) and CHAT_SYSTEM:AddMessage() calls CHAT_ROUTER:AddSystemMessage(messageText) which is the actual way to print messages to chat without using LibChatMessage.
Report comment to moderator  
Reply With Quote
Unread 06/07/21, 10:11 PM  
Phinix
 
Phinix's Avatar
AddOn Author - Click to view AddOns

Forum posts: 186
File comments: 1779
Uploads: 32
Questions...

Can someone explain in a bit more detail why using d() or CHAT_SYSTEM:AddMessage() is bad practice? I am not clear on how this is actually a problem.
Report comment to moderator  
Reply With Quote
Unread 05/21/21, 01:29 PM  
yoderc

Forum posts: 1
File comments: 25
Uploads: 0
I have the same issue as Rengaru.

A little more info if it will help.

With Smart Cast v 1.3 (Minion updated March 13) and LibChatMessage 1.2.0 (Minion updated Apr 22) any ability/ultimate i try to cast that is a ranged target aoe ability:
1. doesn't fire
2. immediately breaks the map (nothing is clickable and no popups on cursor range over)
3. inventory right click menus pop up in upper left corner of the screen.

/reloadui fixes it.

I first noticed it on 4/23 and nothing else updated in the time frame.

I also rolled back to LibChatMessage 1.1.3 and everything works correctly.

I don't know if it's related, but something keeps randomly turning base game setting Quick Cast Ground Abilities to OFF.
Report comment to moderator  
Reply With Quote
Unread 05/19/21, 09:32 PM  
BioKem1

Forum posts: 0
File comments: 11
Uploads: 0
Originally Posted by Rengaru
Originally Posted by sirinsidiator
I just installed both of these addons and don't get any errors. Please make sure that you have installed everything correctly and report any problems you have to the respective comment sections. Also try to be more specific and include as much detail as you can when you report a problem. Don't assume that what happens on your end happens on the author's end too.
I should have been more specific, sorry.
While using the current version (1.2.0) of this library together with SmartCast it will lock up any ground targeted skill, I can still press the button but the skill will not fire.
In-game I'm currently using the previous version (1.1.3) of this library and SmartCast works as expected.
I just wanted to add that I have had the same experience as Rengaru and have rolled back to the earlier version.
Report comment to moderator  
Reply With Quote
Unread 05/14/21, 06:11 PM  
Rengaru
AddOn Author - Click to view AddOns

Forum posts: 0
File comments: 27
Uploads: 3
Originally Posted by sirinsidiator
I just installed both of these addons and don't get any errors. Please make sure that you have installed everything correctly and report any problems you have to the respective comment sections. Also try to be more specific and include as much detail as you can when you report a problem. Don't assume that what happens on your end happens on the author's end too.
I should have been more specific, sorry.
While using the current version (1.2.0) of this library together with SmartCast it will lock up any ground targeted skill, I can still press the button but the skill will not fire.
In-game I'm currently using the previous version (1.1.3) of this library and SmartCast works as expected.
Report comment to moderator  
Reply With Quote
Unread 05/14/21, 01:22 PM  
sirinsidiator
 
sirinsidiator's Avatar
AddOn Author - Click to view AddOns

Forum posts: 1567
File comments: 1120
Uploads: 41
I just installed both of these addons and don't get any errors. Please make sure that you have installed everything correctly and report any problems you have to the respective comment sections. Also try to be more specific and include as much detail as you can when you report a problem. Don't assume that what happens on your end happens on the author's end too.
Report comment to moderator  
Reply With Quote
Unread 05/14/21, 10:40 AM  
Rengaru
AddOn Author - Click to view AddOns

Forum posts: 0
File comments: 27
Uploads: 3
Also SmartCast (https://www.esoui.com/downloads/info...dtargeting.htm) no longer works if you install the latest version of this library.
Report comment to moderator  
Reply With Quote
Unread 05/13/21, 05:42 AM  
Blathnir

Forum posts: 0
File comments: 2
Uploads: 0
UI errors occur with the LibChatMessage addon when the Socerer Helper is used, there is only a constant UI error and the Scoerer Helper addon is no longer executed
Report comment to moderator  
Reply With Quote
Unread 11/30/20, 04:49 AM  
sirinsidiator
 
sirinsidiator's Avatar
AddOn Author - Click to view AddOns

Forum posts: 1567
File comments: 1120
Uploads: 41
Re: Re: Re: Per chat-proxy ability to always include a prefix?

Originally Posted by marlonbrando
Originally Posted by sirinsidiator
Originally Posted by marlonbrando
I may be missing something but I don't see any way to add a prefix to messages without configuring it globally, i.e., LibChatMessage:SetTagPrefixMode(...). I'd like to be able to control this only for my add-on via something like chat:SetTagprefixMode(...) .

Is this possible or is something like this already there and I've missed it?
The tag prefix mode is a user setting, as such it's not supposed to be controlled by addons aside of when they offer a ui for the library. There is currently no way for a user to select it per addon either.
Ok. I'll add it manually. Thanks.
Before you add them manually I want you to consider why this setting was added in the first place. In the past I got asked by users if they can somehow hide the tags in chat, because they explicitly do not want them. The library will still show them by default, so your addon tags are visible for most users, but for the handful that doesn't like them and knows how to disable them via the lib there is now a way to hide them. As such you really should not circumvent this setting and manually add your tags to the message.
Report comment to moderator  
Reply With Quote
Post A Reply



Category Jump:

Support AddOn Development!

You have just downloaded by the author . If you like this AddOn why not consider supporting the author? This author has set up a donation account. Donations ensure that authors can continue to develop useful tools for everyone.