SharePoint Status Bar Access Via Client Side API

In this article we will explore the two new features provided in the SharePoint 2010 release by Microsoft. One is the Status Bar and other one is Notification Area. These both provide the facility to notify the user without distracting him/her.

With the release of SharePoint 2010, Microsoft made tremendous changes in the design and presentation layer of the SharePoint site. In SharePoint 2010, extensive use of AJAX makes a very good user experience. Many of the operations are performed asynchronously using AJAX. For example, when you edit a page and try to add a new web part to a particular web part zone, the list of web parts is loaded asynchronously. This enables the user to experience functionality like a simple desktop application. Same way, Microsoft added two new functionalities to UI of the web sites called Status Bar and Notification Area. In this article we will explore these two with working examples.

Status Bar

Status bar appears just right below the Ribbon tag. See the below image. In SharePoint 2007, alert messages were used to notify the user for some pending operations or missing operations for page editing and others. For example, in publishing sites, if you have edited a page and without saving it or checking in it, if you try to navigate to other page, the alert message will be displayed to notify you that you have not saved the page. But in SharePoint 2010, this alerting system is enhanced and now these types of messages are displayed in the status bar. So, this makes a better user experience. So, we can say that status bar is used to provide the user contextual information without being distracting. The below image gives you the idea what the status bar is in SharePoint 2010 site. Notice the text with yellow background on the page. That is status bar indicating that “This page contains content or formatting that is not valid. You can….”



Status bar is generally used to show some permanent information or message to the user. Microsoft allowed the developers to provide their messages in status bar, by making the status bar customizable. So, a developer can add or append his messages in the status bar whatever he likes or feel relevant to show.

Customizing the Status Bar

The status bar can be extended or customized through both client side and/or server side code. Generally and we can say mostly the messages displayed in status bar are consist of HTML text. So, with this type of HTML message, developer can add images and links to other pages as well as he can provide styles to make good look and feel of message. Also, status bar is provided with four different colors, which are used based on the importance or priority of the message to be displayed. They are Red, Green, Blue and Yellow. To customize the status bar using client-side API, you have to use the SP.UI.Status class. This class contains only five methods which provide the total interaction with status bar. The file SP.debug.js provides detailed information about each and every method contained by SP.UI.Status class. To work with status bar from server side, you need to use the SPPageStatusSetter class. This class is part of the Microsoft.SharePoint.WebControls namespace. This SPPageStatusSetter class provides simpler API that you can call one method named AddStatus. The SPPageStatusControl class can also be used to interact with the status bar from server side. In this article we will explore only client side API and see how to interact with status bar using javascript. Before that we will get some basic information about each and every method of the client side SP.UI.Status class.

addStatus: This method allows you to provide a title, the HTML message to be displayed on status bar, a Boolean value which specifies whether the message will be displayed at the beginning of the status bar or not. This method returns the status ID for the new status created and you can use this ID with other methods.

appendStatus: This method allows you to append status message to an existing status message. You need to provide the status ID of the existing status and HTML message that you want to append as parameter to this method.

updateStatus: This method allows you to update an existing status message. You need to provide the existing status ID which indicates the status to be updated and HTML message for the new status message as parameters to this method.

setStatusPriColor: This method allows you to set the background color of the status bar to give user the visual indication of the status message. For example, for bad message you can set its background as red and for good one you can set it to green one. For this you need to provide the status ID of the status you want to change the color and the color value as parameters to this method. The possible color values are: red, blue, green or yellow.

removeStatus: This method removes the status message specified by the status ID provided as parameter to this method.

removeAllStatus: This method removes all the status messages from the status bar. You can also provide a Boolean value which specifies that if you want the status bar to be displayed or to hide after removing all messages from status bar. Most of the time, this value is true.

Now we will see how to display our message in the status bar using client side API for status bar. For this first of all create a SharePoint 2010 site if you have not one. If you have one, then navigate to it.

Ok. Before adding Content Editor Web part to the page, we will write some javascript code to add a status bar to the page. See the below listing:

<script type="text/javascript">
            var sid;
            function CreateStatus()
            {
                return SP.UI.Status.addStatus(SP.Utilities.HttpUtility.htmlEncode("My first Status Bar"),
        "<HTML><i>Hello, this is my first status message</i></HTML>",true);
             }
        </script>
        <input onclick="sid=CreateStatus();alert(sid);" type="button" value="Create Status" /><br />

As you can see in the above code, we have used SP.UI.Status.addStatus method to add our status message to the status bar. Save this text to a simple text file, for example with name statusbar.txt.

Now, we will upload this text file to our SharePoint Site’s one of the document libraries. So, navigate to your document library if you have or create one and then navigate to it. Next, upload this statusbar.txt file to that document library. See the below image.



Now, on the Home page of the site add a new Content Editor Web part. To add a new Content Editor Web part, select the Page tab from the Ribbon bar and then click on “Edit Page” button. This will get your page in edit mode.



Next, for the Left web part zone, click “Add a Web Part” link. When you click this link, the list of web parts for your SharePoint site is displayed right below the Ribbon bar.

From the Categories list select “Media and Content” and after that from the Web Parts list select “Content Editor” web part. After that click “Add” button to add that selected web part to our web part zone.



Now, from the Web Part menu, select “Edit Web Part” option to open the Web Part task pane for the Content Editor Web part. Now, in the Content Link text box provide the URL for our statusbar.txt file which we uploaded earlier. For your reference I have to provide http://192.168.92.129/Shared%20Documents/statusbar.txt.

After providing URL, click OK to close the web part task pane. You can see that your Content Editor Web part has now a button with text “Create Status”.



Now, when you click on that “Create Status” button, a status bar will be displayed with your provide message in your java script code and the alert message saying the status ID will be displayed. See below image.



So, this way we can work with client side APIs, provided by Microsoft, for status bar in SharePoint sites. Now, we will explore remaining methods for SP.UI.Status class.

For this, open your statusbar.txt file and write the code listed below:

<script type="text/javascript">
            var sid;
            var color = "";
            function AppendStatusMethod() {
                SP.UI.Status.appendStatus(sid, "Appended:", "<HTML><i>My Status append to " + sid + " using appendStatus</i></HTML>");
            }
            function UpdateStatus() {
                SP.UI.Status.updateStatus(sid, "Update: HTML updated for " + sid + " using updateStatus");
            }
            function RemoveStatus() {
                SP.UI.Status.removeStatus(sid);
            }
            function RemoveAllStatus() {
                SP.UI.Status.removeAllStatus(true);
            }
            function SetStatusColor() {
                if (color == "")
                    color = "red";
                else if (color == "red")
                    color = "green";
                else if (color == "green")
                    color = "yellow";
                else if (color == "yellow")
                    color = "blue";
                else if (color == "blue")
                    color = "red"
                SP.UI.Status.setStatusPriColor(sid, color);
            }
            function AppendStatus() {
                SP.UI.Status.addStatus("Appended:", "<HTML><i>My Status Message Append using at Begining</i></HTML>", false);
            }
            function CreateStatus() {
                return SP.UI.Status.addStatus(SP.Utilities.HttpUtility.htmlEncode("My first Status Bar"), "<HTML><i> Hello, this is my first status message</i></HTML>", true);
             }</script>

        <input onclick="sid=CreateStatus();alert(sid);" type="button" value="Create Status" /><br />
        <input onclick="AppendStatus()" type="button" value="Append Status using atBegining" /><br />
        <input onclick="AppendStatusMethod()" type="button" value="Append Status using appendStatus" /><br />
        <input onclick="UpdateStatus()" type="button" value="Update Status using updateStatus" /><br />
        <input onclick="SetStatusColor()" type="button" value="Cycle Colors" /><br />
        <input onclick="RemoveStatus()" type="button" value="Remove Single Status" /><br />
        <input onclick="RemoveAllStatus()" type="button" value="Remove all status" /><br />

Save your file and upload it to the same document library to overwrite the existing one.

Now, when you refresh your home page you will see some more button. See the below image.



Now, check the functionality of each button and see the effect on status bar. This is left to you....

Notification Area

We have seen that Status Bar is used to provide some permanent information or message to the user without distracting him. Same way Notification Area is used to display some sort and temporary messages to the user. As, SharePoint 2010 sites now use more AJAX, to notify the user that some asynchronous process is going on, this Notification Area is used. Please see the below image, where you can see that, the “Deleting…” message is displayed in the Notification Area to the right side of the page. This indicates that the selected document is being deleted.



Notification Area is useful in your custom development when you are performing some asynchronous operation and you want to let the user know that your process is running and wait till end.

Same like Status Bar, Microsoft provided client side API for notification. This notification API is limited to only create and remove functionalities. The class SP.UI.Notify works with notifications from client side. Before going to see working for this we will get some information about the methods provided by SP.UI.Notify class.

addNotification: This method allows you to provide the HTML message to be displayed. This method also takes as parameter the Boolean value which decides that the notification is sticky or not. Means if false value is provided, then the notification disappears after 5 seconds. This also takes tooltip text and name of the function to handler the onclick event, when the notification area is clicked by user. The last two parameters are option one. This addNotification method returns the ID of the notification which is used to remove that notification using removeNotification method, which is described below.

removeNotification: This method removes the notification based on the notification ID provided as parameter to it.

Now, to see working example, write the below code and save it to as notification.txt.

<script type="text/javascript">
            var notifyId;
            function CreateNotification() {
                notifyId = SP.UI.Notify.addNotification("My HTML Notification", true, "My Tooltip", "Hello world");
                alert("Notification id: " + notifyId);
            }

            function RemoveNotification() {
                 SP.UI.Notify.removeNotification(notifyId);
            }
        </script>
        <input onclick="CreateNotification()" type="button" value="Create Notification"/><br/>
        <input onclick="RemoveNotification()" type="button" value="Remove Notification" />

Now, again upload this notification.txt file to your document library. Now again on the home page add one more Content Editor Web Part and provide the URL of your notification.txt file. You resulting page will look like this.



When you click on “Create Notification” button, it will first alert you with the notification id and then displays the notification with your provided message (See above image). As for example, we have made the sticky notification, so to remove that, click on “Remove Notification” button.

So, this way we can use Status Bar and Notification Area in our custom development to give better user experience and can provide some robust application.

Hope you have enjoyed the article. You can download the, statusbar.txt and notification.txt, files from here.

Also you can download the site template, that I've worked for this article, from here.

Feel free to write me your review.

By Jatin Prajapati   Popularity  (2936 Views)
Picture
Biography - Jatin Prajapati
I think, most of the people are interested only in answers so no Biography provided... Want know more just write me at jatin.prajapati.er@gmail.com