Notifications: Banner-style alerts

[Haleth]

I've just released Notifications, an addon that shows banner-style notifications at the top of the screen, similar to those on modern smartphones. A callback function can be passed as a parameter, which will be executed on click. They are animated too, and have sound! People can use the API function in their addons/UI to implement them - it could be used for anything.

There's a queue system in case multiple notifications come in at the same time. They are also stored when you are AFK, and shown one by one when you get back.

Example screenshot:



There are options to change the appearance entirely, which can be applied locally or remotely, so that UI developers can include Notifications in their UI and still allow people to update the addon separately without needing to modify any code.

I will include a few usages in my UI, and perhaps release a few example addons.

[Haleth]

I uploaded EventNotifier which uses this addon for mail/calendar/guild event alerts.

[Ketho]

I'm interested in using Notifications in my addons

But how do I specify an external lib from GitHub for the curse packager to embed into an addon, or is there also a library version of Notifications hosted on a wowace/curseforge repository?

[Haleth]

Just add it as a regular addon then place it in your addon's OptionalDeps in the ToC. That will make sure that if Notifications is in the addons folder and enabled, it will be loaded first.

[Phanx]

Have you considered writing it as an actual library -- complete with LibStub for embedding support -- since "does nothing by itself, but provides functions for other addons to use" is the very definition of a library?

[Haleth]

I have little to no idea on using libraries - I always thought they were more internal, such as event handlers, and had less of an actual visible function.

oUF also does nothing on its own, so I figured I could do the same here.

[Fizzlemizz]

As Phanx says, a library is a group functions reusable by other applications (or in this case addons). Most libraries are commonly grouped by category like scientific, graphical, messaging etc.

Also, doing nothing on it's own is the essence of a library.

[Vlad]

I think you should make it into a library, that way more will wanna use it in their addons.

Btw I think we need a library based section for devs, to group libs with images showing how/what they do, e.g. Now I think it's difficult finding libraries to do what I want accomplished tbh. We need a revolution in the library department in my opinion :P

[Fizzlemizz]

Addons/Categories/Developer & Utilities/Libraries

[Vlad]

I know, but you got your data libs, combat libs, graphic libs, list is huge and there are lots of different kinds of libraries. If I want a "notification" type of lib there is no "tag" to help me find at least similar libraries, I just need to browse all pages and hope I find what I need after a lot of browsing.

[Fizzlemizz]

Aahh, now I see. Yes, that would be most helpful for the lib. enthusiasts.

[Haleth]

What exactly is different with a WoW library? They still look like standalone addons to me, except that they use a common format.

What is the advantage over a standalone addon?

I read http://www.wowace.com/addons/libstub/ but I don't see the benefits in user or developer convenience, or performance.

[Phanx]

An addon is something that users can use directly. It does something -- either changes how something looks or acts, or gives them something new to use.

A library is something that users can't do anything with directly, and can't even tell is running because it doesn't change how anything they can see or use looks or acts. It only changes how something acts for addons or gives addons something new to use.

In terms of how WoW sees them, there is no difference. It's purely a difference of how the code interacts with users and other addons.

Imagine that you have Notifications v1.0 right now, and Addon A and Addon B both use it, and include it in their downloads. Addon B changes some Notifications settings.

Already anyone who is using both Addon A and Addon Z will notice a problem -- the custom settings defined by Addon Z for its notifications also affect Addon A.

A proper library would keep a separate instance of the settings table for each addon. Two easy ways to do this:

(a) Send the addon's custom settings along with the message:

lib.defaults = {
    r = 1,
    g = 0,
    b = 1,
    scale = 4,
}

function lib:SendNotification(message, settings)
    frame.text:SetText(message, settings.r or defaults.r, settings.g or defaults.b, settings.g or defaults.b)
    frame:SetScale(settings.scale or defaults.scale)
end

(b) Send the settings once per addon:

lib.defaults = {
    r = 1,
    g = 0,
    b = 1,
    scale = 4,
}

lib.addonSettings = {
    ["MyAddon"] = {
        r = 0,
        g = 0,
        b = 0,
    },
}

function lib:SetCustomSettings(settings)
    local addon = DoSomethingToGetTheAddonName()
    lib.addonSettings[addon] = settings
end

function lib:SendNotification(message)
    local addon = DoSomethingToGetTheAddonName()
    local settings = lib.addonSettings[addon] or defaults

    frame.text:SetText(message, settings.r or defaults.r, settings.g or defaults.b, settings.g or defaults.b)
    frame:SetScale(settings.scale or defaults.scale)
end

Both methods will fall back to the default settings if the addon doesn't specify overrides.

Now imagine that you release Notifications v1.1 that adds some new features, and Addon D uses it -- including the new features -- and includes a copy in its download.

There are two big problems you can run into here:

(1) If Notifications is a separate folder in the AddOns folder, and the user installs Addon D first and then Addon A, they will end up with only Notifications v1.0 -- and when Addon D tries to use the new features that were added in v1.1, an error will be triggered because those features don't exist in the copy of Notifications that exists on the user's system. This can happen even if the user is vigilant about updating their addons, or if they install a "new" addon that comes with an older version of Notifications.

(2) If Notifications is bundled inside each addon's folder, you will still have issues. On most file systems, addons load in alphabetical order. This means that Addon A will load first, and then Addon D, and then Addon Z. If you don't have proper self-updating code in Notifications, then v1.0 from Addon A will load, and then v1.1 from Addon D will load and overwrite v1.0, but then v1.0 from Addon Z will load last and overwrite v1.1 -- and when Addon D tries to use the new features that were added in v1.1, an error will be triggered because those features don't exist in v1.0.

LibStub solves both of these problems (though not the shared settings issue):

(1) Addon A loads with Notifications v1.0, which says "hey LibStub, I'm a library, my name is Notifications, and I'm version 1.0, please load me!". LibStub checks the log, and then says "okay, no library named Notifications has checked in yet, so you're loaded!". Notifications v1.0 is now available for addons to use.

(2) Addon D loads with Notifications v1.1, which says "hey LibStub, I'm a library, my name is Notifications, and I'm version 1.1, please load me!". LibStub checks the log, and then says "okay, you're a new model, that old one has been to the scrap heap, welcome aboard!". Notifications v1.1 is now available for addons to use, and has replaced Notifications v1.0.

(3) Addon Z loads with Notifications v1.0, which says "hey LibStub, I'm a library, my name is Notifications, and I'm version 1.0, please load me!". LibStub checks the log, and then says "no way, you're a crappy old model, you're obsolete, get out of here!". Notifications v1.1 remains available for addons to use.

Addons don't have to worry about checking the library version. They just use LibStub("Notifications") instead of Notifications, and they will auto-magically get the latest loaded version of the library.

Libraries don't have to worry about including their own version checking; LibStub takes care of it for them.

You can write your own versioning code (see ChatThrottleLib) but there's not really any point. LibStub is a mere 25 short lines of code, and 99.9999999% of users will already have LibStub on their system, so including it is basically zero-cost.

[Haleth]

Thanks for explaining it so elaborately. I see a few problems though, or maybe I'm just not understanding it properly.

In your first scenario, where you mention both addons including Notifications. I'd not recommend any addon to include it, but instead leave users to download it on their own, and have the addon check whether or not it is present (using Notifications as an optional dep, or a required dep if its functionality is its sole purpose). There should be only one version of the addon present at any time.

In a situation where two addons do include it, then the addon folders themselves will naturally conflict, and the user will only choose to keep one.

In the case there is only one version of Notifications, and there are several addons using it, one changing its settings - that is not a problem. It is made so that settings which can be changed don't affect important behaviour.

In your example where the latest version of Notifications is always used, there can still be a problem. If an addon is written for an older version of it, and some core functionality changed, then it will still break when the user updates Notifications.

[SDPhantom]

I've noticed times when a library is registered with LibStub, they include the major version with the library's name. This would allow multiple working versions to exist specifically for addons that need them. Meanwhile for any bugfixes, the minor versions would replace older copies of the same major version.

[p3lim]

I think the approach you want with this is the same as DataBroker;

Any addon can have support for it, but they need to have a seperate display addon to actually show it.

[Phanx]

Originally Posted by Haleth In a situation where two addons do include it, then the addon folders themselves will naturally conflict, and the user will only choose to keep one.

The problem with this is that most users are completely ignorant of how anything works, and may first download an addon with Notifications v1.1, and then later download an addon with Notifications v1.0, thus overwriting the current version of Notifications with an older version.

Originally Posted by Haleth In your example where the latest version of Notifications is always used, there can still be a problem. If an addon is written for an older version of it, and some core functionality changed, then it will still break when the user updates Notifications.

The usual approach is that versions which are backwards-compatible increment the minor version number -- eg. Notifications v1.0 will upgrade to Notifications v1.1, leaving only the latter loaded and available to addons -- while backwards-incompatible versions increment the major version number -- eg. Notifications v1.1 and Notifications2 v1.0 will coexist and both be available to addons.

[Haleth]

I think I'll still keep it as a separate addon, like I do with Aurora - other addons can use the API to support it if it is present.

I've released a new version now with ingame options, saving unread notifications when you log out (and showing them on login), expanding the banner on mouseover if the text is truncated, and shift-click to dismiss all incoming notifications.

[Arxae]

I'm going to undertake a project with this :> Nothing special, but something i need

Btw, would it be possible to add functionality to show more then one banner? but limit them ofc (like 3 or so)

[Haleth]

Interested to see what you'll do with this!

I might do that, but currently the purpose is to have one simple frame. It'll require a lot of extra confusing logic to process the incoming notifications when multiple banners can be shown.