SPServices Stories #15: Custom Client-side Calendar Query for Office 365 SharePoint Site Using SPServices jQuery Library

Introduction

My friend and fellow MVP Becky Bertram (@beckybertram) recently acquiesced to my suggestion to try using SPServices to solve a challenge she had in rolling up calendar items across lists. I know it may often seem that since SPServices is my hammer that I always say to whack the nails with it, but sometimes it’s actually a good suggestion!

Becky wrote up a nice overview of her approach on her blog. It’s always interesting to see the differences in how people use SPServices. Becky built herself some great functions, which allows for better reuse over time. It amazes me sometimes how others end up with hundreds and hundreds of lines of code rather than coming up with generalized functions, as Becky does here. Sure, some SPServices users aren’t “developers”, but that doesn’t mean that they can’t learn from the examples and build stronger code for it.

Note that the REST services also let you access calendar items (or any other list items), but CAML gives you a better syntax to use with recurring events than I’m aware of in the REST interface. Yup, sometimes, I prefer CAML over the newer stuff.

Check out Becky’s blog for lots of other great SharePoint tips and tricks, too!

Custom Client-side Calendar Query for Office 365 SharePoint Site Using SPServices jQuery Library

I’m building an Office 365/SharePoint Online intranet site for a client and they wanted to show a list of the current day’s events from various calendars on the site, in a format like this:

As you might know, you can’t use a normal CAML query to retrieve calendar entries if you want to retrieve reoccurring events that happen within a given timeframe. (If the first instance of a reoccurring event happened outside the timeframe you queried, the event would not be retrieved, even if it had reoccurring events that happened during the queried timeframe.) The Content Query Web Part will not do the trick.

On projects past, I’ve simply created a web part with a custom CAML query that utilizes the DateRangesOverlap node, and installed that web part using a solution package. This being Office 365, that’s not an option. I could have created a sandbox solution containing the web part but that’s also not a preferred approach since Microsoft seems to be deprecating sandbox solutions. At the urging of Marc Anderson, I tried using his SPServices library.

The SPServices library is a jQuery library that accesses SharePoint web services. By attaching your library to a particular Office 365 SharePoint URL, you can retrieve list items using the SharePoint web service, then use them with jQuery. There’s a discussion thread [on the SPServices Codeplex site – lots of other great stuff there, too!] about how to use SPServices to retrieve calendar entries. I decided to modify the file provided in that thread and use it. The main modification I needed was the ability to combine calendar entries from more than one calendar and show them in a common calendar. This meant utilizing a sorting function after entries from multiple calendars were retrieved so all entries would be listed in the proper order.

You can download my calendar.js file here.

Once I had added the script to my site, I added the following lines of code to my page layout in the header:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js" type="text/javascript"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.3/jquery-ui.min.js" type="text/javascript"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery.SPServices/0.7.2/jquery.SPServices-0.7.2.min.js"></script>
<script language="javascript" src="/Style Library/Scripts/calendar.js" type="text/javascript"></script>

<script type="text/javascript">
$(document).ready(function (){
  CallSPServicesCalendar("https://[sitename].com/site1", "Calendar 1");
  CallSPServicesCalendar"https://[sitename].com/site2", "Calendar 2");
  $('div.calendarItem').sortElements(sortByDate);
  if ($('div.calendarItem').length == 0) {
   $("#calendarData").append("There are no events scheduled for today.");
  }
 });
</script>

The script block at the bottom passes in the URL of the web being queried as a first parameter, and then the name of the calendar list as a second parameter. CallSPServicesCalendar is the name of my function in calendar.js that retrieves calendar entries. At the bottom of my calendar.js I have a function that sorts the calendar entries, which you can see is being called with .sortElements in the script above. If no list items are retrieved, a message is displayed saying there are no events. If you want to query more calendars, simply add new calls to the CallSPServicesCalendar function.

In the calendar.js file you’ll notice a section with Field nodes that get passed into the CAML query. You can modify this section to add your own fields if you have custom fields you want to retrieve and display.

In the body of the page, I added a div tag like this, and this is where the event information was added in the page:

<div id="calendarData"></div>

In the calendar.js file, you can modify the HTML that gets rendered for each calendar entry.