Among the useful new features in SharePoint 2010 are the enhancements available with the addition of the Status Bar, helping to provide a more productive experience for users. This seemingly small feature can be used in extremely creative and interesting ways to enhance your own custom SharePoint applications. In this post, we will take a look a how to work with messages on the Status Bar in SharePoint 2010.

Challenge:

How do I show, modify, and remove a message on the Status Bar in SharePoint 2010?

Solution:

What is the Status Bar Message?

The Status Bar is extensible through both client- or server-side code, and is used to display a persistent message to users. The Status Bar message is rendered in HTML, so it can be styled and may contain links and images. In addition, the bar can have four different preset colors, in accordance with the importance of the message.

Working with the SharePoint 2010 Status Bar is very easy. Its functionality is exposed through the SP.UI.Status namespace (defined in the 14TEMPLATELAYOUTSSP.js file) in the SharePoint 2010 JavaScript API.

How to use the Status Bar

In order to display a message in the SharePoint 2010 Status Bar, you use the SP.UI.Status.addStatus function. This function takes three parameters: the title of the status, the status message itself, and a Boolean value which determines whether the status message should be displayed at first or not.  For example:

var statusBarId = SP.UI.Status.addStatus('My Status:', ‘Do You Bamboo?’, true);

Results in the following Status Bar message:

The addStatus function returns the ID of the status message, which can be used to modify the message, change its color, etc.

About Priority

Status Bar messages are meant to provide feedback to users. To support this, SharePoint allows you to set four visual priorities for the message using different colored feedback. From the most to the least important, the available colors are: red, yellow, green, and blue.

You can set the priority of a status message using the SP.UI.Status.setStatusPriColor function. This function takes two parameters: the ID of the status message and the color that you want to set:

SP.UI.Status.setStatusPriColor = function(statusBarId, color) { 

}

For example:

SP.UI.Status.setStatusPriColor(statusBarId, 'red');

Results in changing the color of the status message to red:

Update Status Message

Status messages should be displayed only when necessary and meaningful. As soon as the status of the application changes, you should modify the status message or hide it.

To modify the value of a status message, you use the SP.UI.Status.updateStatus function. It takes two parameters: the ID of the message and the new message:

SP.UI.Status.updateStatus = function(statusBarId, newMessage) {

}

Remove Status Message

Whenever the status of the application changes and the message that has been displayed doesn’t apply anymore, you can hide the message using the SP.UI.Status.removeStatus function. The only parameter that it takes is the ID of the status message to be hidden:

SP.UI.Status.removeStatus = function(statusBarId){

}

Notes:

• See the attachment for the source code and script of this example.

See Also:

• Status and Notifications [MSDN]