iGoogle UI for SharePoint 2010 – Part Four: Control Adapters

Series Content

1.     Part One – Overview, Concept,  HTML Structure & jQuery Basics
2.     Part Two – Dragging, Dropping,  Sorting and Collapsing
3.     Part Three – Saving WebPart states using Cookies
4.     Part Four – Control Adapters – Current Article
5.     Part Five – SharePoint 2010 Integration
6.     Part Six – Bringing it all together
7.     Bonus – Saving WebPart States using the Client Object Model

Overview

In Part Four we will take the take a look at how we will create our widgets in SharePoint 2010.  As the title of this post mentions we are going to use what is known as a Control Adapter.  This Post will outline what they are, how they work, and how we are going to use them in this series.  There will also be a code snippet to explain how we can use it.

Control Adapters

Rather than try to explain these myself I thought it would be easier to grab a snippet from a Microsoft Article which i think does a great job of explaining what and how they work from an architectural level and in more detail than I could probably achieve :).

At their core, control adapters are simply a way of providing different renderings for controls without actually modifying the controls themselves. Because control adapters are designed to provide alternate renderings for different clients, you specify control adapter mappings in a .browser file, which is where associations between User Agent strings and browser capabilities are defined. The control adapter class itself must inherit from the System.Web.UI.Adapters.ControlAdapter, which is an abstract base class that looks much like the Control base class, with events for Init, Load, PreRender, and Unload, as well as a virtual Render method.

The next step to use a control adapter is to derivatively bind your adapter to a specific control.  To do this you use a Browser Definition File Schema which is found in the App_Browsers folder of the IIS WebSite you are using.

How are we going to use Control Adapters?

Now we know what a control adapter is, what do we need them for?  Well, if we are going to have our WebPart rendering like we have built in the previous three post then we will need to use a Control Adapter to do the hard work for us.  WebParts can be placed onto a SharePoint 2010 Page in many ways.  They can be either added to content inline using the rich content editor, they can be added directly into a page layout or masterpage, or (the most common way) is that they can be placed into a WebPart zone.  It is this final method that we are going to use to modify the rendering of our WebParts.

A basic WebPart Control Adapter Code looks like this:

As you can see from the code above we have a class which inherits from System.Web.UI.Adapters.ControlAdapters.  We first get a reference to the current WebPartZone on the Adapter.  If this is not null then we can start to override the WebPart rendering.  We then check how many WebParts exist in the current WebPartZone that we are in and if there are some then we create a new WebPartCollection object with all the WebParts in the current zone.

We can then loop through each WebPart in the collection and render the WebPart control.   This alone will remove all the tables for each WebPart rendered in a WebPartZone.  The final step to get this basic Control Adapter working is to update the compact.browser file stored (in my case) in the inetpub > webapp > App_Browsers > compact.browser file.

We need to add a single line into the <controlAdapters> node to register our new custom adapter.

Save this file and ensure that the dll is in the GAC and then the control adapter should work.  One thing that is important to know about Control Adapters is that when they are in use they will by default process EVERY WebPart on the site.  For our implementation however we want to be able to choose which WebParts are rendered as our widgets.  To do this we will place some logic into our control adapter which will check the title of the WebPartZone to ensure it contains the text “iGoogle” and only process WebParts that are contained within those specific zones.  Another piece of logic that we need to place into our zones is that we only want our rendering to process WebParts when the page is in the Display mode and not in Edit mode.  The code below shows the updated adapter with the new pieces of logic included.

As you can now see we have first added a line to get a reference to the current WebPartManager on the page which will enable use to get the state of the page and check if we are in display or edit mode.

We are then able to set a boolean value to the state of the page.

The final step is to wrap a new if statement around the render code which will control when the table removal is processed.

When this code is run only WebPartZones with the iGoogle text value in the title will be rendered.

Adding the Widget Code Wrapper

Now that we have the basics sorted for our Control Adapter we now need to wrap our widget code around the render control and this can be done like it would be done in a normal WebPart.  We need to add the following code and replace it within the foreach loop around for each WebPart.

Those who have been following the previous three posts will recognize the HTML from above.  I have use the writer object to inject the HTML and have also ensured that the ID of my widget wrapper div is generated from the current WebPart ID – (wp.ID), and the title of the WebPart is injected into the <H3> tag.

Summary

That wraps up part four of the iGoogle series.  The next post will be to integrate the code above into a SharePoint 2010 solution and include some of the extra pieces such as CSS to enable the this solution to come to life.  The final code for this Control Adapter is shown below.  Thanks for reading and all the positive feedback is greatly appreciated.