Sharepoint 2007 Customization Ramp Up - Part 3: Basic Customization

Welcome to Part 3 of the series. In the previous two sections I covered things you should know before getting started with SharePoint Customization, while in this section I will cover actually doing some customization. Firstly, let me state for the record that most of what I've learned on this topic has been from reading blogs from Heather Solomon and Liam Cleary, along with just playing with things myself. Many of the topics covered in this article can seen in much more detail in some of their posts.

Basic Customization:

• Using SharePoint Designer
• Understanding How Pages are Rendered in SharePoint
• Minimal Master Page
• Overriding Cascading Style Sheets
• CSS Friendly Adapters
• Customizing Navigation
• Customizing Search Results
• More Customization Examples

 

Using SharePoint Designer
I covered some basic concepts of using SharePoint Designer and the pitfalls of UnGhosting in my previous article. That being said, this article will be centered mostly around customization by using SharePoint Designer, while the next installment will cover making Site Definitions for customization. I like proofing all of my designs using SharePoint Designer first and then when I am happy with the results I package them up into a Site Definition. I find this method much more fluid because you can see your changes right away just by refreshing the site in your browser. See my previous article for some tips on getting started with SharePoint Designer.

Understanding How Pages are Rendered in SharePoint
As I mentioned before Heather's article on this is really the cream of the crop, but I will cover a brief overview of it here. Basically, your rendered page is made up of several dynamic parts which SharePoint merges together on the fly as a page is requested. You can think of the rendered content from the outside in as:

• Master Page - Controlling the outermost shell of the design including headers, nav, css, body content, javascript, and footer. Also includes Content Placeholders which are required to mark where the specific SharePoint features will be located in your design
• Page Layout - Controls the actual main body content including field controls and web part zones
• Content Types - Field Controls point to specific Content types and can be thought of as something like a grouping of data fields (or Columns) which make up a document type
• Columns - Columns are the most atomic type of data storage in SharePoint. They are literally the actual data column that is located in a table in the SharePoint Content Database. Think of them as areas that reusable content is stored (examples: author, publish date, byline, content, roll-up image, etc.)

When customizing your SharePoint 2007 sites, you will probably want to work in this order from Master Page down to Columns.

• MOSS 2007 Design Component Relationships and Diagrams - Heather breaks down SharePoint page rendering in the most understandable way I have seen to date

 

Minimal Master Page
The Master Page is really where any SharePoint design begins, it contains much of the layout shell and must include specific Content Placeholders to tell SharePoint where specifically you want things like the navigation and Site Actions to be located. If you omit the required Content Placeholders, SharePoint will error on you. Because of this, it makes sense to start with a bare bones Master Page that contains no styles and just the sections that are absolutely required. Thankfully Microsoft has included an easy way to create an empty site with an empty master page... OH WAIT... that would be too easy... no, in fact there is nothing like this included with SharePoint out of the box. Thankfully, once again, Heather to the rescue. Go to her site and download her Base Master Page asap.

• Heather's Base Master Page File for SharePoint 2007 - Heather's base Master Page is the one I usually start with
• How to: Create a Minimal Master Page - Microsoft's minimal Master Page. Heather's is better, but this is good for reference

 

Take a look at those Master Pages, notice how they handle the Content Placeholders that they don't want to show. You can simply place the unwanted Content Placeholders in a hidden panel via:

<asp:Panel visible="false" runat="server">

Overriding Cascading Style Sheets
Overriding CSS is another key to customizing SharePoint designs. Almost everything in SharePoint can be styled with an overriding Cascading Style Sheet. To better understand this concept, check out some info from Heather's blog, specifically check out the second link listed here which is a gigantic list of all the major SharePoint elements and their css classes:

• CSS Options with Master Pages - There are several options for how you override the SharePoint css files, Heather goes over the pro's and con's of each method
• CSS Reference Chart for SharePoint 2007 - Heather's gigantic list O' SharePoint style classes

 

When it comes to overriding the css, I find it incredibly helpful to have Firebug at my disposal. If you have never tried Firebug I can't recommend it enough. When installed in Firefox you can load an interface that not only allows you to pinpoint what classes are being assigned to an element but also if they are overriding other classes, and probably even more importantly, allows you to modify them and see the changes in real time. Its probably the single most important weapon in my SharePoint customization toolkit. I only wish that it would work in Internet Explorer for those times when IE and Firefox diverge in their handling of css. I have also included a link to the Internet Explorer Developer Toolbar which is worth downloading, but is not nearly as useful as Firebug.

• Firebug
• Internet Explorer Developer Toolbar Beta 3

 

CSS Friendly Adapters
When it comes to CSS, one area that SharePoint is lacking is the actual ASP.net 2.0 controls that it relies on (asp:menu and asp:treeView as examples). Many of these pump out extremely verbose and non con formant table structures. If you require very specific styling of these, or are interested in w3c and government compliance you are going to be sorely disappointed in Microsoft's out of the box implementation. To get around this Microsoft has released to the community a set of CSS Friendly Control Adapters that work nicely with SharePoint 2007. Essentially what they do is replace the standard html stream that ASP.net is sending to the browser with a very minimal css friendly layout. They can be rather tricky to install, so I have an article on how my team put them to use (see below). For example the standard code for the Menu control outputs a table structure that includes many many elements, some with classes defined (for overriding) and some without. With the adapters installed it outputs a simple unordered list with each element having unique classes defined. I have found this MUCH easier for customizing.

• ASP.NET 2.0 CSS Friendly Control Adapters 1.0
• CSS Friendly Control Adapters in SharePoint 2007 (A Walk-Through)

 

One quick word of warning on the CSS Friendly Adapters: my team is running into issues with the treeView adapter crashing some of the SharePoint out of the box admin pages. Some folks are working on a solution now, you can follow the story at the asp.net forums.

Customizing Navigation
A big part of any SharePoint customization is making the menu's your own. Besides customization with CSS you may want to user various dataproviders to show different navigation schemes or play around with the amount of static or dynamic menu items that show at any one time.

• Moss Navigation Deep Dive Series - The Microsoft ECM Team goes into excruciating detail about the various menu options that are available

 

Customizing Search Results
Searching is a huge deal in SharePoint 2007, and you may want to customize the search results page. You can either edit the results page by using the SharePoint web interface (just use the Site Actions menu to edit the page) or use SharePoint Designer. From SharePoint Designer go to Open Site and pick your website. At the top of the Folder List you will see Search listed. Double click this, and it will open the Search site. From here, you can see the results.aspx page listed. Be warned that this file is extremely dense (mine clocks in at 1200 lines).

• Search Results - Liam gives a great overview of using the SharePoint web interface to customize the search results

 

More Customization Examples
There are several great SharePoint UI customization examples on the web right now that give thorough walk throughs of the entire customization process, here are a few of them:

• Building tylerbutler.com, Part 1: Planning and Basic Branding - Tyler Butler posts a six part feature on customizing MOSS to look like his old site
• Customizing and Branding Web Content Management-Enabled SharePoint Sites - Patrick Tisseghem's three part article on customizing a WCM site
• hello its liam - Rebuild Corporate Website (Parts 1 - 7) - Liam's seven part SharePoint customization series

CSS Friendly Control Adapters in SharePoint 2007 (A Walk-Through)

My good friend John Ross just managed to get the CSS Friendly Control Adapters working in a SharePoint 2007 Publish Site, and I was able to talk him into posting a guest blog entry on the topic. If you aren't familiar with them, you should check out the CSS Friendly Control Adapters here, they are very helpful in creating CSS only, standards compliant controls (like the menu and treeView) for easy styling. I also noted that Microsoft was kind enough to allow the community to take over the development and enhancements of the adapters in an open source model. You can read more about that news in their forums. So without further fanfare, here is John Ross's CSS Friendly Adapters in SharePoint 2007 walk-through:

One of biggest selling points for SharePoint 2007 is that it is built on top of ASP.NET 2.0.  That means, that if you create a design that will work in ASP.NET 2.0 it will work in SharePoint 2007 right?  The short answer is yes!  But the big question is “How do you do it?”  As we were trying to recreate our design concept for an Internet-facing website in SharePoint, we were quickly able to create a new master page and get our page very close to our concept.  However, styling the navigation proved to be a challenge.  If you view the source for the default navigation that is rendered in the browser you’ll notice that it is full of tables.  Very messy indeed!  There had to be a better way – CSS Friendly ASP.NET 2.0 Control Adapters seemed like the answer.

Using a post from one of the developers at Tam Tam) http://blogs.tamtam.nl/frank/PermaLink,guid,aad39854-4f7d-4666-8a0a-0fc02f3cd01b.aspx) from back in August 2006, it provided a good start.  But if one were to follow these instructions to the letter, they will run into a problem (which I’ll talk about later).  This post will repeat many of the steps outlined in this original post, but will provide additional detail about getting the CSS Friendly ASP.NET 2.0 Control Adapters to work.

1) Download and install the ASP.NET 2.0 CSS Friendly Control Adapters (http://msdn.microsoft.com/vstudio/eula.aspx?id=%20096D9643-2597-4a3b-82E3-8863145E4A3D)

(NOTE: I had some trouble with the install and had to select all of the content items for install otherwise it didn’t work.  Don’t quote me on that, but that’s what I had to do).

2) Once you’ve installed the Adapters, open Visual Studio 2005 and create a new Web Site (File > New > Web Site).   If the install was successful, you should have two new options under ‘My Templates.’  Select ‘ASP.NET CSS Friendly Web Site’ and specify the location where you want to save the web site, and select the language.  I’ve only tried Visual C# so I can’t validate these steps for Visual Basic.

3) Now that you’ve created a Web Site, you’ll need to create a new Project (File > New > Project) based on a ‘Class Library.’ 

In your new Project, you’ll need to copy some files from the Web Site that you created and saved in Step 2.  To do this, go to the project name in Solution Explorer, Right-click, then select Add > Existing Item.  Browse to the location of the Web Site saved previously and select all of the files from the App_Code\Adapters and App_Browsers folders.

You’ll also need to add references to System.Web and System.configuration.

4) Sign and Build your Class Library.

5) Copy the .dll that was created when you built your class library into the GAC (C:\Windows\Assembly).  This will register the .dll.

6) You may have noticed a file called ‘CSSFriendlyAdapters.browser’ that was added to the project.  Open the file and modify it so that it looks like this:

<browsers>

  <browser refID="Default">

      <controlAdapters>

<adapter controlType="System.Web.UI.WebControls.Menu" adapterType="CSSFriendly.MenuAdapter, CSSFriendlyControlsLib, Version=1.0.0.0, Culture=neutral, PublicKeyToken=<Your token>" />

</controlAdapters>

  </browser>

</browsers>

NOTE: The highlighted text represents the same of the .dll file installed in the GAC.  You can name your Project whatever you like, but the code in the .browser file must match.  The ‘PublicKeyToken’ value can be found by Right-clicking on the .dll in the GAC that you just installed and selecting ‘Properties.’  Copy and paste the Public Key Token into the .browser file.

7) Once you’ve made the changes to the .browser file, save the file. 

8) You’ll need to copy the .browser file to the following directory:

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\CONFIG\Browsers

9) Open the Visual Studio Command Prompt (Start > Programs > Microsoft Visual Studio 2005 > Visual Studio Tools > Visual Studio Command Prompt) and enter the following command:

aspnet_regbrowsers –i

IMPORTANT NOTE:  You’ll notice that if it was successful, the message will read that ASP.BrowserCapsFactory.dll has been successfully installed.  This is important because if you happen to do something that messes things up, the way to undo the damage is to delete the entry for this .dll from the GAC, remove your custom .browser file, then rerun the aspnet_regbrowsers –i command. 

10) Almost done.  But you’ll notice if you stop here, you’ll get a really fun error:

<SORRY LOST I LOST THIS IMAGE - MOSSMAN>

The final step is to go to ..\12\CONFIG\compat.browser and comment out the final four browser tags (ids: InfrawareSamSung, InfrawareLG, InfrawareSKY, InfrawareMotorola).  You’ll also need to make the change to compat.browser files in any SP sites in IIS that have been created previously (C:\Inetpub\wwwroot\wss\VirtualDirectories\<Your App Pool>\App_Browsers). 

That’s it!  It’s just that easy! 

A few final notes.  You’d have to make these changes on any web server that you plan to run the controls on.  You’d just have to drop the .dll into the GAC and modify and install the .browser files. 

And lastly – since nothing in SharePoint can be easy here’s the bad news.  If you try adding another line to the .browser file to enable the CSS Friendly Tree Control at first glance everything will work fine.  But if you try going to Site Actions > Manage Content and Structure you’ll get the dreaded SP error message (this is where the rollback method comes in handy!).  We are still in the process of trying to crack this nut, but as of now it looks like we are stuck.  If and when we find a solution we’ll post about that.

A big thanks to Bernie Johnsen for helping to get this working! 

-John Ross