Branding WSS Sites by Using CSS Files

In the final section of this chapter, we will discuss a few additional topics that are relevant to branding sites. First, we will examine how WSS uses Cascading Style Sheets (CSS) and discuss how to extend this support in a custom branding solution. We will then examine how to replace the image used in the standard WSS page banner by using a custom graphics file.

Understanding core.css

The look and feel of every WSS site is controlled through a standard set of CSS files. The WSS team created a separate set of CSS files for each spoken language supported by WSS. You can find the standard CSS files that are localized for US English at the following path within the WSS TEMPLATE directory.

 \TEMPLATE\LAYOUTS\1033\STYLES\

The file that defines the majority of the standard CSS classes used by pages in WSS is named core.css. WSS was designed so that every site page and every application page is automatically linked to core.css. The support for setting up these links is included in a WSS-specific control named CssLink shown earlier in this chapter. The CssLink control contains logic to link the current page to the most appropriate localized version of core.css. This decision is made by examining the regional settings for the current site and also determining what language packs are installed within the farm.

If you have never looked inside core.css, you should make a copy of this file and examine what’s inside. This exercise is somewhat intimidating at first because core.css contains over 4,000 lines of CSS class definitions. However, understanding which CSS classes are defined by the WSS team and learning where they are used becomes an essential aspect of branding WSS sites.

It’s important to understand that the core.css file is scoped at the farm level. Changes made to core.css affect every site in the farm; therefore, this is not a file that you should customize. Furthermore, the team at Microsoft responsible for creating updates to WSS reserves the right to install an updated version of core.css in future service packs, and such an action would overwrite any changes you make to core.css today.

WSS provides two recommended techniques for extending the CSS classes defined inside core.css. The first approach involves the use of WSS themes and is targeted at end users. The second approach is targeted at developers and involves creating a secondary CSS file to extend and override the CSS classes defined inside core.css.

WSS Themes

WSS allows users to quickly change the look and feel of a WSS site by changing its theme. The WSS support for changing themes is supplied by a standard application named themeweb.aspx that is accessible through a link on the Site Settings page.

Each theme is defined within its own directory on the front-end Web server. Themes are located in a THEMES directory within the TEMPLATE directory. For example, the built-in theme named Citrus is defined by a set of files residing in the following directory.

 TEMPLATE\THEMES\CITRUS

If you examine the directory for a theme, you find that it includes CSS files and graphics files. When a user chooses a theme, WSS copies all of these files up into the site, including a primary CSS file. WSS also adds a link to the primary CSS file to each application page and each site page. Note that this link is always added after the link to core.css so that CSS classes inside the theme’s CSS file override CSS classes defined inside core.css.

Once a user applies a theme to a site, the CSS files can be further customized by using the SharePoint Designer. For example, you can open a site that already has a theme applied in the SharePoint Designer and open the primary CSS file. Any changes you make to this CSS file are stored as ordinary customization with the content database.

From a design perspective, you should observe that themes are targeted more toward end users than developers. While you can create custom themes and deploy them in a WSS environment, the main idea is that themes are added to WSS to support the ability of users to enable or disable them on demand. If you want a site to have specific branding without giving the user control over enabling or disabling it, you should use a custom CSS file as shown in the next section.

AlternateCSS Property

It’s fairly easy to integrate a custom CSS file into a custom branding solution. The Visual Studio project named CustomBranding that accompanies this chapter provides an example of how to accomplish this by copying a custom CSS file named LitwareBrand.css and some accompanying graphics files to the following directory.

 TEMPLATE\LAYOUTS\1033\STYLES\Litware

You simply need to update an SPWeb property named AlternateCssUrl in each site where you want to apply your custom theme. Note that when you apply a custom CSS file, it’s also a good idea to disable any theme applied by a user so that the CSS classes from a theme do not conflict with the ones defined in your custom CSS file. As shown in the following example, you can see that this step doesn’t take much code to accomplish.

  SPWeb site = SPContext.Current.Web; site.ApplyTheme(""); site.AlternateCssUrl = "/_layouts/1033/STYLES/Litware/LitwareBrand.css"; site.Update(); 

Site Icon

In addition to supporting custom CSS files, WSS also provides a property so that you can substitute the standard WSS banner image with one more appropriate for your brand. The CustomBranding project contains a graphics file named LitwareFullLogo.png. This file is deployed inside the TEMPLATE\IMAGES directory in the following location.

 TEMPLATE\LAYOUTS\Litware\LitwareFullLogo.png

It takes a few lines of code to replace the standard WSS site logo with your own.

  SPWeb site = SPContext.Current.Web; site.SiteLogoUrl = "/_layouts/images/Litware/LitwareFullLogo.png"; site.Update(); 

Best Practices for Site Branding

You have encountered several different techniques for adding custom branding to a site. The CustomBranding project provides a feature scoped to the site collection level that allows you to apply all of these branding techniques to all sites within a site collection. We will now examine all code behind the command button in the application page named CustomBrand.aspx. This example extends what was shown earlier by adding extra code so as to add a custom style sheet and custom site log, in addition to redirecting all of the site pages so that they link to Litware.master.

  protected void cmdApplyCustomBrand_Click(object sender, EventArgs e) {   SPWeb site = SPContext.Current.Web;   string MasterUrlPath = site.ServerRelativeUrl;   if (!MasterUrlPath.EndsWith(@"/"))     MasterUrlPath += @"/";   MasterUrlPath += @"_catalogs/masterpage/Litware.master";   ApplyCustomBrand(MasterUrlPath, site);   Response.Redirect(Request.RawUrl); } protected void ApplyCustomBrand(string MasterUrlPath, SPWeb site) {   site.MasterUrl = MasterUrlPath;   site.ApplyTheme("");   site.AlternateCssUrl = "/_layouts/1033/STYLES/Litware/LitwareBrand.css";   site.SiteLogoUrl = "/_layouts/images/Litware/LitwareFullLogo.png";   site.Update();   // use recursion to update all sites in site collection   foreach (SPWeb child in site.Webs) {     ApplyCustomBrand(MasterUrlPath, child);   } } 

The CustomBranding project provides the code to enable and disable custom branding for a site collection through an application page with command buttons. However, you can extend this example and add the same code to the FeatureActivated event handler so that branding is applied whenever the CustomBranding feature is activated. You can even take this example one step further by writing code to enumerate every through site collection in a farm and activate the CustomBranding feature in each of these site collections along the way.

One final observation that we want you to make is that some branding techniques work across both site pages and application pages, which is the case for both the custom CSS file applied by using the AlternateCssUrl property as well as the site logo that can be replaced by using SiteLogoUrl. This occurs because support for these items is included in both the standard application.master template and the default.master template. However, the technique shown in this chapter for branding sites with a custom master page doesn’t extend to application pages. Therefore, you might decide to do as much branding as possible by using CSS files and the replaceable site logo.