Retrieving, Archiving, and Disposing Messages with Anguilla’s MessageCenter

Inspired by yet another question on StackExchange, I’ve decided to do a follow up on a previous post on using MessageCenter. While in the previous post we focused on the creation and registration of new messages and notifications, today we are going to discuss the retrieval, archiving, and disposing (removing) of messages within the message center. Before we continue, you should know that archiving a message in Anguilla means that is shows up as dark grey (ones that you’ve read) in the list of messages, while disposing means that it doesn’t show up in the list at all.

Retrieving

You can get an Array of all the messages using the getMessages() method of MessageCenter.

$messages.getMessages().forEach(function (message) {
    // do cool things with each message
});

The getMessages method does return ALL messages, including those that are inactive (archived) or disposed. If instead you want to get only the active messages, you could use the getActiveMessages() method.

$messages.getActiveMessages().forEach(function (message) {
    // do cool things with your active messages
});

But what if you wanted to get a list of all disposed messages… or a list of all archived messages? Although we’ll talk about how to dispose and archive individual messages later in the article, one thing to understand is that when a message gets archived, the message.properties.inactive property gets set to true, and when a message gets disposed, the message.properties.disposed property gets set to true. Knowing this, we can now filter our results based on those properties:

$messages.getMessages().forEach(function (message) {
    if (!message.properties.disposed) {
        console.log("This message has not been disposed yet!");
    }
    if (!message.properties.inactive) {
        console.log("This message has not been archived yet!");
    }
    if (!message.isActive()) {
        console.log("The isActive method can also be used to check the .properties.inactive property!  There is no isDiposed one though!");
    }
});

You can even filter on other things, like the type of messages or dates!

$messages.getMessages().forEach(function (message) {
    if (!message.properties.disposed && message.isActive()) {
        if (message.getClassName() === "error") {
            console.log("We have an error message that was given on " + message.getDate() + "!");
        }
    }
});

Archiving

When a message is archived, it shows up as gray in the message center. A message gets archived when you acknowledge it (clicking the “close” button), automatically (like with progress messages), or when you programatically archive it. You can do this with a message’s doArchive() method. The following snippet will archive any active messages that are out there:

$messages.getActiveMessages().forEach(function (message) {
    message.doArchive();
});

Disposing

Disposing of a message makes it so that it doesn’t show up in the GUI list at all. Besides marking the message.properties.disposed property as true, it also seems to clean up some of the other properties and data that existed on the message. So this means that even though the message is still in the list of messages after being disposed, there’s really no useful data on it except for that disposed property. You can easily dispose of a message by calling its dispose() method.

$messages.getActiveMessages().forEach(function (message) {
    message.doArchive();
    message.dispose();
});

You’ll notice that in the above example we are calling doArchive() first. This is VERY important to do, because if you dispose of an active method without first archiving it, the message will remain counted as “unread” in the message center’s counter. This will leave our users in a confused state as they are being notified that they have new messages, but there is nothing in this list.

Show/Hide Archived Messages

You’ve probably noticed the checkbox in your Message Center that allows you to “Show Archived Messages”. Unchecking this box will hide any archived messages in the list. The anguilla API also allows you to view and manipulate this setting.

if ($messages.getIsShowArchivedMessages()) {
   // the checkbox is checked!
   $messages.setIsShowArchivedMessages(false); // but not anymore!
}

And with that I leave you with more power and knowledge to manipulate and bend the Message Center to your will!

Anguilla Framework: Adding Messages With MessageCenter and $messages

The Anguilla Framework comes with a built in message center that allows you to display different types of messages and notifications to the user. You’ve probably seen these messages already – they appear at the top of the window when you do almost any action in Tridion. They can even appear as a modal, display a question that requests a user response, or display a progress message that lets the user know when a certain action is done. When building your custom GUI Extensions, instead of rolling your own status or update notification system, you can easily take advantage of the one that’s already in place (and make your extension feel like its an actual part of Tridion). Messages added with MessageCenter are even archived, so your users can go back and view them if needed (by clicking the flag like symbol in the upper left of the screen). In this post, we’ll cover how to add notifications, warnings, errors, questions, goals and progresses.

Notifications

Notifications get displayed with the “i” icon (as with the image at the top of this post). You can use these for simple updates or alerts. Notifications will disappear from the upper window after around ten seconds or so.

$messages.registerNotification(title, description, local, modal)

title – The title of the notification. This is the message that gets displayed when shown at the top of the screen.
description – (optional) A better description of the notification. Can be seen when user double clicks the message to get further details.
local – (optional) You’ve probably noticed that most of the messages get displayed across all of your open Tridion windows. Setting ‘local’ to true will only display your message at the top of the window you are working with. Note that it still goes to the MessageCenter, so you can still view it from the other windows via the Message Center icon.
modal – (optional) True or false, if true your notification will get displayed as a modal popup.

Goals


Goals are like notifications, except they are displayed with a check mark icon (and a different colored background!).

$messages.registerGoal(title, description, local, modal)

Warnings


Warnings are also similar to notifications as well and are displayed with a warning icon. Unlike Notifications and Goals, the warning message will not disappear on its own (you’ll have to click the little ‘x’).

$messages.registerWarning(title, description, local, modal)

Errors


Errors, like Warnings, do not disappear on their own, and they are displayed with an error icon. They allow for an extra area for specifics of your error.
Error message with Details.

$messages.registerError(title, description, details, local, modal)

details – Details are for displaying the details of your error. For example, this area would be a lovely place to display the stack trace of an error.

Questions

Questions allow you to supply a simple “yes/no” type of question to the user. You can add events to your message to perform an action upon confirming or canceling. Messages are great to use with the modal feature.

Question with modal option turned on

$messages.registerQuestion(title, description, local, modal, buttonLabels)

buttonLabels – (optional) Additional settings to control the labels of the button, which by default is “Yes” and “No”. { cancel: "Cancel Label", confirm: "Confirm Label" }

Question Code Samples:

var question = $messages.registerQuestion("Do you love GUI Extensions?", null, true, true, { cancel: "Hate Them!", confirm: "Love Them!" });
question.addEventListener("cancel", function (event) {
    $messages.registerNotification("Haters want to hate!");
});
question.addEventListener("confirm", function (event) {
    $messages.registerNotification("TridionLove++");
});

Progress


Progress messages let you display the progress of an action, for example, “Saving…”. Like Questions, they are a bit more interactive than just displaying a message to the user. You can set messages that will get displayed upon success of your action using setOnSuccessMessage(title, description). You can even have a cancel button appear and allow the user to cancel your action, and set a message to display upon cancellation using setOnCancelMessage(title, description). Note that the Success and Cancel messages will be displayed as Goals.

$messages.registerProgress(title, description, canCancel, local, modal)

canCancel – (Optional) True or false, when set to true will display a cancel button

Progress Code Samples:

var progress = $messages.registerProgress("Waiting...", null, true);

progress.setOnCancelMessage("You've canceled!");
progress.setOnSuccessMessage("Done waiting!!!");

progress.addEventListener("cancel", function (event) { 
    console.log("Do stuff when canceled..."); 
});

// ... somewhere later in your code, in a callback or some form of dark arts... 
progress.finish({ success: true }); // Will remove progress message and display your onSuccess message.
progress.finish(); // Will remove progress message, but not display your onSuccess message.

// You can even cancel programatically by... clicking the cancel button or calling this method directly will display the cancel message.
progress.cancel();

You can also set it to automatically call the .finish() method upon the event of another item via the .addFinishEvent(itemID, event, isSuccessEvent) method. The follow example will show a loading status, and will automatically fire our success message upon completion of our item being loaded.

var item = $tcm.getItem("tcm:1-234"),
    progress = $messages.registerProgress("Loading our item...");

progress.setOnSuccessMessage("Item Finished Loading!");
progress.addFinishEvent("tcm:1-234", "load", true);

item.load();

Playing around in a console…

If you want a quick way to experiment with MessageCenter, feel free to try the $messages api inside of the console window!

Update 08/01/2014

I’ve posted a follow up on this article on retrieving, archiving, and disposing of messages. You can find it here!