Demystifying SharePoint CSS Links

Thereseems to be a lot of confusing, incomplete, or incorrect information(some of it from yours truly) out there about the choices available toyou when the time comes to create your own styles or override existingones so I thought I should shed a little light on the subject and talkabout the Web Controls that actually emit said <Link> elements.

SharePoint:CssLink and CssRegistration

Havea look at the default.master page in the GLOBAL site definition(12\Template\Global). You'll see a control named SharePoint:CssLink.

<HEAD runat="server">
    <META Name="GENERATOR" Content="Microsoft SharePoint">
    <META Name="progid" Content="SharePoint.WebPartPage.Document">
    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
    <META HTTP-EQUIV="Expires" content="0">
    <SharePoint:RobotsMetaTag runat="server"/>
    <Title ID=onetidTitle><asp:ContentPlaceHolder id=PlaceHolderPageTitle runat="server"/></Title>
    <SharePoint:CssLink runat="server"/>
    <SharePoint:Theme runat="server"/>
    <SharePoint:ScriptLink language="javascript" name="core.js" Defer="true" runat="server" />
    <SharePoint:CustomJSUrl runat="server" />
    <SharePoint:SoapDiscoveryLink runat="server" />
    <asp:ContentPlaceHolder id="PlaceHolderAdditionalPageHead" runat="server"/>
    <SharePoint:DelegateControl runat="server" ControlId="AdditionalPageHead" AllowMultipleControls="true"/>
</HEAD>

The CssLink Web Control renders <LINK> elements in this order:

  1. The primary CSS file (core.css)
  2. An optional CSS file specified by the control's DefaultUrl property
  3. Thevalue of the site definition's AlternateCSS attribute if one exists.(If you are using the MOSS publishing features, you can also set thisproperty for a single site by using the Site Master Page Settingspage.)

Note that the AlternateCSS attribute affects every page in the site, even the application pages.

Ifyou examine any of the master pages included in either of the MOSSpublishing site definitions, you will see another control,SharePoint:CssRegistration.

For example, the following code comes from OrangeSingleLevel.master:

<Sharepoint:CssLink runat="server"/>
<SharePoint:CssRegistrationname="<% $SPUrl:~SiteCollection/Style Library/~language/CoreStyles/SingleLevel.css%>" runat="server"/>
<SharePoint:CssRegistrationname="<% $SPUrl:~sitecollection/Style Library/~language/CoreStyles/controls.css %>" runat="server"/>
<SharePoint:CssRegistration name="<% $SPUrl:~SiteCollection/Style Library/zz1_orange.css%>" runat="server"/>

TheCssRegistration control adds each of the style sheets to an internalcollection in the SPContext and the CssLink renders each of them inalphabetical order before rendering the primary, default, and alternate CSS links. If you want one of them to appear after core.css, set the DefaultUrl property of CssLink.

So, if you want to ensure that zz1_orange.css appears after core.css, you would change the above to match the following:

<Sharepoint:CssLink runat="server" DefaultUrl="<% $SPUrl:~SiteCollection/Style Library/zz1_orange.css%>"/>
<SharePoint:CssRegistrationname="<% $SPUrl:~SiteCollection/Style Library/~language/CoreStyles/SingleLevel.css%>" runat="server"/>
<SharePoint:CssRegistrationname="<% $SPUrl:~sitecollection/Style Library/~language/CoreStyles/controls.css %>" runat="server"/>

It's very easyto get confused by this because the CssRegistration controls are afterCssLink, but they don't render the links, CssLink does!

Oneadvantage that the publishing definitions have over the WSSdefault.master is the $SPUrl expression that allows dynamic creation ofthe URL for sites under the root web that use the root web's masterpages. Unfortunately, while CssRegistration is part of the coreMicrosoft.SharePoint.dll, $SPUrl requires the publishing features ofMOSS.

Theme

On either of these master pages,somewhere under SharePoint:CssLink is SharePoint:Theme. The Theme WebControl just renders a <LINK> to the current theme if one isapplied (Default is actually the lack of a theme).

For example, here the rendered HTML source for a page on a site that has the Simple theme applied.


<link rel="stylesheet" type="text/css"

   href="/_layouts/1033/styles/core.css"/>

<link rel="stylesheet" type="text/css"

   id="onetidThemeCSS"

   href="/sites/y/_themes/simple/simp1011-65001.css"/>

Notethat the href points, not to the 12 hive, but to the site's _themesfolder. When a user applies a theme, the themes files are copied to thesite to allow customization.

Also note that like AlternateCSS, themes affect the application pages.

Summary

So, to summarize the rendering order on a MOSS publishing site page is:

  1. The CssRegistration entries in alphabetical order
  2. Core.css
  3. The value of the CssLink Web Controls DefaultUrl property if one is specified
  4. The AlternateCSS if one is specified
  5. The current theme if there is one

Ifyou want to add your own HTML <LINK> by hand bypassing any ofthese and want to be sure it comes last, simply place it after bothSharePoint:CssLink and SharePoint:Theme.

--Doug Ware