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 UPDATE: can now be found at http://www.codeplex.com/SharePointSkinner.

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.

When it is specified to specify text in a CDATA section to prevent invalid XML, use the following syntax: <![CDATA[text]]>

3         Advanced Skinner configurations

Pages are skinned by the skinner if the following conditions are met:

• The page request is in a ASP.NET virtual directory
• The web.config file contains the Macaw.SharePoint.Skinner HTTP module
• The page request returns content of type text/html

If you have a page that returns for example XML (content type is text/xml) the page is NOT skinned.

If you don’t want a page to be skinned (and no comments added tot the top, even if there is no URL match), you can add skinnerskip=1 to the query string.

Example: http://server/default.aspx?skinnerskip=1

4         Regular expressions

4.1      Introduction

Matches, selections, finds and replacements are all done using regular expressions. There are multiple flavors available in regular expressions. MacawSharePointSkinner uses the .Net flavor. For more information on regular expressions have a look at:

4.2      Regular expression matching configuration

All regular expression matches performed in MacawSharePointSkinner are done with the following options enabled:

IgnoreCase              Specifies case-insensitive matching.

Multiline                  Specifies multiline mode. Changes the meaning of ^ and $ so that they match at the beginning and end, respectively, of any line, not just the beginning and end of the whole string.

CultureInvariant     Specifies that cultural differences in language is ignored.

To increase the performance of matching, all regular expressions are compiled when the configuration file is read.

4.3      Tools for regular expression construction

When constructing regular expressions I always utilize a regular expression construction tool. These tools allow you to specify a source text (use the ‘view source’ text of the page you want to do replacements on), a regular expression (including captures) and a replacement. The tool visualizes the matches in the text and the resulting text after the replacement.

See http://www.larkware.com/RegexTools.html for an overview of available tools. One of my favorites in “The regulator” (http://regulator.sourceforge.net).

4.4      Tips & tricks

This section contains some tips and tricks in smart regular expressions to perform skinning tasks.

4.4.1      Block selection of head

In one situation we had to replace the stylesheets within the head. These are four replacements. To improve replacement speed the replacements are done on a block that matches only the head section. The head can be matched as follows:

5         Using MacawSharePointSkinner

There are many, many usages for the MacawSharePointSkinner. Some examples of the usage of the MacawSharePointSkinner are:

• Apply different style sheets to different areas in the portal area tree.
• Remove system account from the “Assigned to:” dropdown boxes in the new and edit pages of certain lists (issues, tasks).
• Redirect access to certain pages in the /_layouts directory to your own, modified, versions of these pages.

5.1      Url redirections

Url redirections in SharePoint works different from url redirections with normal ASP.NET applications. SharePoint uses special handling of url’s, because it uses a kind of “in context” page access. Examples are the pages in the /_layouts virtual directory. If you request the url http://servername/sites/mysite/_layouts/1033/aclinv.aspx, you actually access the page /_layouts/aclinv.aspx, but in the context of the SharePoint site mysite.

Due to special handling in SharePoint, we also have to take this into account in specifying the url redirections.

If you want to redirect the page /_layouts/1033/aclinv.aspx to /_layouts/my1033/aclinv.aspx, do the following:

This redirection is performed “in context”, so in the destination page we are still in the same context.

If you want to redirect all access to the “in context” page /_layouts/1033/aclinv.aspx (for example http://servername/sites/mysite/_layouts/1033/aclinv.aspx and http://servername/sites/othersite/_layouts/1033/aclinv.aspx) to a page NOT in /_layouts, the complete url of the destination page must be specified, and the permanent attribute must be set to true (if target is full url, permanent is automatically set to true).

If you only want to redirect all access to the page http://servername/sites/mysite/_layouts/1033/aclinv.aspx (so NOT access to all /_layouts/1033/aclinv.aspx pages in any context), a complete url of both the target and destination page must be specified, and the permanent attribute must be set to true (if target is full url, permanent is automatically set to true).

6         Frequently Asked Questions

Q: MacawSharePointSkinner works great in my SharePoint sites and in the portal, but not for the pages in the /_layouts virtual directory. It also does not work for the help pages of SharePoint.

A: See section 2.2 for information on how to modify the web.config file to add the HttpModule. The procedure to add it to the /_layouts virtual directory is included in this section. For each virtual directory you want to skin you have to modify the web.config file. So for

Portal/Wss:

/_layout:

/_vti_bin (help pages):