Microsoft Office SharePoint Server 2007 – Custom Chrome / Branding
PREFACE
If the graphics snapshots do not paste over in this document (to the blog) please feel free to email me, including an email address for yourself, and I will send you this final draft, in MS Word format, including all graphics/screenshots.
REVIEW
After deploying MOSS and my first site collection, obviously the first thing I want to know is how can I customize the look and feel?
Thus begins my journey down Chrome Lane and my first of a multi-part series on customizing the look and feel of WSS v3 / MOSS 2007 sites (v3 bits / sites).
As you have no doubt read and heard several times, v3 sites leverage the .Net 2.x Framework and implement master / content pages. Whether you are new to, or seasoned with this approach, I hope the following provides some insight into the ways you can customize your v3 sites.
Foremost, this approach is a simplified example of customizing and the approach is 1 of many you can take. This approach is not exhaustive and certainly not applicable to all v3 deployments. Please allow me to explain…
MOSS provides many feature-rich templates for each optional site collection you can deploy under a web application (a web application is an IIS web application, and previously referred to as a virtual server in v2 days). If you deploy a Team Site, or Internet Presence Site, each of these provides the developer a set of templates that can be used / customized further for that site collection. It is important to note here that the actual templates provided are different from 1 site collection to another. Why is this important? For this presentation, the customization that we are going to do will be specific to the master page provided for the template of the site type. More specifically, if you deploy a Blank Site or a Internet Presence Site, the templates for the master pages will be different, and you will have to understand these differences to apply this approach to each of the different sites. Let’s get started and you will see what I mean.
CHROME LANE
We are going to deploy a web application and 1 site collection for that web application. Here we will work with the My Company Site, and the site collection is an Internet Presence Web Site template-base.
As we proceed I will reveal the out-of-the-box templates and setup derived from publishing this site template.
I could proceed on the predicate that you can create a web application and the site collection for that web application – but I’ll walk through this piece by piece. Please forgive the lengthy posting and the many screen shots – I simply want to try and be as thorough as possible.
ASSUMPTIONS
MOSS 2007 is installed and configured on your server. Further, you have configured the services that should be running on this server. If you are not familiar with these, please review the following screenshot and ensure that you have at least these services running (you get to this screen by opening the Central Administrator and clicking the server name under Farm Topology.
Ensure that your services are started – as indicated in the above figure.
Finally, we are going to customize our site by placing a banner object in the titleArea (we’ll get into this when we open the SharePoint Designer and begin to customize the template), and we are going to customize the toolbar. To do these things we have created custom graphics – 1 for the banner display, and 1 for the toolbar – which is a small GIF image, 40px high that we’ll repeat-x across the toolbar space – basically overriding the default out-of-the-box GIF used by SharePoint.
We will begin by creating our web application on a specified port on this server.
THE FUN BEGINS!
Launch the SharePoint Central Administrator. Click on Application Management.
Under SharePoint Web Application Management choose the first option Create or extend Web application.
On the next screen click Create a new Web Application.
In the IIS Web Site section, fill in the Description field with My Company Site, and for the Port set it to 10000.
In the Security Configuration section, set the Allow Anonymous: to Yes.
In the Application Pool section, set the Create new Application Pool / Application Pool Name to MyCompanySite.
Under Select a security account for this application pool, select Configurable and enter the User name and password fields appropriately. I used the Administrator account.
You can accept the rest of the default properties, scroll the page to the bottom, and click OK. This may take up to several minutes to create the web application.
When the web application is created, you will see a screen similar to the following:
We want to click the first link Create a new Windows SharePoint Service web collection.
The Web Application will be on the machineName:port we created it on.
For the Title and Description enter My Company Site.
Under Web Site Address change the radio button from the default of Create site under this URL: (URL Name) to the 2nd option Create site at this URL: (URL path:) and leave the (root) path. (I will go into this in more detail in another post.)
For this exercise, under Primary and Secondary Site Collection Administrator enter the Administrator account.
Under Template Selection select Internet Presence Web Site and click OK.
It may take several minutes for the site collection to be created. Once it is complete let’s browse to our new site root. We do this by browsing to http://machineName:10000 – where machineName is the name of the server you have installed MOSS on. If all went well and you have browsed to the new site, your screen should be similar to the following:
If you select the top-right Site Actions drop-down, and select Edit Page you will see a template that provides a Page Image and two Summary Links content panes, as well as three webpart zones. This page is derived from the WelcomeSplash.aspx. I can confirm this by selecting Site ActionsàManage Content and Structure and then selecting Pages in the left treeview. On the right I’ll see a default.aspx and to the far-right, you’ll see the template it derived from. We are not going to get into modifying templates in this posting, but I wanted to help you understand some of the out-of-the-box aspects and how your template was created by default.
I want to review one more thing before we begin. SharePoint also uses a default master page and set of style sheets for this site. To see what the default master page is, select Site ActionsàSite SettingsàModify All Site Settings.
Under Look and Feel click Site Master Page Settings.
Under Site Master Page notice that our master page is TopNavFlyOuts.master. We will do some customization here to implement our custom look and feel. Scroll this page down and notice under Alternate CSS URL there is a style sheet referenced called Blue.css. We are going to be replacing this as well.
Out-of-the-box, the Blue.css is an empty file that we can edit and use to override some of the classes that drive the master page TopNavFlyouts.master (Top Nav). Top Nav has a style sheet called TopNavFlyouts.css that is used when the master page is rendered.
For now, select Site ActionsàManage Content and Structure. In the left treeview, expand Style Library, then en-us, finally, select Core Styles. Your screen should look similar to the following:
Notice that we have some out-of-the-box style sheets, and one of these is TopNavFlyouts. What is important to understand is that we have to create a new style sheet, in this Core Styles library so we can override some of the classes in the Top Nav style sheet.
We do not want to edit the Top Nav style sheet directly, but rather, create our own style sheet and override the classes that we’ll need to implement our customizations. Also, we’ll create a couple new classes in our style sheet that will handle the banner and default background images / colors.
For this exercise, I created a my.css text file with the following in it:
This has my color for the main background, and my banner properties. The three graphics that I will be using are for the banner, toolbar, and the toolbar hover/selected images.
We’ll include a custom footer in this setup and that’s why I have the my–spacerX and my–footer classes included.
My banner is 785px by 200px, and my toolbar images are 4px by 40px each. These are shown below:
my-toolbar.gif
my-toolbar-hoverselected.gif
Each of these graphics and my my.css style sheet need to be uploaded to SharePoint before we can begin to customize our Top Nav master page.
To do this, back in SharePoint under Site Content and Structure with Core Styles still selected on the left, in the right pane, click NewàItem to upload our style sheet.
On the Upload Document: Style Library page, click Browse to browse to where you saved your my.css object. Once you have selected your file, click OK and you should see a screen similar to the following:
Here we enter a Title for our style sheet, and click Check In. You will be returned to the Core Styles and you’ll notice our new style sheet in the library.
Notice in the above image, under Style Library there is an Images folder. There is also one under the en-us folder. We want to select the one that’s actually under Style Library, not en-us. Once selected, we need to select New-->Item and here we are going to upload multiple items – our banner and two toolbar objects.
When you get to the Upload Document: Style Library screen, below the Name textbox for the image, you’ll see a link for Upload Multiple Files… - click this to browse for the banner and toolbar objects.
Once these are selected, click OK to begin the upload process. You will be prompted to confirm the upload and you will want to click Continue.
Once the upload is completed you will be returned to the Site Content and Structure-->Style Library-->Images view. You want to scroll down and find our three new images, and click the box to the left of each image to select them. Once selected, select Actions from the menu, and select Check In (be sure to select Publish Major Version as well).
When prompted for comments about the check-in, enter My Company SIte Images and click OK.
Once this is done, in the upper-left area of your screen click My Company Site to return to the root site.
We are now ready to being our customization of the master page and override the classes from the Top Nav style sheet.
To perform these next steps you will need the SharePoint Designer 2007 installed.
Launch SharePoint Designer (SPD) and select FileàOpen Site, then type in the URL for our new site (http://<machineName>:10000).
You should see a screen similar to the following once you are connected to the site with SPD:
In SPD, under Folder list expand _catalogs, then masterpage, and locate and double-click on TopNavFlyouts.aspx. When prompted to Check Out the object, click Yes and continue.
If this is the first time you have worked on this site with SPD you will be restricted from editing code at first. Do the following to resolve this:
From the menu bar select SiteàContributor Settings and you will see a dialog like the following:
In the upper Manage Contributor Groups region, select Content Authors (Default) and click Modify.
You should see a screen like the following:
From here click / enable Allow unrestricted use of SharePoint Designer and click OK. Click OK again to return to SPD with full editing capabilities.
When you return the SPD the Web Site tab is rendered. Click on the TopNavFlyouts.aspx tab to render that page. In the lower region of your designer form you’ll see Design Split Code. Click on Split and you should see something similar to the following:
We want to load our custom my.css style sheet, and the TopNavFlyouts style sheet now too. In the Folder list browse down to Style Libraryàen-us (Style Library)àCore Styles (Style Library). Double-Click our my.css object. When prompted to check-out the item, click Yes. Now double-click the TopNavFlyouts.css, but when prompted to check-out, click No.
OVERRIDING STYLES
The TopNavFlyouts.css library is used for the TopNavFlyouts.aspx master page – which you have probably already assumed. For this example, we will want to override some of the classes in this style sheet. And to do this, we copy and paste those classes into our my.css object. Yes, we can certainly get more involved and complex in our chroming / customization – but for this walk-through I am trying to keep this pretty simple / straight-forward. Soon you will see where our my.css object gets configured in SharePoint and you will understand why I took this approach.
Remember, our image is 200px high by 785px wide. By default, the Top Nav area renders by percentage, and at 100%. We will need to change this so that our screen aligns with our banner. Again, this is for this customization only – and you can play with this in a number of different ways, depending on your customization and whether or not you are introducing custom graphics or navigation.
For now, locate, and copy / paste the following classes from TopNavFlyouts.css to our my.css:
.body
.master
.search td
.search
.topNavContainer
.topNavItem
.topNavItem a
.topNavSelected a
.topNavHover a
.topNavFlyouts
.topNavFlyOutsItem
.topNavFlyOutsItem a
.topNavFlyOutsHover
You should now have a my.css object that contains the following – before any customizations have been implemented:
.my-mainbackground
{
background-color: #B4BC97;
background-image: url(../images/blog-background.jpg);
}
.my-mainbanner
{
background-image: url(../images/blog-header.jpg);
background-color: #768365;
height: 200px;
border: 0px;
}
.my-spacer5
{
height: 5px;
}
.my-spacer10
{
height: 10px;
}
.my-footer
{
background-color: #B4BC97;
height: 15px;
border: 0px;
text-align: center;
font-family: Verdana;
font-size: 11px;
font-style: italic;
font-weight: normal;
color: #ffffff;
}
.body
{
background-color:#596E9E;
height:100%;
margin:0px;
}
.master
{
width:950px;
margin-left:auto;
margin-right:auto;
height:100%;
background-color:#FFFFFF;
}
.search td
{
font-family:tahoma;
font-size: 8pt;
color: #3A4663;
}
.topNavContainer
{
background-image:url("../../images/bl_Navbar_Gd_Default.jpg");
background-repeat:repeat-x;
height:40px;
}
.topNav
{
*position:relative;
*top:-1px;
}
.topNavItem
{
background-image: url('../../Images/bl_Navbar_Splitter.jpg');
background-repeat:no-repeat;
background-position:top right;
font-family: tahoma;
font-size: 8pt;
color: #294C7A;
}
.topNavItem a
{
display:block;
padding:8px 5px 0px 5px;
height:32px;
}
.topNavSelected a
{
background-image: url('../../Images/bl_Navbar_Gd_Hover.jpg');
background-repeat:repeat-x;
background-position:top right;
color: #EFF4FA;
}
.topNavHover a
{
color:#FFFFFF;
background-image: url('../../Images/bl_Navbar_Gd_Hover.jpg');
background-repeat:repeat-x;
background-position:top right;
}
SHOW ME THE CHROME!!!
Now the fun begins!
We’ll step through the change for each class, and then we’ll modify a few things in our master page and step back and see how things render.
1) .body, and .master – Change color to #B4BC97
2) .search td – change Color to #3A4663.
3) .search – Remove top:-2px; altogether.
4) .topNavContainer – change background-image: to ‘../../my-toolbar.gif’
5) .topNavItem a – Change padding to 12px 5px 0px 5px, and change the height to 40px.
6) .topNavSelected a – Change the background-image URL to ../../Images/my-toolbar-hoverselected.gif'.
7) .topNavHover a – Change the background-image URL to ../../Images/my-toolbar-hoverselected.gif'.
APPLY THE STYLE SHEET
Before we proceed, let’s apply our custom style sheet to the site collection so we can see our progress thus far.
To do this, select Site ActionsàSite SettingsàModify All Site Settings.
Under Look and Feel select Site Master Page Settings.
Scroll down to Alternate CSS URL and ensure that the following is entered:
/Style Library/en-us/Core Styles/my.css
Click OK to apply the setting.
MASTER PAGE CUSTOMIZATION
We are now ready to do the final modifications to our master page.
Locate the line just below the beginning of the <body> tag that looks like
<table cellpadding=”0” cellspacing=”0” class=”master”>
Just below this replace the class reference of shadowLeft with my-background
Your screen should look similar too:
TIP – It’s important to remember that this walk-through deals with a specific template and as you venture into the area of chroming and customization, you will not do everything the same.
FINAL STEPS…
Just below our my-background, within the table def. that includes masterContent, change the width to 785 and add an align statement like the following:
- Modify the table def. below this line to include align=”center” width=”785”
See below:
The highlighted areas include the changed content:
Now, we need to remove the Title Area icon, and class, and insert our banner. Scroll down in the code view and locate the topArea class. Look at the snapshot below – you want to select the two lines below the topArea and delete those. Then we’re going to replace the top area class:
Now, change the topArea class reference to my-header the name of the class which defines our new banner. The following reflects these changes:
Now, scroll down to where the table definition and class reference for the topNavContainer are. Just below this is the reference to topNavRoundLeft, and below that is a table definition with only a valign attribute setting. Here we want to change the attribute to valign=”center”, and add an align=”left” in table definition. (This is necessary because we added the align=”center” earlier in our changes, and we’ll need to address the navigation, breadcrumb, and left navigation text being left justified vs. centered.)
Next, scroll down to the <div class=”breadcrumb”> statement, and add align=”left” at the end of “breadcrumb”.
The following screenshots show these latest changes.
Now, locate the table def. just above the div class=”mainContainer” line, and change the width from 100% to 785.
In the line with class=”mainContainer” add a align=”left” to this line (just after the “mainContent” part.
Finally, locate the table def. just below this that includes the class reference for shadowRight and replace shadowRight with my-background. Save your changes.
Your screen should reflect changes similar to that shown below:
Finally, let’s add a custom footer to our page. Just below the </tr> and just before the final </table> tags, insert the following code:
<!-- Custom Footer... -->
<tr>
<td colspan="3" class="my-background">
<table width="100%">
<tr><td class="my-spacer10"></td></tr>
<tr><td class="my-footer">Copyright (C) 2006 – My Company Site</td></tr>
<tr><td class="my-spacer10"></td></tr>
</table>
</td>
</tr>
Save the TopNavFlyOuts.master page. Once this is saved, right-click on the master page in the Folder List in Designer, and select Check-In.
When the check in dialog appears, be sure to select Publish Major Version. You should see something similar to the following:
Click OK to check-in and publish a major version (otherwise you will not see your changes immediately).
Next you should see a dialog like the following:
Click YES to proceed.
You will get to the Master Page Gallery (MPG) for your site, and see a screen similar to the following:
Hover over the Top Nav page that is in Pending status, and select Approve/reject. When you get to the approval page, you will want to ensure you click Approve before submitting. You should have a screen similar to the following:
Click OK to finalize this process.
If all has gone well, your home page should be similar to the following:
This concludes a basic chroming / customization approach. Yes, there are certainly more robust things that can be done – and hopefully this opens the door for some ideas!
NOTES
If something is not rendering properly, it is usually because something is not checked in and published fully. This will become a nuance you’ll get used to quickly J.
I am pasting the following graphics and complete source code to help you just in case you need them. The graphics are our images (4 total) that we used for the main banner, toolbar, toolbar-hoverselected, and finally, the background.
The source is the my.css first, followed by the complete topnavflyouts.master XSL code-behind (if such a thing is a valid way to state it).
GRAPHICS
Main Banner
Background
Toolbar
Toolbar – hoverselected
MY.CSS
.my-background
{
background-color: #B4BC97;
background-image: url(../images/my-background.jpg);
}
.my-header
{
background-image: url(../../images/my-header.jpg);
background-color: #768365;
height: 200px;
border: 0px;
}
.my-topmenu
{
background-image: url('../../images/my-toolbar.gif');
background-color: #f9da5d;
height: 40px;
boarder: 0px;
text-align: left;
vertical-align: top;
padding-top: 10px;
padding-bottom: 5px;
padding-left: 10px;
padding-right: 10px;
font-family: Verdana;
font-size: 11px;
font-style: normal;
font-weight: bold;
text-decoration: none;
color: #ffffff;
}
.my-spacer5
{
height: 5px;
}
.my-spacer10
{
height: 10px;
}
.my-footer
{
background-color: #B4BC97;
height: 15px;
border: 0px;
text-align: center;
font-family: Verdana;
font-size: 11px;
font-style: italic;
font-weight: normal;
color: #ffffff;
}
.body
{
background-color:#B4BC97;
height:100%;
margin:0px;
}
.master
{
width:950px;
margin-left:auto;
margin-right:auto;
height:100%;
background-color:#B4BC97;
}
.search td
{
font-family:tahoma;
font-size: 8pt;
color: #3A4663;
}
.search
{
float:right;
font-size: 8pt;
margin-left:5px;
margin-right: 0px;
position:relative;
}
.topNavContainer
{
background-image:url("../../images/my-toolbar.gif");
background-repeat:repeat-x;
height:40px;
}
.topNav
{
*position:relative;
*top:-1px;
}
.topNavItem
{
background-image: url('../../Images/bl_Navbar_Splitter.jpg');
background-repeat:no-repeat;
background-position:top right;
font-family: tahoma;
font-size: 8pt;
color: #294C7A;
}
.topNavItem a
{
display:block;
padding:12px 5px 0px 5px;
height:40px;
}
.topNavSelected a
{
background-image: url('../../Images/my-toolbar-hoverselected.gif');
background-repeat:repeat-x;
background-position:top right;
color: #EFF4FA;
}
.topNavHover a
{
color:#FFFFFF;
background-image: url('../../Images/my-toolbar-hoverselected.gif');
background-repeat:repeat-x;
background-position:top right;
}
TOPNAVFLYOUTS.master
<%@ Master language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Register Tagprefix="SPSWC" Namespace="Microsoft.SharePoint.Portal.WebControls" Assembly="Microsoft.SharePoint.Portal, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="PublishingWebControls" Namespace="Microsoft.SharePoint.Publishing.WebControls" Assembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="PublishingNavigation" Namespace="Microsoft.SharePoint.Publishing.Navigation" Assembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register TagPrefix="wssuc" TagName="Welcome" src="~/_controltemplates/Welcome.ascx" %>
<%@ Register TagPrefix="PublishingVariations" TagName="VariationsLabelMenu" src="~/_controltemplates/VariationsLabelMenu.ascx" %>
<%@ Register Tagprefix="PublishingConsole" TagName="Console" src="~/_controltemplates/PublishingConsole.ascx" %>
<%@ Register TagPrefix="PublishingSiteAction" TagName="SiteActionMenu" src="~/_controltemplates/PublishingActionMenu.ascx" %>
<html dir="ltr" runat="server" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:msdt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882">
<head runat="server">
<META name="WebPartPageExpansion" content="full">
<meta name="GENERATOR" content="Microsoft SharePoint" />
<meta http-equiv="Content-Type" content="text/html" />
<meta http-equiv="Expires" content="0" />
<title id="onetidTitle">
<asp:ContentPlaceHolder id="PlaceHolderPageTitle" runat="server"/>
</title>
<Sharepoint:CssLink runat="server"/>
<!--Styles used for positioning, font and spacing definitions-->
<SharePoint:CssRegistration name="<% $SPUrl:~sitecollection/Style Library/~language/Core Styles/TopNavFlyouts.css %>" runat="server"/>
<SharePoint:CssRegistration name="<% $SPUrl:~sitecollection/Style Library/~language/Core Styles/controls.css %>" runat="server"/>
<SharePoint:ScriptLink language="javascript" name="core.js" runat="server"/>
<SharePoint:ScriptLink language="javascript" name="ows.js" runat="server"/>
<!--Placeholder for additional overrides-->
<asp:ContentPlaceHolder id="PlaceHolderAdditionalPageHead" runat="server"/>
</head>
<body class="body" onload="javascript:_spBodyOnLoadWrapper();">
<WebPartPages:SPWebPartManager runat="server"/>
<form runat="server" onsubmit="return _spFormOnSubmitWrapper();">
<table cellpadding="0" cellspacing="0" class="master">
<tr>
<td height="100%" class="my-background" />
<td valign="top">
<table cellpadding="0" cellspacing="0" align="center" width="785" class="masterContent">
<tr>
<PublishingWebControls:AuthoringContainer id="authoringcontrols" runat="server">
<td colspan="2" width="100%" class="authoringRegion">
<span class="siteActionMenu">
<PublishingSiteAction:SiteActionMenu runat="server" />
</span>
<div class="sharepointLogin">
<!--Authentication for Authors only-->
<table cellpadding="0" cellspacing="0" >
<tr>
<td><SharePoint:DelegateControl ControlId="GlobalSiteLink1" Scope="Farm" runat="server"/></td>
<td><SharePoint:DelegateControl ControlId="GlobalSiteLink2" Scope="Farm" runat="server"/></td>
<td><wssuc:Welcome id="explitLogout" runat="server"/></td>
</tr>
</table>
</div>
<div class="console">
<PublishingConsole:Console runat="server" />
</div>
</td>
</PublishingWebControls:AuthoringContainer>
</tr>
<tr>
<td colspan="2" >
<table cellpadding="0" cellspacing="0" width="100%">
<tr>
<td colspan="4" class="my-header">
<PublishingNavigation:PortalSiteMapDataSource ID="SiteMapDataSourceRoot" Runat="server"
SiteMapProvider="CombinedNavSiteMapProvider" EnableViewState="true"
StartFromCurrentNode="true" StartingNodeOffset="0" ShowStartingNode="true"/>
<div class="topLinkBar">
<div class="topLink">
<PublishingVariations:VariationsLabelMenu id="labelmenu1" runat="server"/>
</div>
<PublishingWebControls:AuthoringContainer id="VisibleToReaders" DisplayAudience="ReadersOnly" runat="server">
<div class="login">
<asp:ContentPlaceHolder id="PlaceHolderLogin" runat="server">
<!--End user login for forms authentication-->
<asp:LoginStatus id="formsAuthLogin" LoginText="<%$Resources:cms,masterpages_logincontrol_label%>" LogoutText="<%$Resources:cms,masterpages_logoutcontrol_label%>" LogoutAction="RedirectToLoginPage" runat="server"/>
</asp:ContentPlaceHolder>
</div>
</PublishingWebControls:AuthoringContainer>
</div>
</td>
</tr>
<tr class="topNavContainer">
<td class="topNavRoundLeft" />
<td valign="top" align="left">
<SharePoint:AspMenu ID="GlobalNav" Runat="server" DataSourceID="SiteMapDataSource1"
Orientation="Horizontal" StaticDisplayLevels="1" MaximumDynamicDisplayLevels="1"
StaticSubMenuIndent="0" DynamicHorizontalOffset="0" DynamicVerticalOffset="-8"
StaticEnableDefaultPopOutImage="false" ItemWrap="false" SkipLinkText="<%$Resources:cms,masterpages_skiplinktext%>" CssClass="topNav">
<StaticMenuItemStyle CssClass="topNavItem" ItemSpacing="0"/>
<StaticSelectedStyle CssClass="topNavSelected" ItemSpacing="0"/>
<StaticHoverStyle CssClass="topNavHover"/>
<DynamicMenuStyle CssClass="topNavFlyOuts" />
<DynamicMenuItemStyle CssClass="topNavFlyOutsItem" />
<DynamicHoverStyle CssClass="topNavFlyOutsHover"/>
</SharePoint:AspMenu>
<PublishingNavigation:PortalSiteMapDataSource ID="siteMapDataSource1" Runat="server"
SiteMapProvider="GlobalNavSiteMapProvider" EnableViewState="true"
StartFromCurrentNode="true" StartingNodeOffset="0" ShowStartingNode="false">
</PublishingNavigation:PortalSiteMapDataSource>
</td>
<td>
<div class="search">
<asp:ContentPlaceHolder id="PlaceHolderSearchArea" runat="server">
<SPSWC:RightBodySectionSearchBox id="SearchBox" TextBeforeDropDown="" TextBeforeTextBox="<%$Resources:cms,masterpages_searchbox_label%>" TextBoxWidth="100" GoImageUrl="<% $SPUrl:~sitecollection/Style Library/Images/Search_Arrow.jpg %>"
GoImageUrlRTL="<% $SPUrl:~sitecollection/Style Library/Images/Search_Arrow_RTL.jpg %>" SearchResultPageURL="<% $SPUrl:~sitecollection/SearchResults.aspx %>" DropDownMode = HideScopeDD FrameType="None" runat="server"/>
</asp:ContentPlaceHolder>
</div>
</td>
<td class="topNavRoundRight" />
</tr>
</table>
</td>
<tr>
<td colspan="2">
<asp:ContentPlaceHolder id="PlaceHolderTitleBreadcrumb" runat="server">
<div class="breadcrumb" align="left">
<asp:SiteMapPath ID="siteMapPath" Runat="server" SiteMapProvider="CurrentNavSiteMapProvider" RenderCurrentNodeAsLink="false" cssclass="breadcrumb" CurrentNodeStyle-CssClass="breadcrumbCurrent"/>
</div>
</asp:ContentPlaceHolder>
</td>
</tr>
<tr>
<asp:ContentPlaceHolder id="PlaceHolderLeftNavBar" runat="server">
<td valign="top">
<!-- Current Navigation -->
<SharePoint:AspMenu runat="server" datasourceID="SiteMapDS" orientation="Vertical"
StaticDisplayLevels="2" MaximumDynamicDisplayLevels="0" StaticSubMenuIndent="1" ItemWrap="true" AccessKey="3" CssClass="leftNav" SkipLinkText="<%$Resources:cms,masterpages_skiplinktext%>">
<LevelMenuItemStyles>
<asp:MenuItemStyle CssClass="leftNav1" />
<asp:MenuItemStyle CssClass="leftNav2" />
<asp:MenuItemStyle CssClass="leftNav3" />
</LevelMenuItemStyles>
<StaticHoverStyle CssClass="leftNavHover"/>
<StaticSelectedStyle CssClass="leftNavSelected"/>
<DynamicMenuStyle CssClass="leftNavFlyOuts" />
<DynamicMenuItemStyle CssClass="leftNavFlyOutsItem"/>
<DynamicHoverStyle CssClass="leftNavFlyOutsHover"/>
</SharePoint:AspMenu>
<PublishingNavigation:PortalSiteMapDataSource ID="SiteMapDS" Runat="server"
SiteMapProvider="CurrentNavSiteMapProvider" EnableViewState="true"
StartFromCurrentNode="true" StartingNodeOffset="0" TrimNonCurrentHeadings="true" ShowStartingNode="false">
</PublishingNavigation:PortalSiteMapDataSource>
<div class="leftNavSpacer"/>
</td>
</asp:ContentPlaceHolder>
<td width="785" valign="top">
<div class="mainContainer">
<div class="pageTitle">
<asp:ContentPlaceHolder id="PlaceHolderPageTitleInTitleArea" runat="server" />
</div>
<div class="mainContent" align="left">
<asp:ContentPlaceHolder id="PlaceHolderMain" runat="server" />
</div>
</div>
</td>
</tr>
</table>
</td>
<td height="100%" class="my-background" />
</tr>
<!-- Custom Footer... -->
<tr>
<td colspan="3" class="my-background">
<table width="100%">
<tr><td class="my-spacer10"></td></tr>
<tr><td class="my-footer">Copyright (C) 2006 – My Company Site</td></tr>
<tr><td class="my-spacer10"></td></tr>
</table>
</td>
</tr>
</table>
<asp:panel visible="false" runat="server">
<asp:ContentPlaceHolder ID="PlaceHolderPageImage" runat="server" />
<asp:ContentPlaceHolder ID="PlaceHolderBodyLeftBorder" runat="server" />
<asp:ContentPlaceHolder ID="PlaceHolderNavSpacer" runat="server" />
<asp:ContentPlaceHolder ID="PlaceHolderTitleLeftBorder" runat="server" />
<asp:ContentPlaceHolder ID="PlaceHolderTitleAreaSeparator" runat="server" />
<asp:ContentPlaceHolder ID="OSSConsole" runat="server" />
<asp:ContentPlaceHolder ID="PlaceHolderMiniConsole" runat="server" />
<asp:ContentPlaceHolder id="PlaceHolderCalendarNavigator" runat ="server" />
<asp:ContentPlaceHolder id="PlaceHolderLeftActions" runat ="server" />
<asp:ContentPlaceHolder id="PlaceHolderPageDescription" runat ="server" />
<asp:ContentPlaceHolder id="PlaceHolderBodyAreaClass" runat ="server" />
<asp:ContentPlaceHolder id="PlaceHolderTitleAreaClass" runat ="server" />
</asp:panel>
</form>
</body>
</html>
.Net Directory Services Programming – C# - Part 3
Topics
DirectorySearcher – the other critical class in the DirectoryServices namespace.
Review
Because a lot of your Directory Services (DS) development will involve querying DS for data, it makes sense that this is a powerful class offered in the namespace, and below are some of the features:
- DirectorySearcher – Performs the initial queries against AD
- SearchResult – A single object reference from a search performed by DirectorySearcher
- ResultPropertyCollection – A collection of properties of the SearchResult instance
- ResultPropertyValueCollection – The values of properties in a SearchResult instance.
- SearchResultCollection – Basically a collection of SearchResult instances returned from a query by DirectorySearcher
- SortOption – Allows a means to sort a result set.
We have briefly touched on DS by introducing some basic DirectoryEntry information and a couple simple examples, and we have introduced some basic properties and examples on how to interact with those.
I have not taken a lot of time to review a directory structure – basically assuming that you should have some of this understanding already. As I delve into the next lesson, this assumption holds fast. If you have any issues or are dealing with something that I am not elaborating enough on, please feel free to email me directly at (mikeh AT thedataworks.net) and I will respond as quickly as I can. Please forgive the notation there – but we all are familiar with the latest in SPAM bots and whatnot.
Show me the Money!!!
Or at least the code. Lets get started…
Parent – Child Relationships
DirectoryEntry objects (DE’s) can be a root object in AD, or an object within another – hence, a child object of another. We reviewed in Part 1 a few of the common references to object types (CN, OU, DC). These are the most prevalent you will deal with.
DC is the root level context. OU’s can be off the root, or a child of other OU’s and even Containers. CN’s can be off the root, within OU’s and often are found within Containers.
A word about Containers and Security
When planning your DS application, keep this in mind: Containers are non-secure objects! Let me explain. AD security is multi-faceted, yes, but the real security is managed using Group Policy (something we are not going to review here).
Containers are basically folders in your directory tree. AD comes with a couple by default. If you promote a server and check your directory tree, you’ll find a Users, a Built-In, and a couple other folders off the root tree (or context/server name) object. These are not OU’s – they are containers.
Group Policy (GP) cannot be applied to a Container object in AD. You can apply GP to objects within Containers – depending on what those objects are – but not the Container itself. This is important because a lot of administration can be simplified by applying the GP to the entire Container. So if not the Container, then what? Organizational Units – OU’s. Alas, OU’s are going to be your preferred folder or container (for lack of a better way to put it) for object storage.
Basic Searches
In Part 1 we introduced a server name and basic OU’s. To re-cap that:
Server: developer.hamilton.com
OU=Accounts – off the root of developer.hamilton.com
OU=Developers – within the OU=Accounts
CN=Mike Hamilton – within the OU=Developers
Within the OU=Accounts I might also create service accounts – basic user accounts that are used to run services such as IIS Application Pools, SQL Server, or other server / service applications. I might also have OU’s that represent other departments that pertain to development: BA’s for the Business Analyst, QA’s, etc. You can nest OU’s and accounts in just about any way you want to. NOTE: In AD – if you have not already – you will run into one of the inherent limitations of the AD Users & Computers (dsa.msc) snap-in: It can only display the first 2,000 objects within a Container or OU. So if you anticipate a large volume of users for a system you are designing, keep this in mind. You will want to present 1) a more suitable customized user interface piece for administration of this DS, or 2) design your object hierarchy so that users are more spread out within the DS. I will touch base on this topic in a later Part and introduce a couple ideas for addressing this limitation.
DirectorySearcher and the SearchResult
When using the DirectorySearcher class, you have the FindOne() and FindAll() methods that build your result set. As they infer, one finds one occurrence, the other finds all occurrences.
Let’s say I had more than one Mike on my team, and I wanted to find all entries that began with Mike?
DirectoryEntry rootEntry = new DirectoryEntry(); // Binds root context
// Now find every CN that has Mike at the beginning of the name…
DirectorySearcher searcherResults = new DirectorySearcher(rootEntry,”(CN=Mike*)”);
This is a simple example, and the result set will be one or more object references that begin with Mike. Notice that I did a bind on the root of the DS. I could have narrowed the focus of the search to only the developer’s OU by doing the following:
DirectoryEntry developersEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Developers,DC=developer,DC=hamilton,DC=com”);
This would return an entry object where the parent would be the OU=Developers, and not the default root of the DS tree.
Lets say my DS was structured like the following:
developer.hamilton.com à root of the DS
OU=Accounts à First OU of accounts of users.
OU=Developers à Key development personnel
OU=Bas à Business Analyst
OU=QA à Quality Assurance / Test personnel
OU=Users à General users on this server.
Now, we want to find all users that are in the Users OU, not returning the developers or other personnel within the directory. That’s pretty straight forward.
DirectoryEntry developersEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Users,DC=developer,DC=hamilton,DC=com”);
// Now return all users in this OU…
DirectorySearcher searcherResults = new DirectorySearcher(rootEntry,”(CN= *)”);
As you get more familiar with DS programming, you will find there are other ways to accomplish the same result – I am simply trying to open those doors for you.
It is important that you understand how to narrow your search filter in this way because you will find it greatly improves the performance of your application when you know where to search for content and you keep your search filter narrowly defined. For example, if I have 15,000 employees, they would very likely be grouped in AD by their department, and possibly further grouped by sub-departments. I would want to know this information beforehand so I can plan my DS application to be as efficient as possible. I would not want to search the rootDSE each time for a given employee or group of employees, if I know the departments those employees are in.
More on the Search Filter
The filter is a LDAP string that allows you to search for objects based on specific criteria. You will also use relational operators to better refine your search. The following list those operators:
= Equal to
~= Is approximately equal to (or like)
<= Less than or equal to
>= Greater than or equal to
NOTE: You cannot use ‘<’ or ‘>’ individually in LDAP – you must use the notation <= or >=.
The * character works as a wildcard in your search, as in the example above we searched for CN=Mike* or CN=* - in this case, get all Canonical (common) Names beginning with Mike, or get all names period (respectively).
To find all users with a surname of Hamilton you would use
(sn = Hamilton)
To find all users where the email ends in @hamilton.com
(&(objectCategory = person) (objectClass = user) (mail = *@hamilton.com))
Notice the Polish notation used here – the operator comes before the condition. LDAP uses this notation in the Filter. The above example would be more familiar possibly as
(objectCategory = person) AND (objectClass = user) AND (mail = *@hamilton.com)
The following are allowed logical operators:
& AND
| OR
! NOT
You set the filter for a search using the DirectorySearcher.Filter property. The following code will create a binding to the root context, and return everything from the root down:
DirectoryEntry rootEntry = new DirectoryEntry(); // Binds root context
DirectorySearcher rootSearcher = new DirectorySearcher(rootEntry);
Let’s say we have a binding to the rootDSE as above, but only want to return all users with a surname of Hamilton? Change the DirectorySearcher to the following:
DirectorySearcher rootSearcher = new DirectorySearcher(“(sn=Hamilton)”);
You can either pass the DirectoryEntry object, or you can specify a filter in this fashion when creating a DirectorySearcher instance.
Loading Specific Properties
By default, when you create a DirectorySearcher instance, you return all properties for that binding (which can be a lot of data if you