Basically, any time you’d look up a value in the RAID_CLASS_COLORS table, check for the existence of a global CUSTOM_CLASS_COLORS table and — if it exists — get the value from it instead:

Old:

local color = RAID_CLASS_COLORS["SHAMAN"]

New:

local color = (CUSTOM_CLASS_COLORS or RAID_CLASS_COLORS)["SHAMAN"]

Callback usage

If your addon creates a local upvalue (variable) for RAID_CLASS_COLORS, or maintains its own table of class colors, you should register for the PLAYER_LOGIN event and, when it fires, redirect your upvalue to CUSTOM_CLASS_COLORS or update your table with the values from CUSTOM_CLASS_COLORS.

It is strongly recommended that you also register for a callback to be notified when class colors are changed by the user, and update your upvalue or table when the callback is fired:

RegisterCallback API

CUSTOM_CLASS_COLORS:RegisterCallback(method[, handler])

Registers a function to be called when values in CUSTOM_CLASS_COLORS are changed.

Arguments

• method — function or string
• handler — nil or table

Details

• If method is a function, that function will be called when class colors are changed, with no arguments.
• If method is a string, handler is a table, and handler[method] is a function, that function will be called when class colors are changed, with handler as its first and only argument.
• If the provided arguments do not identify a valid function, an error will be thrown.
• If the function is already registered, nothing will happen.

UnregisterCallback API

CUSTOM_CLASS_COLORS:UnegisterCallback(method[, handler])

Removes a function from the callback registry, so it will no longer be called when class colors are changed.

Arguments

• method — function or string
• handler — nil or table

Details

• If the provided arguments do not identify a valid function, nothing will happen.
• If the function is not registered, nothing will happen.

Caveats

You should not set the !ClassColors addon as a dependency for your addon, or check for the !ClassColors addon by name — eg. with IsAddOnLoaded or GetAddOnInfo — as a means of implementing support for custom class colors. There are two main reason for this:

1. The loading order of addons is not defined, and not all users are on systems which load files in alphabetical order, so you cannot guarantee that !ClassColors will be loaded before your addon, unless you clutter up your TOC by setting !ClassColors as an optional dependency for your addon.
2. CUSTOM_CLASS_COLORS is meant to be a community standard, not a single addon. Currently, there are no known alternate implementations, but you should not assume that the !ClassColors addon is the only way for your users to get a CUSTOM_CLASS_COLORS table.

Use the methods described above instead to ensure consistent support for users’ custom class colors.

Alternate implementations

CUSTOM_CLASS_COLORS is a proposed commnity standard defining a globally-accessible table of alternate class colors that can be freely modified without tainting parts of the Blizzard UI. Since it creates a new table, rather than modifying Blizzard’s RAID_CLASS_COLORS, addons must explictily include support for it.

The !ClassColors addon is only one possible implementation of this standard (though, it is currently the only one I know about). Any implementation must:

1. Create a global CUSTOM_CLASS_COLORS table with the same keys and structure as RAID_CLASS_COLORS
2. Define :RegisterCallback and :UnregisterCallback metamethods on the CUSTOM_CLASS_COLORS table

The callback registration methods must be defined using a metatable so that addons can freely iterate over the table using pairs() and get only the same keys and data structures they’d get from RAID_CLASS_COLORS without adding any special code to handle function or other non-standard values.

The following features are recommended, but can be left out without actually breaking anything:

• Provide a UI for changing color values
• Maintain custom color values between sessions
• Maintain a list of functions requesting callbacks, and call them when any color values are changed
• Check if another addon has already defined CUSTOM_CLASS_COLORS and, if so, avoid overwriting it
• Apply custom color values to the Blizzard UI

Implementations may also provide any number of other features, as long as they do not pollute the raw key/value structure of the CUSTOM_CLASS_COLORS table. The intent is that CUSTOM_CLASS_COLORS is a drop-in replacement for RAID_CLASS_COLORS.

If you’ve released an alternate implementation of CUSTOM_CLASS_COLORS, please send me a PM so I can add a link to it here!

Feedback

If you have any questions or comments about this documentation, send me a PM!