Now the solution I present here is also far from perfect, I have no illusions about that. I debated whether to post about it at all until I had a chance to optimse and refine it seeing that what exists here is essentially a protoype, however I believe it is in a complete enough state to provide some benefit or interest to people out there. If anyone can propose some better ways of achieving some of the functionality demonstrated here I’d be more than interested in hearing it. The first half of the post will explain the journey, so if you’re not interested in what drove the implementation decisions along the way, feel free to skip down to the solution.

The Journey

The concept I was going for was something similar to Google Maps; your standard zoom, move, mouse-wheel and drag functionality. The most attractive option I could find was a paid solution called MapBox which can be seen in their various featured map demos. I didn’t think a paid solution would be an option and besides, I wanted to see if I could create something similar myself. I found a jQuery plugin also called MapBox documented at Mapbox: Zoomable jQuery Map Plugin which definitely appeared to get me half way there. The only remaining challenge was to plot the points on the map and get it driven via SharePoint.

Plotting the points definitely proved challenging. I went through a few iterations as I lead myself down some wrong paths – the joys of experimentation. I went so far as to get everything adjusting correctly from a movement point of view (thinking I was better off starting easy and leaving the complicated functionality for later) only to have it breaking during zoom. It wasn’t until I further investigated the zoom requirements and changed the way in which I was approaching the challenge that I realised the work I had done to adjust for movement was redundant and was handled by the plugin. Lovely.

I eventually got the locations remaining in place during zooming however this exposed its own issues; the pins representing each location didn’t adjust in size as the map did, resulting in a very strange looking experience. It is here where my solution is least elegant – I essentially created multiple CSS classes and multiple sized images and dynamically changed the class of the elements as I zoomed in and out (using the width of the parent div to differentiate). I couldn’t simply scale the image as I was using background images and divs rather than image elements (for reasons based on issues with the previous solution and brief experimentation in this one). This exposed even more gotchyas – it appears different browsers round decimal values in different ways (there were variations around rounding, floor or ceiling). I also noticed that while on most occassions the plugin would zoom to fixed width sizes, occassionally it would result in completely unexpected values which I needed a safety net CSS definition for. I love Internet Explorer. The CSS is hence a pretty ugly beast, but for the most part it works.

The next step was adding some hover over functionality to display the staff members information. This was relatively simple and just leveraged the onMouseOver event and some jQuery for each plotted element. The search functionality was a little more complex. I had witnessed the functionality I desired during my research, present on the Rock ‘n’ Roll Metro Map, which I dug deeper into and discovered it was being achieved via the animate function of the jQuery UI plugin. A couple of equations and experimentation later to determine how I could establish my scroll-to points and it was all humming along nicely.

The final challenge was getting it all into SharePoint. This functionality was to sit on the intranet which had been created as a codeless solution, therefore rather than rendering what I needed via the API in a web part I decided to stick with the theme and leverage the Content Query Web Part (CQWP), drawing out of a custom list. The previous solution had done the same so it wasn’t too difficult with a few tweaks to achieve what I desired. A couple of the gotchyas encountered included ensuring the CommonViewFields were set in the CQWP (exporting and importing the web part was used to achieve this) and rediscovering that for a column to exist to filter on in the web part it needed to be a site column, not just a list column. One last little hurdle that needed to be jumped included how the parts sat on the page with the master page being used – and this differed between browsers (Did I mention how much I love IE?). Seeing this probably had a lot to do with the custom master page being used I’ll leave the specifics out in the solution below, however just know that it is something that may need to be considered.

The Solution

Part 1: The list to hold the data

This was a custom list with some custom columns. Note that the IsAResource column is a site column. The -1000 X and Y values reflect a staff member that does not exist in the building.

Part 2: Header.xsl

The templates in Header.xsl map to the Group Style settings selected in the Content Query Web Parts. They render once to open and close the items which are rendered in between. The below templates were defined.

  <xsl:template name="DeskfinderSelectName" match="*[@GroupStyle='DeskfinderSelectName']" mode="header">
    <script type="text/javascript">document.write('<![CDATA[<div id="SearchByName"><span class="SearchLabel">Search by Name:</span><select onchange="FindUser(this.value);"><option value="">Please select an option...</option>]]>')</script>
  </xsl:template>
  <xsl:template name="DeskfinderSelectNameClose" match="*[@GroupStyle='DeskfinderSelectName']" mode="footer">
    <script type="text/javascript">document.write('<![CDATA[</select></div>]]>')</script>
  </xsl:template>
  <xsl:template name="DeskfinderSelectResource" match="*[@GroupStyle='DeskfinderSelectResource']" mode="header">
    <script type="text/javascript">document.write('<![CDATA[<div id="SearchByResource"><span class="SearchLabel">Search by Resource:</span><select onchange="FindUser(this.value);"><option value="">Please select an option...</option>]]>')</script>
  </xsl:template>
  <xsl:template name="DeskfinderSelectResourceClose" match="*[@GroupStyle='DeskfinderSelectResource']" mode="footer">
    <script type="text/javascript">document.write('<![CDATA[</select></div>]]>')</script>
  </xsl:template>
  <xsl:template name="DeskfinderPin" match="*[@GroupStyle='DeskfinderPin']" mode="header">
    <script type="text/javascript">document.write('<![CDATA[<div class="StaffLocations">]]>')</script>
  </xsl:template>

The most important part to note here is that the DeskfinderPin doesn’t have an associated footer. This was a bit of a gotchya – the browsers closed off the div anyway but if I included the footer, the

<script type="text/javascript">document.write('<![CDATA[</div>]]>')</script>

node was appearing within the div which caused issues when I went to extract the HTML via jQuery and pump it into other locations. It worked fine without the footer so it was removed.

Part 3: ItemStyle.xsl

The templates in ItemStyle.xsl map to the Item Style settings selected in the Content Query Web Parts. They’re rendered for each item in the query. The below templates were defined.

  <xsl:template name="DeskfinderSelectOption" match="Row[@Style='DeskfinderSelectOption']" mode="itemstyle">
    <xsl:variable name="DisplayTitle">
      <xsl:call-template name="OuterTemplate.GetTitle">
        <xsl:with-param name="Title" select="@Title"/>
        <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
      </xsl:call-template>
    </xsl:variable>
    <option value="{@ID}">
      <xsl:value-of select="$DisplayTitle"/>
    </option>
  </xsl:template>
  <xsl:template name="DeskfinderPin" match="Row[@Style='DeskfinderPin']" mode="itemstyle">
    <xsl:variable name="DisplayTitle">
      <xsl:call-template name="OuterTemplate.GetTitle">
        <xsl:with-param name="Title" select="@Title"/>
        <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
      </xsl:call-template>
    </xsl:variable>
    <xsl:choose>
      <xsl:when test="starts-with(@Location,'L2')">
		<div class="pin2" style="left:{@X}px; top:{@Y}px;" onMouseOver="DisplayDetails(this);" data-id="{@ID}" data-xpos="{@X}" data-ypos="{@Y}" data-name="{$DisplayTitle}" data-phone="{@Phone}" data-email="{@Email}"></div>
      </xsl:when>
      <xsl:otherwise>
        <div class="pin3" style="left:{@X}px; top:{@Y}px;" onMouseOver="DisplayDetails(this);" data-id="{@ID}" data-xpos="{@X}" data-ypos="{@Y}" data-name="{$DisplayTitle}" data-phone="{@Phone}" data-email="{@Email}"></div>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

It is important to note that all of the custom columns referenced in the template (X, Y, Email, Phone) need to appear in the CommonViewFields element of the Content Query Web Part to be recognised. This can be done by exporting the web part, manually editing the .webpart file to add those columns and importing it back onto the page.

Part 4: The resources

CSS – the CSS used was extended from that used for the MapBox demo with some slight tweaks to those definitions. A little more was added to style the drop down menus and staff information. The majority of CSS was to style the pins mapping to the locations of staff members. As mentioned before, this was a very bloated solution and far too much to include in this post. I’ll try and summarise.

There were essentially 4 groups of styles – level 2 pins, level 3 pins, level 2 ‘located’ pins and level 3 ‘located’ pins. These were seperated into whether they appeared in the firstLayer, secondLayer, thirdLayer or fourthLayer. They were further seperated into sizes mapping to the width of the parent div (the reason for 2 sizes 1 pixel apart is due to the rounding issue I mentioned earlier). Here are a few randomly selected examples:

#firstLayer .pin2
{
	position: absolute;
	width: 10px;
	height: 9px;
	background: url(../PublishingImages/pin2-size709.gif);
}

#secondLayer .pin2.found.size974, #secondLayer .pin2.found.size975
{
	width: 16px;
	height: 16px;
	background: url(../PublishingImages/found2-size975.gif);
}

#fourthLayer .pin3 {
	position: absolute;
	width: 30px;
	height: 27px;
	background: url(../PublishingImages/pin3-size2126.gif);
}

#fourthLayer .pin3.size1505, #fourthLayer .pin3.size1506 {
	width: 21px;
	height: 19px;
	background: url(../PublishingImages/pin3-size1506.gif);
}

You get the idea. Perhaps look into an alternative solution!

Images – The images included the 4 different sized floor map images, the map control image and 100 different pin images to match the CSS styles.

JavaScript – The javascript leveraged that provided with the MapBox demo with the following adjustments.

Functionality to populate the staff information:

function DisplayDetails(person)
{
	$("#staffName").text($(person).attr("data-name"));
	$("#staffPhone").text($(person).attr("data-phone"));
	$("#staffEmail").html('<a href="mailto:' + $(person).attr("data-email") + '">' + $(person).attr("data-email") + '</a>');
}

Functionality to find a given user or resource:

function FindUser(id)
{
	var limitX = 0, limitY = 0, mapWidth = $(".mapwrapper").width(), mapHeight = $(".mapwrapper").height(),
	nodeWidth = $(".current-map-layer").width(), nodeHeight = $(".current-map-layer").height();

	if(mapWidth < nodeWidth) limitX = mapWidth - nodeWidth;
	if(mapHeight < nodeHeight) limitY = mapHeight - nodeHeight;

	var element = $(".current-map-layer div[data-id='" + id + "']");
	var left = (parseInt($(element).css("left")) * -1) + (parseInt($(".mapwrapper").css("width")) / 2);
	var top = (parseInt($(element).css("top")) * -1) + (parseInt($(".mapwrapper").css("height")) / 2);

	left = (left > 0) ? 0 : left;
	left = (left < limitX) ? limitX : left;
	top = (top > 0) ? 0 : top;
	top = (top < limitY) ? limitY : top;

	var width = parseInt($(".current-map-layer").css("width"));
	if ($("div[data-id='" + id + "']").attr("class").indexOf("pin2") == -1)
		$("div[data-id='" + id + "']").attr("class", "pin3 found size" + width);
	else
		$("div[data-id='" + id + "']").attr("class", "pin2 found size" + width);

	$(".current-map-layer").animate({top: top,left: left}, {easing: "easeOutQuart"});
	DisplayDetails(element);
}

The important thing to note here is that extra code was required to ensure the map wasn’t moved ‘out of viewport’. Thankfully, the MapBox JavaScript already included that logic for its drag functionality so I just leveraged that.

Document Ready functionality:

$(document).ready(function() {
	$("#firstLayer,.mapcontent").html($(".StaffLocations").html());

	$("#viewport").mapbox({
		mousewheel: true,
		layerSplit: 8//smoother transition for mousewheel
	});
	$(".map-control a").click(function() {//control panel
		var viewport = $("#viewport");
		//this.className is same as method to be called
		if(this.className == "zoom" || this.className == "back") {
			viewport.mapbox(this.className, 2);//step twice
		}
		else {
			viewport.mapbox(this.className);
		}
		return false;
	});
})

The first line is the most important – this is where the HTML is taken from the hidden div rendered by our Content Query Web Part and injected into the necessary locations. The rest of the code is the same that existed for the MapBox demo.

Custom changes to the _zoom function (insert above return movement; line)

/* Custom changes */
var xChange = (totalWidth == undefined) ? 1 : totalWidth / $("#firstLayer").width();
var yChange = (totalHeight == undefined) ? 1 : totalHeight / $("#firstLayer").height();

$(".pin2,.pin3").each(function(index, value) {
	$(this).css("left", ($(this).attr("data-xpos") * xChange));
	$(this).css("top", ($(this).attr("data-ypos") * yChange));

	var width = parseInt($(".current-map-layer").css("width"));
	if ($(this).attr("class").indexOf("pin2") == -1)
	{
		if ($(this).attr("class").indexOf("found") == -1)
			$(this).attr("class", "pin3 size" + width);
		else
			$(this).attr("class", "pin3 found size" + width);
	}
	else
	{
		if ($(this).attr("class").indexOf("found") == -1)
			$(this).attr("class", "pin2 size" + width);
		else
			$(this).attr("class", "pin2 found size" + width);
	}
});
/* End Custom changes */

Part 5: Referencing the resources

This was a chromeless Content Editor Web Part referencing the required resources:

<link href="../Documents/master.css" type="text/css" rel="stylesheet">
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.3/jquery.min.js"></script>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.16/jquery-ui.min.js"></script>
<script type="text/javascript" src="../Documents/mousewheel.js"></script>
<script type="text/javascript" src="../Documents/mapbox.js"></script>

Take note the version of jQuery referenced – it’s not the latest, but was required for MapBox to function correctly.

Part 6: The search box

This was a chromeless Content Query Web Part pointing to the list in Part 1. It was set to show items of type ‘Custom List’ and filtered where ‘IsAResource is equal to 0′. The Presentation was grouped by <Site> (to ensure the group element was rendered) and sorted by ‘Title ascending’. The ‘Limit the number of items to display’ was turned off. The Group Style was set to ‘DeskfinderSelectName’ and Item Style set to ‘DeskfinderSelectOption’.

To include a Search by Resource box as well as a Search by Name box, the steps above can be followed, however the filter value should be 1 and the Group Style should be set to ‘DeskfinderSelectResource’.

Part 7: The map, associated controls and staff information

This was a chromeless Content Editor Web Part which essentially rendered the HTML which existed in the MapBox demo with a few minor tweaks.

<div class="mapwrapper">
	<div id="viewport" style="overflow: hidden; position: relative;">
		<div id="firstLayer" class="current-map-layer" style="background: url('Images/FloorImage1.png') no-repeat scroll 0% 0% transparent; width: 709px; height: 631px; position: absolute; display: block; left: 0px; top: 0px;">
		</div>
		<div id="secondLayer" style="height: 947px; width: 1063px; position: absolute; display: none;">
			<img style="width: 100%; position: absolute; left: 0pt; top: 0pt;" src="Images/FloorImage.png" alt="">
			<div style="position: absolute; left: 0pt; top: 0pt; background: none repeat scroll 0% 0% white; opacity: 0;" class="map-layer-mask"></div>
			<div style="position: absolute; top: 0pt; left: 0pt;" class="mapcontent">
			</div>
		</div>
		<div id="thirdLayer" style="height: 1262px; width: 1417px; position: absolute; display: none;">
			<img style="width: 100%; position: absolute; left: 0pt; top: 0pt;" src="Images/FloorImage.png" alt="">
			<div style="position: absolute; left: 0pt; top: 0pt; background: none repeat scroll 0% 0% white; opacity: 0;" class="map-layer-mask"></div>
			<div style="position: absolute; top: 0pt; left: 0pt;" class="mapcontent">
			</div>
		</div>
		<div id="fourthLayer" style="height: 1893px; width: 2126px; position: absolute; display: none;">
			<img style="width: 100%; position: absolute; left: 0pt; top: 0pt;" src="Images/FloorImage.png" alt="">
			<div style="position: absolute; left: 0pt; top: 0pt; background: none repeat scroll 0% 0% white; opacity: 0;" class="map-layer-mask"></div>
			<div style="position: absolute; top: 0pt; left: 0pt;" class="mapcontent">
			</div>
		</div>
	</div>
	<div class="map-control">
		<a href="#left" class="left">Left</a>
		<a href="#right" class="right">Right</a>
		<a href="#up" class="up">Up</a>
		<a href="#down" class="down">Down</a>
		<a href="#zoom" class="zoom">Zoom</a>
		<a href="#zoom_out" class="back">Back</a>
	</div>
	<div class="staff-information">
		<div><span class="staff-info-label">Name: </span><span id="staffName"></span></div>
		<div><span class="staff-info-label">Phone: </span><span id="staffPhone"></span></div>
		<div><span class="staff-info-label">Email: </span><span id="staffEmail"></span></div>
	</div>
</div>

Note that the images and sizes were adjusted respectively and each layer div was given an id so I could reference them via both jQuery and CSS. The staff-information div was also included to present the staff information.

Part 8: The staff locations

This was a chromeless Content Query Web Part pointing to the list in Part 1. It was set to show items of type ‘Custom List’, grouped by <Site> and the ‘Limit the number of items to display’ was turned off. The Group Style was set to ‘DeskfinderPin’ and Item Style set to ‘DeskfinderPin’.

Note that the contents rendered here were within a div hidden by the CSS – it’s main purpose was to render the data once, then jQuery injected it into the locations required.

The End Result

An image doesn’t really do it justice, but for the purposes of completing the article, the end result looks something like that depicted below.

Either that or you can watch a video below on how the functionality works.

In the ASP.NET world this topic would barely rate a mention. Handling this matter is essentially as simple as ensuring the <customErrors> mode=”" attribute is set to “On” and the defaultRedirect=”" attribute is set to a valid error page. We can’t use this method in SharePoint however as SharePoint has its own error handling infrastructure which overrides this functionality.

What we do have are different ways in which we can achieve this functionality in both versions of the product. When we talk of error pages in a SharePoint context we can group them into two categories for the purpose of identifying ways in which they can be addressed; 404 Page Not Found error pages and any others (which can include but are not limited to 401 Access Denied errors, 500 HTTP Status errors and the like).

404 Page Not Found

Microsoft has a knowledge base article How to point to a custom 404 error Web page in SharePoint which covers both versions of SharePoint. One thing to note here however is that it’s not necessary to create a console application to carry out the command in SharePoint 2007 – you can also use a powershell command to achieve the same thing noted in Ian Morrish’s post Using PowerShell to set a custom SharePoint Error Page.

Another thing to note is that this method requires the specified file to be valid HTML larger than 512 bytes in size. The size limitation is to ensure friendly HTTP error messages are not triggered in the client. I’ve also seen minorly-invalid HTML rendering as text in the browser so this is another thing to look out for. One more gotchya was identified by Andreas Glaser in SharePoint and custom 404 Page Not Found and UTF-8 issue with Firefox which is worth consideration.

One downside to the method presented above is that you are limited to static HTML pages deployed to the _layouts/1033 directory (or which ever LCID is appropriate for your site). This results in branding elements needing to be implemented in the static HTML and ensures maintenance of the page is more complicated than it should be. The main advice here is to implement a redirect on that error page to a standard SharePoint page along the lines identified by Jingmei Li in How to create your own custom 404 error page and handle redirect in SharePoint 2007 (MOSS)?.

There is another line of thought however, predominantly outlined by Waldek Mastykarz in his posts Accessible 404 (PageNotFound) in Microsoft Office SharePoint Server 2007 and SharePoint 2010 ‘Page not found (404)’ page the way it should be. This advocates using an HTTP Module to redirect the user to a page managed in SharePoint. If you’re going to go down this path focus on the second article and pay attention to Andrew Greaves’ comment.

While I like Waldek’s approach and appreciate its thoroughness in its flexibility for working in all scenarios and its technical correctness, for most purposes using the other method would suffice (particularly in controlled internal environments).

Other Error Pages

While the handling of 404 errors is quite similar in both SharePoint 2007 and 2010, the same cannot be said for other errors. SharePoint 2010 excels in this area providing an easy to use method of assigning these custom error pages at the web application level. Todd Carter provides a post titled An Expected Error Has Occurred which is well worth a read and while the code snippets are identical, Ram Prasad Meenavalli’s post Mapping Custom Error Pages for SharePoint 2010 Site is a good extension to it. Mike’s post SharePoint 2010 Custom Error Messages for Public Facing Deployments is a quality post particularly in terms of 401 authentication errors and is worth a look as well.

Implementing custom error pages for SharePoint 2007 however is not so simple. There seems to be 3 camps of thought; firstly there is the HTTP Module method similar to that used with the 404′s outlined above. While its a little difficult to read and follow, this method is documented in Ketaanh Shah’s post MOSS / Sharepoint 2007 Custom Error Page and Access denied Page. Another option is using a control adapter as per Aapo Talvensaari’s post Custom Error Page Adapter although i’d be a little wary implementing the functionality in this manner. My favourite option is Jeremy Jameson’s Error Handling in MOSS 2007 Applications which advocates hooking into the Error event from a custom master page – nice and clean, however it’s only really appropriate for errors that occur once the page has been accessed – i’m guessing it wouldn’t be suitable to handle errors such as a 401 authentication error.

In the interests of completeness there was one other form of configuring custom error pages I came across on Heath Anderson’s Implementing SharePoint 2010 Custom Error Pages. It is relevant to IIS7 and claims to work in SharePoint 2010 (whether it would work on an WSS instance installed on IIS7 i’m not sure). It definitely looks like a reasonably nice and clean option to consider, however it requires modifications to the web.config file even after configuring via the IIS UI and thus would not be the perfect option in my opinion.

So as you can see there are a bunch of ways in which you can implement custom error pages for your SharePoint site no matter which version of the product you are using. All methods vary in terms of their difficulty, suitability and correctness however the main takeaway is to ensure that you do use one of the methods and ensure that your users have the most user-friendly experience if they counter an error on your site.

The forms of logging I identified and will discuss below include logging to the SharePoint ULS, to the Event Log, via email, a database, CRM or a SharePoint list.

SharePoint ULS

Logging to the SharePoint ULS is arguably the most logical option when it comes to logging exceptions in your custom code. It is most appropriate for developers or support staff if they have access to the files and are able to monitor them consistently. Ideally, the ULS should be monitored regardless to ensure the ongoing health of the site but under some scenarios the files may not be made available and hence logging here would go unnoticed – in this situation an alternative logging option should be considered.

The difficulty with logging to the ULS surrounds the different options available depending on what version of SharePoint you’re using. SharePoint 2010 makes this task a breeze with its SPDiagnosticsService functionality which is available in both the free (SPF) and licenced (SPS) versions of the product. The best articles I found on this topic were Tobias Zimmergren’s article on SP 2010: Developing for performance Part 4 – Logging and Waldek Mastykarz’s extension of this in Logging to ULS in SharePoint 2010.

The task is more difficult in SharePoint 2007. MOSS at least provides some functionality to write to the logs via Microsoft.Office.Server.Diagnostics.PortalLog.LogString (briefly documented in Clayton James’ post Log errors to SharePoint Log file) but that is not available in WSS. There are some examples listed including Eli Robillard’s SharePoint Trace Logs and the Unified Logging Service (ULS) however a number of links in that article are broken now. Gunnar Peipman’s SharePoint: Writing messages to ULS (Unified Logging System) is another quality post however a reasonably complicated solution. There is also a Codeplex SharePoint Logging Library by Ayman El-Hattab that may be able to be harnessed. As you’re probably appreciating now, logging to the ULS in WSS was not made easy.

There is however one saving grace for any version of SharePoint when it comes to logging to the ULS and that is the
patterns & practices SharePoint Guidance Library which i’ll discuss in more detail later.

The other possible qualm about logging to the SharePoint ULS is the difficulty in reading them. This is made easier in SharePoint 2010 by Microsoft’s ULS Viewer or Stefan Gordon’s SharePoint ULS Log Viewer on Codeplex. Tools also exist for SharePoint 2007 including Florin Muntean’s SPTraceView and Stuart Starrs’ WSS / MOSS Log File Reader – both on Codeplex.

Event Logs

The other logical place to log exceptions is the Event Log. It is most suitable for system administrators or developers and support staff who have access to the server (hopefully this isn’t the case in production environments!). Much like the ULS it is reliant on the logs being monitored on a consistent basis and also on the system administrators reporting any issues back to the development or support teams.

Again SharePoint 2010 steps up to the plate with it’s SPDiagnosticsService class, also documented in Tobias’ post outlined previously. SharePoint 2007 has to rely on core functionality in the System.Diagnostics namespace called EventLog.WriteEntry briefly documented in SharePoint King’s Event Log Access Denied : Sharepoint /.NET. As that article points out (to a degree), you need to ensure that access to write to the Event Log is granted to the relevant accounts.

One thing to point out here is, like the ULS logs above, the patterns & practices SharePoint Guidance Library provides the ability to write to the Event Logs as well.

Email

Logging exceptions via email is an interesting one. In my opinion, email should only be used hand in hand with another logging option primarily for the purposes of notification. It is mostly required if the primary log store isn’t checked on a regular basis. There are 2 options available here; either use the in-built SharePoint emailing capability of SPUtility.SendEmail or using .NETs SmtpClient class – both documented in Mohd Sukri At’s post Send Email in SharePoint via .NET SmtpClient Class and SharePoint SPUtility Class.

Database

I’m not a huge advocate of using a database logging mechanism in a SharePoint context however it may be appropriate if there is a need to aggregate exceptions from multiple (and non-SharePoint) applications across an organisation. If database logging is desired then a library should be used such as log4net or the Enterprise Library Application Block. There is a good article on Configuring Enterprise Library 4.0 for Exception handling and Logging by Suleman Ibrahim and some potential issues in Cory Roth’s How to get Enterprise Library working with SharePoint if you choose to go down this path. While on the topic of the Enterprise Library it may be worth pointing out that it is also possible to use it to log to the ULS logs demonstrated in Madhur Ahuja’s post Implementation of Logging and Instrumentation Application Blocks in MOSS 2007.

CRM

My opinions on logging to CRM are similar to that of a database. The most appropriate reason for this however would be in a tightly integrated SharePoint and CRM application where interaction mostly takes place on the CRM side. I’ve actually been involved in projects like this where logging exceptions to CRM was deemed more appropriate than SharePoint as it would aggregate issues from both systems and be more closely monitored. At the risk of exposing my lack of CRM knowledge and in lieu of providing a link to an example, the premise would be to have a log entity in CRM and have a library code-side which creates a dynamic entity of that type, populates the relevant fields, creates a TargetCreateDynamic object binding the dynamic entity and a request binding the target, then executing the request via the CrmService. Sounds easy, is relatively easy, but will leave this to the CRM experts.

SharePoint list

I find it interesting that I have yet to see an implementation of exception logging to a SharePoint list. It’s a highly visible and accessible location to monitor issues within a SharePoint site. Another plus to logging to a SharePoint list is that it is sandbox-friendly and hence a viable option for SharePoint 365. Timmy Gilissen identifies this in his post SharePoint 365 logging and the example is not restricted to just sandboxed solutions (note that if you’re going to take the code from that page you may also want to read Rob Garrett’s post Efficient way to add a new item to a SharePoint list).

On the topic of sandboxed solutions it is something worth pointing out in terms of the other logging mechanisms. It essentially makes them far more difficult to implement, for instance logging to the ULS or Event Logs in a sandbox requires a full-trust proxy due to the Microsoft.SharePoint.Administration namespace not being available in a sandboxed environment. The patterns & practices SharePoint Guidance Library however includes a full trust proxy which enables the use of it’s SharePoint Logger within the sandbox.

The patterns & practices SharePoint Guidance Library

I’ve been a little coy throughout this post regarding the patterns & practices SharePoint Guidance Library solely for the reason that I think it’s worthy of it’s own section in this post. The library is amazing on a number of fronts and this is no different when it comes to Logging. In fact, it is my most recommended option for logging exceptions assuming logging to the ULS and/or the Event Logs is suitable for your circumstances. I highly recommend you visit the page and read what the library offers both from a SharePoint 2007 and 2010 perspective. Another post worth reading in regards to the library is Alex Angas’ Intro to SharePoint 2010 patterns & practices – Logging.

As you can see there are a number of options when it comes to logging exceptions in SharePoint and depending on your circumstances, different ones may be the most suitable. The important part is that you use some form of exception logging and do it in a best practice manner.

As such, I was slightly hesitant to write this post. The reason I have is because exception handling seems to be one of the most poorly implemented (or at least forgotten/ignored) tasks in SharePoint development. It’s also an important task when you factor in user experience, performance and ability to monitor your deployed applications. I’ve seen some shockers; from potential exception-throwing lines of code going unmanaged in web parts which could  bring down the entire page, to swallowed exceptions that you’ll never even know are there. I’ve seen catch (Exception ex) blocks scattered everywhere and try-catch blocks used to control execution flow or used in place of pre-exception checks.

There is a lot of good information out there. MSDN has version-specific editions regarding Handling and Throwing Exceptions. There are some good articles written for .NET in general including Scott Mitchell’s Exception Handling Advice for ASP.NET Web Applications, Daniel Turini’s Exception Handling Best Practices in .NET and Russell Allen’s C# .net Exception Handling Best Practice – As Easy as 1, 2, 3?.

The general consensus tends to boil down to a few rules. Generally, the base exception classes (Exception, ApplicationException) shouldn’t be caught or thrown. Exceptions should only be handled if you can add value to how they’re processed, otherwise they should be allowed to bubble up the chain. Finally, exceptions should be reported so corrective action can be taken if nececssary – preferably using an existing framework such as the Exception Management Application Block.

The question is how these rules and surrounding information can be tweaked to be suitable for SharePoint projects. I’ll structure my comments around this by identifying some general rules and outlining where they’re applicable in a SharePoint context.

1. Never, ever swallow an exception.

Pretty obvious, but the following is a definite no-no.

try
{
    // code
}
catch { }

At the very least the error should be reported using error logging functionality, if not handled sufficiently. I have seen an instance whereby the exception was expected and superfluous to report – I wish I could find it now or even remember why to explain – but if this unlikely case ever occurs it should be properly documented in the code.

2. If you’re going to throw an exception, use throw;

A common piece of code I see goes something along the lines of:

try
{
    // code
}
catch (Exception ex)
{
    throw ex;
}

This is actually quite bad practice. The reasons why were highlighted in some of the links I mentioned earlier, but essentially by doing this you clear the stack trace which is very useful when debugging the exception down the track. You’re better off using the following:

try
{
    // code
}
catch
{
    throw;
}

3. Wherever possible handle the specific exception.

The most common form of exception handling I see is something along the lines of:

try
{
    // code
}
catch (Exception ex)
{
    // handle exception
}

The problem is this goes against the general philosophy behind exception handling. Lee Dumond’s post Friends Don’t Let Friends catch (Exception) explains this nicely.

If you know the object model, or at least know where to go to find the information, you’ll be able to find out which exception/s you should be handling. Take the GetList function in SPWeb. That page identifies clearly the exceptions that may be thrown so you should handle them appropriately.

try
{
    spList = spWeb.GetList("/Path/List");
}
catch (FileNotFoundException ex)
{
    // handle exception
}
catch (ArgumentException ex)
{
    // handle exception
}

An important point to note is that your catch blocks must go in order of most specific to least specific.

4. If you can check for a condition before it throws an exception, do so.

A common block of code you may see is something along the lines of:

try
{
    myString = listItem["MyField"].ToString();
}
catch (Exception ex)
{
    // handle exception
}

Sure, if MyField was never populated in the list item it would throw an exception when you attempt to convert it to a string, but why not check to see if it was populated in the first place?

if (String.IsNullOrEmpty(listItem["MyField"]))
{
    myString = listItem["MyField"].ToString();
}

5. You got to know when to hold ‘em, know when to fold ‘em.

Ok I may have stretched the poetic licence a bit there. What i’m talking about somewhat contradicts the rule regarding letting exceptions bubble up the chain to be handled at the application level. Consider you have a web part on a page, relatively non-critical to the page or application as a whole, a weather web part for instance. Do you really want the whole page to error out because it generated an exception? I wouldn’t begrudge you a global catch (Exception) in that instance.

On the flip side, imagine an event receiver that is processing a list item that is currently being added. The processing is necessary to complete the step of adding the list item, but the exception is caught, reported and held. The list item will exist, but the process did not complete, and depending on the level of reporting the user may never have a clue.

The point is you really need to use your best judgement when it comes to error handling in SharePoint. It’s hard to state a catch-all rule that can be applied across the board, often it will depend on context.

6. Determine the most appropriate form of logging and use it.

I would have preferred to state how errors should be logged in a SharePoint application much more definitively than this. The most important takeaway is to ensure that the errors are logged. The 2 most logical locations to log the errors would be the ULS or Event Log, however this may not always be appropriate. If these locations aren’t regularly monitored or accessible by the people who need to know about the errors, then it is essentially no better than swallowing the errors in the first place. Email, CRM, a database or even a SharePoint list are other potential locations that could be more accessible. Logging to a file on the file system makes little sense seeing if that is an accessible option you could just use the ULS. I write on this topic in more detail and explain my preference for logging to the ULS/Event Log using the SharePoint Guidance Library in my post Error Logging in SharePoint.

7. Use a custom error page.

Nothing looks worse on a public facing internet site or even an intranet application than when you get the ‘yellow screen of death’. Wherever possible you should display a user friendly message rather than an ugly generic error page. I explain the options available around this topic in my post Custom Error Pages in SharePoint.

That about covers it. Just thinking about this post made my head spin around in circles so it’s no wonder why a vast number of developers take the shortcut route and use global try-catch blocks with generic Exceptions. Hopefully this post sheds some light however on why doing so is a bad idea and that there are better options available to be leveraged. If anyone wishes to comment on the topic I’d be very interested in hearing opposing views and ideas – I’d still consider myself learning the best practice approach to exception handling at this point.

If you have the time, there is a tonne of background reading to get through on the subject. Technet includes pages dedicated to both versions of SharePoint including Security and protection for Office SharePoint Server 2007  and Security and protection for SharePoint Server 2010. In this article i’m focussing on securing site content which is more specifically targeted in the Downloadable book: Security for Office SharePoint Server 2007 and Security planning for sites and content (SharePoint Server 2010).

I’ve always favoured a simplistic approach to site security. I used to advocate maintaining security groups in active directory, assigning those security groups to SharePoint groups and then assigning the relevant permissions to those groups across the site where necessary. The premise behind this methodology was to have one source of truth (AD) which was often maintained more religiously when staff joined or left the organisation. It was to allow a ‘set and forget’ approach to security within SharePoint – the security across the site would ideally never change, only the staff members assigned to the security groups. In reality, this approach is far too idealistic.

I’ve since realised that a lot of the time the security methodology will be largely influenced by the context of the organisation. Security groups may make a lot of sense throughout the organisation, but they may not map ideally to the SharePoint site. Some organisations may not and will not assign email addresses to security groups which renders them a tad ineffectual when it comes to workflow notifications. Some will refuse to create SharePoint-specific security groups in AD altogether. AD maintenance may be carried out solely by an over-worked IT department at a low priority, so getting a particular user added to a group may take longer than necessary. Or you may want to display the members of a given site using the Site Users web part and notice you end up with the security group listed rather than the individuals (there is a way around this in SP2010 however, check out Robi Voncina’s Display members of AD group in SharePoint 2010  solution on CodePlex). You get the idea – there’s not necessarily a one size fits all approach that will work in every scenario.

There are however a few golden rules which can be followed with a few potential caveats to implement a solid security methodology across a site.

1. Plan your security

One of the biggest issues with security in SharePoint is it seems to be done ad-hoc initially and grows wildly once the site is live. Security is granted on an as-needed basis with little fore-thought which generally results in a sprawling mess which is hard to track and maintain. Initially the security implementation should be well thought out and planned – identify the levels of access required, the users which will need those levels of access and identify the logical groupings of those users. When security needs to be modified, assess how the change fits in to the initial model and implement the most logical option to affect the change.

2. Document your security

This is particularly important in terms of tracking the customisations to security – preferably everything should be documented. It allows you to have an over-arching view of what is in place – determine what users have access to which portions of the site – something which is otherwise difficult to ascertain. At the very least where ever inheritance has been broken should be clearly identified, especially at more granular levels such as list or item level security (which preferably should be avoided).

3. Inherit permissions where ever possible

Aside from making the job far easier for point 2, it really keeps the security structure a lot more clear and clean to identify which users have certain levels of access across the site. Breaking inheritance at the sub-site level is not too much of a concern but at the list and item level should be avoided if possible. SharePoint helps out in this regard seeing inheriting permissions is the default.

4. Always use SharePoint groups when applying security across a site

You may not be able to only use AD security groups as identified above, but you should always use the SharePoint groups. Permissions should only be assigned to these groups rather than individuals – you are able to add both AD users and security groups to the SharePoint groups. It keeps everything a bit neater and consistent across the site rather than having some SharePoint groups, some security groups and some individuals. It’s worth preventing group-sprawl if possible – maintaining as few logically seperated groups as possible will ensure ease of maintenance.

5. Use AD security groups where appropriate

I still prefer using security groups to keep the SharePoint security structure clean and concise – but only when it makes sense to do so. Leverage the Domain Users group to provide global read access across a site for instance.

6. Use the principle of least-privilege

This is just good practice in all forms of IT. No user should ever have access to functionality that they don’t need. I’ve seen plenty of implementations which give site ownership to a wide range of users so they can edit a particular page of a sub-site, then wonder where a certain list item disappeared to.

The goal for any security implementation should be simplicity, understandability, maintenance efficiency and most importantly effectiveness in securing the content. The best way to get there is to plan and document the approach, for the time invested in the beginning will save a lot of headaches moving forward.

Rather than focus the article on the differences between a 301 and 302 redirect I’d rather point you in the direction of some existing resources that explain the details better than I could myself. The article Redirects: Permanent 301 vs. Temporary 302 does a good job in doing so.

The main concern around the 301 vs 302 redirect in SharePoint is 2-fold. Predominantly, there is a lot of information floating around the net in regards to the SEO implications of the 2 redirect techniques. To cut a long story short, 301 redirects are generally preferred from an SEO standpoint to 302 redirects. The problem being, SharePoint uses 302 redirects for its ‘Redirect Page’ layout. You can get a more in depth explanation of this in Jeff Cate’s post MOSS for Internet and 301 Redirects.

Those wanting to implement 301 redirects rather than the default 302 redirects are left with 2 main options. Firstly, IIS can be used to re-write the URLS (which serves as a 301 redirect). This can be done natively via an add-on in IIS7 and with a 3rd party add-on in IIS6. Secondly, the option exists to write a custom HttpModule to perform the 301 redirect as per Waldek Mastykarz’s post on Using 301 instead of 302 redirects. Waldek’s post is focussing more on another MOSS 302 redirect phenomenon rather than the Redirect Page layout but the concepts are still applicable.

I have a bit of an issue with both solutions. I should be attracted to the custom code option being a developer by trade, but from a complexity and maintainability point of view it doesn’t really appeal to me. It may be possible to architect a solution whereby the redirects are maintained in a SharePoint list improving the functions extensibility, and that’s probably the angle I would have looked into had time allowed, but it still seems like a bit of an overkill considering the IIS solution existed. The problem with the IIS solution however is (aside from it not being native in IIS6 which was being used in my instance) that maintenance would need to be conducted on the server by IT rather than the site owners.

Jeff posed the question in his post ‘Will it be in SharePoint 2010?’ – unfortunately, the answer is no. Waldek points out in a follow up post Using 301 instead of 302 (without code!) that they can be handled in IIS7 (required for SharePoint 2010) natively, which is true and how Jeremy Thake at NothingButSharePoint implemented their 301 Redirects in IIS7.5, but doesn’t solve the issue of giving access to site owners to perform the function. You really don’t want this administrative overhead placed on IT.

To be honest in my opinion we seem to be left with no ideal option. It would be nice (but still not ideal) if 301 redirects could be set and maintained via Central Administration (at least ensuring server access would not be necessary). It would be even better if they could be set and maintained in the Site Settings of the relevant site. Better still, an option on the redirect page to indicate whether it should be a 301 or 302 redirect would be perfect.

For now we’re left with the options presented. Having a personal interest in SEO myself it would be nice to see future versions of SharePoint tailored towards this goal in anyway possible, and making it easier to perform 301 redirects out of the box would be one way of getting there. Assuming SharePoint vNext is based on .NET 4.0 we should be a lot more likely to have this feature considering the 301 Redirects in .NET 4.0.

If it so happens that this piece of work is given the green light i’ll post a follow up on how the solution was achieved.

It’s ironic that in projects laced with features and solutions to deploy resources ‘the right way’ that configuration is overlooked and remains a manual process. Aside from wanting to avoid any manual modification of files directly on the server by principle, dangers exist in terms of ensuring the web.config files are the same on all web front end servers. Maintaining application settings this way also requires access to the web.config file (and hence server) itself which wouldn’t be considered best practice, and the act of changing a variable in the web.config directly would cause the application pool to refresh and cause the site to load slowly on the next hit.

I write this post with a tinge of regret – I too have been guilty on multiple occassions of maintaining the status quo and leaving (and even adding to) configuration values maintained manually in a web.config file. So not only should this post serve as a source of information regarding the best practice methods to maintain application settings, but it should also serve as a motivator to myself and others to practice what I/we preach on all future greenfield projects.

Anyone who has studied for or taken the application development exam (70-576) would have noticed that 4 main options consistently get presented for application configuration: web.config, lists, property bags and the hierarchical object store. I’ll discuss each option briefly and provide some situations where the method would be appropriate.

Web.config

Now it may seem like i’m beginning to contradict myself here – I previously mentioned that manually maintaining application settings in the web.config was a BAD idea. It is. The beauty of SharePoint though is that it provides a mechanism to maintain application settings in the web.config file automatically via the SPWebConfigModification class. If you’re wanting to store them in the web.config, then a feature should be created which on activation uses the SPWebConfigModification class to modify the web.config for you. This ensures that the same values are written to the web.config files on all front-end web servers and even ensures they’re consistent amongst new servers added to the farm.

You’re likely to want to use this option if you just can’t pull yourself away from the web.config for variable configuration. At least its a safer method. There are some valid reasons however – it’s reasonably simple to incorporate this functionality and then easy to program with seeing you’re probably used to it already. It ensures values are consistent across all front-end web servers and are available and consistent across the entire web application. It’s also fairly useful for ‘set and forget’ the values – if you’re unlikely to need to change them in the future, then you won’t run into the application pool refresh issue I mentioned previously and will get the performance benefits of the cached settings.

Before running off and using this method however, be warned that the web is littered with issues and problems with using SPWebConfigModification. I’d probably want to avoid making any ‘unnecessary’ changes to the web.config especially for the purposes of setting configuration values considering there are other options available.

SharePoint lists

It almost seems too easy and obvious. SharePoint provides us with these useful things called lists. Most of us would be familiar with or have used database-driven variable configuration mechanisms before. Lists, on face value, are reasonably similar to database tables. Why don’t we use lists for variable configuration? It’s not actually that silly a proposition and is in fact one of the more reasonable options. One of the beauties of using lists is that you get all that SharePoint listy goodness. Versioning, security and an out-of-the-box UI for example. You’re likely already familiar with list-based programming, so that isn’t too much of an inconvenience.

Using SharePoint lists is definitely one of the preferred methods. It’s probably easier to outline some of the reasons why you may not want to use it; a site with lax security restrictions would probably be wise to avoid this method – you wouldn’t want any user being able to modify or delete configuration items or the list itself. If you wanted the application settings to be available to multiple site collections/web applications then you’d potentially end up duplicating the list values across these sites.

There’s another huge advantage to choosing this method. An MVP named Chris O’Brien has written a Config store framework available on Codeplex which makes the option even more attractive and erases some of the drawbacks from choosing it. I’d definitely recommend reading a bit about it in his post A better Config Store for SharePoint sites.

Property bags

This option is perhaps a little less obvious but similarly powerful. A number of SharePoint objects contain a Properties property which stores a collection of key/value pairs. These obviously lend themselves towards being used for storing application settings.

This option is possibly the best one to harness when scope is an important consideration for configuration. It lends itself to being able to maintain numerous variables with different values on a per-scope basis (per web, per web application and so forth).

Like the SharePoint list option, this also benefits from addons which improve the usability and effectiveness of the option. The SharePoint Guidance Library provides the Application Setting Manager which is an API to read and write application settings. Codeplex also has the SharePoint Property Bag Settings project which provides a GUI in Central Administration to manage the settings.

Hierarchical Object Store

This is a farm-scoped store similar to a property bag. It requires custom code to create and is far more complex than the other options, however has the benefit of being able to store more complex types if that’s neccessary. Generally for the purpose of variable configuration though, in my opinion i’d go for one of the other options.

You’d possibly choose this option if you were looking for a global storage option for values or required complex values to be stored. If the values are simple key/value pairs however a farm-scoped property bag would probably be easier to use and do the trick.

WebPart properties

I know I said before there were 4 main options, but I wanted to briefly cover this one too. In the event that your custom web parts require configuration values specific to the web part then it will often make sense to include custom properties editable in the web part itself – they are then able to be set by modifying the settings of the web part.

My initial concept for this post was to include an array of advantages, disadvantages and code samples on each option to more completely highlight where each could be used and how they’re used, however during my research for this post came across an MSDN article written by David Mann titled Managing Custom Configuration Options for a SharePoint Application – it essentially covers in reasonable detail those points and I would strongly recommend reading.

Overall I’d have to say I prefer the SharePoint list method the best. I’m somewhat surprised, I remember thinking a while ago that using lists for application settings would be a bit primitive and that surely the other options which have been provided (obviously for the purpose of variable configuration?) like SPWebConfigModification, SPPersistedObject and the Properties collections would be the best practice method to use. I guess sometimes the easy option actually is the best, and it’s sandbox-friendly to boot.

First though a bit of background on what brought this topic to the fore. The project I was analysing was a shared solution used for a large number of public facing websites (5+) hosted on the MOSS platform. All resources (CSS, Images, JavaScript, Flash) were deployed to the 12 hive within a folder structure suitable for identifying the site the resources belonged to. There were some smarts in the code which determined where to reference the resources in question.

The problem was 3-fold. Firstly, some site owners wanted the ability to make changes to the CSS or images themselves and didn’t have access to the servers to do so. Secondly, even if the changes were to be made by the development team they still needed to be done within the weekly change window to deploy the new solution. Finally, because the solution was shared between a number of sites and contained code as well as resources, any minor changes made to an image or CSS file would need to go through a complete and rigorous UAT and regression testing phase before they could be deployed.

The solution was obvious; the resources needed to be stored in the content database, and there are a number of benefits gained from storing resources for SharePoint in there.

1. Site owners can be given the ability to make modifications to the images and CSS files if desired. Assuming they don’t have access to the server itself, and they shouldn’t, getting the files into the content database is the best way to enable this.
2. Immediate access. Assuming you’re deploying your resources to the file system via a solution package (and there should be no other option), you’ll require the solution to be deployed and in many cases this needs to be scheduled during a deployment window.
3. Versioning. Storing these files within the content database will be able to leverage the in-built versioning capabilities of SharePoint assuming they’re enabled. This could be countered with the fact that source control could be considered a form of file versioning.
4. Backups. This in my opinion is somewhat of a minor benefit as any decent disaster recovery plan would incorporate multiple forms of backup which would include source control and the SharePoint server (assuming virtual environments), however having the files in the content database enables the resources to be backed up both via SharePoint mechanisms and via backups of the SQL database.
5. Isolation. By storing the files within the content database you’re ensuring that any changes made are far less likely to affect other sites hosted on the same server. Storing the files within separate sub-folders on the file system mitigates this to an extent, but it’s less safe.
6. Sandboxed solutions. While not relevant to my own situation in MOSS, deploying the resources to the content database enables the solution to be deployed as a sandboxed solution, opening the door to deploying in a hosted environment.

So why would anyone want to deploy their resources to the file system in the first place? I’m going to start by being cynical – developer laziness. Frankly, with tools such as WSPBuilder in 2007 or the build-in developer tools in 2010 it’s simply easier to place your resources into a mapped folder in your solution rather than creating the feature and module to deploy the files to the content database. There are however legitimate reasons why you may want to go down this path.

1. Global access. It is possible that some of the resources you are deploying need to be used across sites for the purpose of common branding. By deploying to the file system all sites will have access to the files without having to duplicate content into the individual content databases.
2. Restricting access. While the granular security in SharePoint allows you to lock down access quite significantly, there is the possibility that a user may have levels of access which would give them the ability to modify these resources when they shouldn’t. It would be a bad security scheme that enabled this, but keeping the files out of the content database and on the file system would ensure this never happened.
3. Performance. Out of the box you’d get better performance having the resources on the file system rather than the content database. You can get around this for the most part using the build-in caching mechanisms within SharePoint such as BLOB caching, however for MOSS at least there are known issues associated with this noted in Chris O’Brien’s post on Optimization, BLOB caching and HTTP 304s.

It’s a question that seems to polarise the SharePoint community and there are a bunch of blog posts, MSDN articles and discussions on this very subject matter. My personal opinion now, which would appear to be backed by a number of credible posts I’ve since read, is that ideally resources for SharePoint should be stored in the content database whenever possible.

To be honest this article could go on forever with explanations and definitions, examples and possibilities. What I’ve since found when researching for this post however is that the information available on the net is actually pretty comprehensive. Unsure what the difference is between the various view-model design patterns? Take a look at Niraj Bhatt’s post on MVC vs. MVP vs. MVVM. In fact somewhat to my surprise there are even a number of quality SharePoint related posts in regards to implementing MVVM. The majority of them relate to MVVM in Silverlight hosted in SharePoint – you can read up on a great article series by Andrew Connell regarding Silverlight, MVVM & SharePoint. There’s a quality post by Shailen Sukul regarding Applying MVVM Principles to SharePoint 2010 Development. There’s even a post on Using MVVM with Office365 and SharePoint 2010 REST API by Sahil Malik.

Sahil’s post is somewhat similar to my own. The reason being, we’ve both implemented the MVVM pattern using Knockout – a library to ‘Simplify dynamic JavaScript UIs by applying the Model-View-View Model (MVVM) Pattern’. There is a difference however – where Sahil had the luxury of using the SharePoint 2010 REST APIs which go hand in hand perfectly for this purpose, my task was to implement it in MOSS 2007.

The tools created using this method are a part of the suite of tools that exist on the Career Centre Portal including the Resume Builder, Slider tools, Choices and Hands On, Career Possibility Generator, Card Sort tools and multiple forms throughout the site. A number of developers have played a large part in the creation of these tools and forms including Paul Maddox, Elliot Wood, Lay Hooi Tan and myself. Some are SharePoint list-driven and others are CRM-driven. For the purpose of this article I’ll focus on the Career Possibility Generator.

So how does Knockout work? It could really do with a post of its own. I’d suggest reading the documentation for a full explanation of how it works and its capabilities. Trying to keep it simple however, essentially you use data-binds to map UI elements to values stored in a data model. If you define the value as ‘observable’ you ensure that updates to the UI are reflected in the model and vice-versa. Knockout also harnesses the jQuery.tmpl template engine to render repeatable blocks of code.

It’s driven really well by using a JSON object as the underlying data model. This is why it ties in so nicely with the SharePoint 2010 REST services – you can quite easily pull back a JSON object instead of an Atom response via those services and use it within the Knockout framework. To get around this missing functionality an ASHX handler was created to return the JSON object for us. This is quite easy to do – the generic shell of the handler would look something like that shown below:

public class MyHandler : IHttpHandler
{
    #region IHttpHandler Members

    public bool IsReusable
    {
        get { return true; }
    }

    public void ProcessRequest(HttpContext context)
    {
        List<CloudListItem> items = new List<CloudListItem>();
        // Retrieve items from SharePoint and populate into the generic list
        JavaScriptSerializer ser = new JavaScriptSerializer();
        string jsonObject = ser.Serialize(items);
        context.Response.Clear();
        context.Response.ContentType = "application/json";
        context.Response.Write(jsonObject);
    }

    #endregion
}

public class CloudListItem
{
    // Various properties to return in the JSON object
}

The next step is to bind the returned JSON object to Knockout and in turn allow Knockout to bind the values to the UI using applyBindings.

<script id="Occupations_Cloud_Tmpl" type="text/x-jquery-tmpl">
    <li class="cloud${Count}"><a target='_blank' href="${PageUrl}">
      <label data-bind="text:Title"></label>
    </a></li>
</script>

<div id="tag-cloud">
    <ul id="occupations-cloud"
        data-bind="template: {name: 'Occupations_Cloud_Tmpl', foreach: viewModel.Cloud}">
    </ul>
</div>

<script type="text/javascript">
    $.getJSON('/_controltemplates/ccosdportal/handlers
               /ListToJsonHandler.ashx?ListName=NormalisedKSA
               &Web=occupations', function(data){
        //viewModel.Cloud = ko.mapping.fromJS(data);
        viewModel.Cloud = data;
        $.each(viewModel.Cloud, function(index, value) {
            value.Count = ko.observable(0);
        });
        ko.applyBindings(viewModel.Cloud);
    });
</script>

Essentially what the above code will result in is an unordered list of Occupation profile links with a distinct class applied. I’ve left in the comment above to demonstrate one of the gotchyas I encountered using Knockout. By using ko.mapping.fromJS() you’re essentially ensuring that all properties within the JSON object are observable. This causes some memory issues if the object is too large and can result in the following warning in Internet Explorer browsers:

The only thing left to explain here is how the ‘observable’ functionality works. The tool itself includes a number of checkboxes which users can select which in turn drives how the cloud looks on the screen. The checkboxes are mapped in SharePoint lists to various occupations and thus when a checkbox is selected that maps to a given occupation, the class applied to the relevant list item is modified to reflect that link. As you may have noticed, the only observable property in the object is the ‘Count’ which is used in the list item class=”cloud${Count}”. By incrementing the Count value in the model, the UI is updated to reflect the new value and hence changes the class of the list item, changing the way it displays on the screen.

function AdjustCloud(checkbox) {
    var addValue = -1;
    if (checkbox.checked) addValue = 1;

    $.getJSON('/_controltemplates/ccosdportal/handlers
               /ListToJsonHandler.ashx?ListName=OccupationKSA
               &Web=occupations&KSAID=' + checkbox.value, function(data){
    if (data.length > 0)
    {
        $.each(data, function(ind, dtwd) {
            var dtwdVal = dtwd.DTWDANZSCO;
            $.each(viewModel.Cloud, function(index, value) {
              var clouddtwdVal = value.DTWDANZSCO;
              if (clouddtwdVal == dtwdVal)
                if (((viewModel.Cloud[index].Count() + addValue) >= 0) &&
                   ((viewModel.Cloud[index].Count() + addValue) <= 9))
                       viewModel.Cloud[index].Count(viewModel.Cloud[index].Count() + addValue);
            });
        });

         HideItems();
    }
    });
}

A visual example of the tool can be seen below (click for the full-sized image).

If you take the time to look at the Career Possibility Generator and all the tools throughout the Career Centre Portal you’ll get an appreciation of how powerful it is to leverage the MVVM pattern via Knockout to create highly interactive applications within SharePoint.

This actually turned out a little more challenging than I was expecting. There appeared to be a lot of information in regards to WordPress APIs as it related to plugin development, but the information I was searching for wasn’t as obvious to find. I eventually found out that WordPress supports both the Atom Publishing Protocol (AtomPub) and XML-RPC for client development and that currently WordPress provides more features and capabilities via XML-RPC than AtomPub. XML-RPC seemed the way to go.

This snippet of information actually made life a lot easier. Turns out that the information WordPress provides on this subject is actually pretty useful. Firstly there’s the XML-RPC Support page which identified that 3 APIs were supported; Blogger, metaWeblog and Movable Type. There’s also an extension to the Movable Type API specific for WordPress (conveniently called the WordPress API) that should be used as a first resort if possible. That API is pretty well documented too on the XML-RPC wp page.

It seemed pretty promising – getCategories? Perfect. There didn’t seem to be an obvious way to get the latest blog post though from this API so the search continued. Reading through the alternate API’s metaWeblog seemed the easiest to use and appeared to have the functionality I needed. Unfortunately I found it to be pretty poorly documented – it seemed that no one wanted to make this task easy! I did stumble across one page; Eric’s WordPress XML-RPC – MetaWeblog API. Without this page I think I would have had a much harder time getting everything to work – getRecentPosts? Perfect.

The only thing left to do was to code it up in .NET. Turns out there’s an excellent library for this purpose by Charles Cook called XML-RPC.NET. The download includes the DLL you’ll need to reference (CookComputing.XmlRpcV2.dll) and a bunch of examples to get you started.

Time to pull out a few code snippets. Firstly you need to create an interface with the functions you intend to call:

public interface IStateName : IXmlRpcProxy
{
    [XmlRpcMethod("wp.getUsersBlogs")]
    Blog[] GetUsersBlogs(string username, string password);

    [XmlRpcMethod("metaWeblog.getRecentPosts")]
    BlogEntry[] GetPosts(int blog_id, string username, string password, int numberOfPosts);

    [XmlRpcMethod("wp.getCategories")]
    Category[] GetCategories(int blog_id, string username, string password);
}

The arrays are public structures with the properties you’re wanting to pull back – note that casing is important for the properties – make sure it matches the documentation exactly. Next is the code to retrieve the most recent post, and then all the blog categories:

IStateName proxy = XmlRpcProxyGen.Create<IStateName>();
proxy.Url = XMLRPCUrl;

BlogEntry[] blogEntries = null;
BlogEntry blogEntry = new BlogEntry();
Blog[] blogs = proxy.GetUsersBlogs(Username, Password);
if (blogs.Length > 0)
{
    Blog blog = blogs.FirstOrDefault(s => s.blogName == BlogName);

    if (blog.blogid != null)
    {
        blogEntries = proxy.GetPosts(int.Parse(blog.blogid), Username, Password, 1);
        blogEntry = blogEntries[0];
    }
}

IStateName proxy = XmlRpcProxyGen.Create<IStateName>();
proxy.Url = XMLRPCUrl;

Category[] categories = null;
Blog[] blogs = proxy.GetUsersBlogs(Username, Password);
if (blogs.Length > 0)
{
    Blog blog = blogs.FirstOrDefault(s => s.blogName == BlogName);

    if (blog.blogid != null)
    {
        categories = proxy.GetCategories(int.Parse(blog.blogid), Username, Password);
    }
}

The XMLRPCUrl is your wordpress address /xmlrpc.php (ie http://spmatt.wordpress.com/xmlrpc.php), the BlogName is the name of your blog (ie SPMatt) and your Username and Password is pretty self explanatory – use the account you use to author/administer your blog (I believe some of the actions you’re able to perform are dependant on the credentials of the account you use – using the administrator account is obviously the bad practice / guaranteed success way of getting it working).

That’s pretty much it. There’s one last potential gotchya and that’s to do with organisational proxies on your SharePoint servers. If the server requires a proxy to access the internet then there’s a fair chance you’re going to end up getting an error page like this (click to expand):

What’s required is to find the proxy line in your web.config and change it to the following:

<system.net>
  <defaultProxy>
    <proxy proxyaddress="http://your-proxy-address:port" bypassonlocal="true" />
  </defaultProxy>
</system.net>

And that should be it! You’re good to go. Pretty basic integration I know, but for most public facing sites this is all you’ll ever need. Dig in to the APIs and see the true power you can get interacting with WordPress through the APIs (anyone feeling like authoring blogs in SharePoint and publishing them to WordPress and vice-versa?).

One last point I should mention – I’ve yet to link in this blog to a man who seems to be a bit of a guru in this stuff – at least it seems that way from the research I did. His name is Joseph Scott and you can view a slidedeck of a presentation on the WordPress APIs here. If you’re scouring the net for decent advice I’d suggest looking out for his name would be a good start.