MacawSharePointSkinner 1.0.0.1 released

Welcome to the MacawSharePointSkinner. MacawSharePointSkinner is a tool designed to enable non-intrusive modifications to the visual and functional design of SharePoint. The tool can be used for both Windows SharePoint Services 2.0 and for Microsoft Office SharePoint Portal Server 2003. Actually, it can be used for any web site utilizing the ASP.NET technology. Download at http://www.gotdotnet.com/Workspaces/Workspace.aspx?id=3ed68681-ae28-4d33-8c36-403e6af7fa11

One of the major issues that we encounter in the implementation of SharePoint within organizations is that organizations want modifications to the visual and functional design that are almost impossible to implement without a major overhaul of the standard files and templates provided with SharePoint. SharePoint is constructed as a kind of standard product that is best used out of the box. Some design can be applied by specifying themes (for team sites) or by modifying CSS stylesheets (for the portal). The possibilities here are limited however, and changes to the actual HTML that is rendered results in changes to hundreds of the standard files.

When implementing customer requested visual modifications, one of the big problems that we encountered in making extensive modifications to the files and templates delivered with SharePoint was that the rendering of the same HTML is implemented differently by different pages. Some pages contain the actual HTML that is outputted and can be easily modified. Other pages contain server controls that do the rendering of the same HTML. These pages are almost impossible to modify. Another problem is that modifications must often be made to hundreds of pages.

The approach that MacawSharePointSkinner takes is two-fold:

Text Replacements – MacawSharePointSkinner lets SharePoint render the final HTML, and just before this HTML is sent to the browser MacawSharePointSkinner makes the needed modifications to this HTML. This is done in such a way that no modifications are needed to the internal files of SharePoint, so it is non-intrusive. Another advantage is that it will survive service packs (although the output HTML may change in a service pack!) and template modifications.

Url Redirections – MacawSharePointSkinner can translate requested url’s into other url’s. This allows you to redirect standard SharePoint url’s to your own url’s.

MacawSharePointSkinner is implemented as an HttpModule that provides functionality for url replacements and powerful replacements in the HTML output rendered by SharePoint.

I will not describe the inner workings of an HttpModule, for more information have a look at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconhttpmodules.asp.

1         How to install MacawSharePointSkinner

1.1      Introduction

MacawSharePointSkinner is an HttpModule. HttpModules are configured in the web.config of your ASP.NET web site. SharePoint is an ASP.NET web site. The required DLL is installed in the Global Assembly Cache (GAC).

1.2      Procedure

Follow the steps below for installation:

1.3      Final step

The final step is to modify the MacawSharePointSkinner configuration file SkinConfig.xml.

1.4      Alternative configurations

This section describes some alternative configuration possibilities for the HttpModule dll, and for the used configuration files.

1.4.1      HttpModule dll deployment

The procedure described above deploys the Macaw.SharePoint.Skinner.dll to the global assembly cache. This deployment has the advantage that you only need one step to deploy the assembly and it is available in all virtual directories. Disadvantage is that an IISRESET is needed to activate the DLL.

If you don’t want to deploy Macaw.SharePoint.Skinner.dll to the global assembly cache, you need to deploy it to the following bin directories:

• C:\inetpub\wwwroot\bin (the path to the SharePoint virtual directory)
• C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\ISAPI\BIN (to keep FrontPage working, and have skinning support on the help pages)
• C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS\BIN (to have skinning enabled on all pages in the ‘/_layouts/’ directory)

1.4.2      Configuration files

It is possible to specify different configuration files for the different virtual directories in their corresponding web.config files. This allows for specific skinning configurations for the SharePoint virtual directory pages and the /_layouts virtual directory pages.

It is possible to specify a file pattern as a configuration file, instead of a single file. So for example if you specify c:\MacawSharePointSkinnerConfig\SkinnerSharePoint*.xml as configuration file in the web.config of the SharePoint virtual directory and  c:\MacawSharePointSkinnerConfig\SkinnerLayout*.xml in the web.config of the /_layouts virtual directory, you can have multiple configuration files to define your skinning operations. This is used in large Share Point modification projects where each subproject has its own configuration files. Note however that the configuration files are read in undefined order, so make the configuration files as independent as possible of each other. Especially overlapping URL redirections can lead to unpredictable behavior.

If order of interpretation of configuration files is important, it is also possible to supply multiple configuration files separated by ‘;’ characters. For example: c:\MacawSharePointSkinnerConfig\mefirst.xml; c:\MacawSharePointSkinnerConfig\restoffiles*.xml

2         MacawSharePointSkinner configuration

2.1      Introduction

Configuration of the MacawSharePointSkinner is done in an XML file named SkinConfig.xml. This file can be found in a directory called c:\MacawSharePointSkinnerConfig or another directory as defined in step 2 of the installation procedure defined in section 2.2. This file can be edited in any text editor like notepad or in a special XML editor[2].

Within the configuration file regular expressions[3] are used extensively to define match patterns.

2.2      Structure of the configuration file

The structure of the configuration file is unambiguously defined by the corresponding XSD schema SharePointSkinner.xsd.

In this chapter some configuration examples are given

2.3      Skinning language

This section describes the skinning elements that make up the skinning language. The elements are given, and their hierarchy. Between brackets the occurrence count is specified.

skinner (1)

            default-uri-matchtype (0,1)

cache-time (0,1)

parameters (0,1)

            parameter (1, n)

urlredirections (0,1)

            urlredirection (0,n)

rules (0,1)

            rule(0,n)

                        uris (1)

                                    uri (1,n)

                                                match (0,1)

parameters (0,1)

                                                            parameter (1, n)

                                                texts (0,1)

                                                            text (0,n)

                                                                        match (0,1)

parameters (0,1)

                                                                                    parameter (1, n)

                        blocks (1)

                                    block (1,n)

                                                match (0,1)

                                                            replacements (1)

                                                                        replacement (1,n)

                                                                                    find (1)

                                                                                    replace (1)

Below is a detailed description of the available elements.