SPServices Stories #5 – Gritter and Sharepoint: Integrate Nifty Notifications in Your Intranet!

Introduction

This SPServices Story comes to use from Rick El-Darwish (@RtfulDodg3r) in Geneva, Switzerland. For those of you who aren’t familiar with it, Gritter is a Growl-like notification jQuery plugin. That’s a mouthful, but try the links and you’ll quickly get the picture. If you’re an OS X user, then you’ll recognize the capability right away.

Sure, SharePoint has a notification scheme built into it – Showing transient messages using the SharePoint 2010 Notification Area – SharePoint 2010 UI tip #2 (thanks, as always, @waldekm) – and there is at least one Codeplex project – SPNotifications – that provides similar functionality. However, the built-in notifications are limited in functionality and the SPNotifications requires server-side code. The script-based approach has a much smaller footprint and the content can easily be maintained by an end user. (Getting developers out of the mix with content ought to always be the goal.) Also, by using open source jQuery-based alternatives, you always have the option to expand the functionality to meet your own needs.

By using SPServices and Gritter together, Rick was able to create very user-friendly notifications on SharePoint pages which were driven by list-based content. Rick starts out with a simple example and shows you how to set up the list-driven approach. With a little extrapolation, I’m sure you will be able to see quite a few additional uses for this approach in your own environments.

You can see Rick’s original post on his blog, Forensic Aspirations, Inferred Logic: Rick’s tale of FAIL.

Gritter and Sharepoint: Integrate Nifty Notifications in Your Intranet!

I’m working with a client on building up a project management tool in SharePoint; one thing that’s really piqued their interest is the concept of getting short flashes of information when their staff logs into the landing page. I think it’s a lovely idea, and I’m intend on giving them this functionality – but how, you might ask? There doesn’t seem to be any SharePoint feature for doing that!

We tend to forget that SharePoint is, above all, a web-based solution. This means that, with a little ingenuity (and sometimes a lot of sweat and blood), you can integrate some of the latest, coolest web features into your existing SharePoint. Fortunately, notifications are not too complicated. In this short article, we’re going to walk through creating very cool notifications using Gritter, a jQuery-based “plugin”, with Sharepoint.

Step One: Create a Sandbox

This may be as simple as creating a new page in your Site Pages repository. I seriously recommend implementing a proof-of-concept rather than work on your production page… If you’re not familiar with these libraries, the last place you want to test things out is on your production work, as easy as these implementations may seem.

Apart from your page, your sandbox will need a few extra files. These you can either place in the Site Assets repository of your PoC portal, or in the Site Assets repo of your root. The latter has the benefit of being accessible to your entire audience (or at least I assume so, it will depend on your permissions). The files that you need are the latest minified version of jQuery, the latest version of Gritter, and the latest version of SPServices (double-check these pages for compatibility issues, of course – if Gritter or SPServices tell you that they won’t work with certain versions of jQuery, don’t use those versions…)

When downloading Gritter, you’ll notice that it is a zip file that has several folders and files. I recommend that you keep those in one single place in your Site Assets. I find it’s easiest to use SharePoint Designer to do that.

Step Two: Add Your jQuery References

Now that you have a sandbox, you can start working with it. In case you’re wondering, this section is assuming that you’re working with SharePoint Designer (SPD) to do your work.

Open your sandbox page in SPD, editing it in Advanced Mode. Locate the PlaceHolderMain placeholder and add the references to your script files:

<!– Inserted by Rick – references to jQuery scripts –>
<!– These are the references to jQuery and SPServices. –>
<script type="text/javascript" src="../SiteAssets/jquery-1.8.3.min.js"></script>
<script type="text/javascript" src="../SiteAssets/jquery.SPServices-0.7.2.min.js"></script>
<!– These are the references to Gritter: –>
<link rel="stylesheet" type="text/css" href="../SiteAssets/gritter/css/jquery.gritter.css" />
<script type="text/javascript" src="../SiteAssets/gritter/js/jquery.gritter.min.js"></script>
<!– End Rick insertions. –>

You can test that the libraries loaded correctly by firing up Chrome, navigating to your PoC page, and opening your Console (F12). In the Console, type the following:

$
$(document).SPServices
$.gritter

If any of these return ‘undefined’, review your references, make sure the files are uploaded in the correct location.

Step Three: Setting up your notifications!

OK, now we know that all the necessary libraries are loaded. Time to develop notifications. Always develop incrementally, testing your code one chunk at a time. To that effect, here’s code that you should insert after the above script blocks:

<!– Here’s a test notification –>
<script type="text/javascript">
$(document).ready( function() {
  $.gritter.add({
    title: "This is a test notification",
    text: "This will fade after some time"
  });
});
</script>

If that works, you know that Gritter is functional for static content! Now it’s time to pull the real notifications from a list — this is where SPServices comes in. Before we proceed, we need something to pull information from: create a custom list with a single title for your PoC, “Latest Activities” for instance. Then, you will call the GetListItems function using SPServices.

The following code replaces your test notification:

<!– Code for notifications –>
<script type="text/javascript">

//This function throws up the notification:
function notify(curTitle, curContent) {
  $.gritter.add({
    title: curTitle,
    text: curContent
  });
}

//This retrieves the latest item of your Latest Activities.
function getLastActivity() {
  $(document).SPServices({
    operation: "GetListItems",
    async: false,
    listName: "Latest Activities",
    CAMLRowLimit: 1,
    CAMLQuery: "<Query><OrderBy><FieldRef Name=’Created’ Ascending=’False’ /></OrderBy></Query>",
    CAMLViewFields: "<ViewFields><FieldRef Name=’Title’ /></ViewFields>",
    completefunc: function(xData, Status) {
      $(xData.responseXML).SPFilterNode("z:row").each(function() {
        notify(‘For your information…’, $(this).attr("ows_Title"));
      });
    }
  });
}

//On document load, throw up the notification:
$(document).ready( function() {
  getLastActivity();
});
</script>

Et voilà — Gritter and SharePoint notifications in a nutshell! Your page will load and, once loaded, will call the getLastActivity function. getLastActivity pulls the latest item from the Latest Activities list (we use the CAMLQuery parameter to order by create date, and the CAMLRowLimit parameter to only return one parameter), and use a callback function to call the notify() function. The notify function is what is responsible for rendering the Gritter notification.

Happy notifying!

Rick.