Brett's SharePoint Blog : sharepoint

Master Pages Revisited: References to master pages in SharePoint

bgeoffro — Mon, 22 Jun 2009 11:12:00 GMT

I'm still neck-deep in WCM planning, design, and development on my current project and also get lots of questions on branding topics, so a frequent point of discussion is various design patterns for the use of master pages. One of the topics that's come up a lot recently is "how do I assign master page X to page (or page layout) Y", so I've attempted to summarize my findings and recommendations on this topic in a handy table in this post.

First off, a refresher on key jargon used in the table...

Page Types - these include System Pages (i.e. web pages & web part pages that aren't based on page layouts and list view/display form pages), Page Layouts, and Application Pages.

There are five techniques described in the table for assigning a master page reference:

Hardcoded
This is a relative or absolute path to a master page. Relative locations are based on the page instance's location - i.e. "../_catalogs/masterpage/this.master" will find this.master in the current SPWeb's master page gallery, which may or may not be the top-level site's master page gallery.
Token-based References as described in this article

Static Token for Site-Relative Master Page
Note that the syntax for using this token is incorrect in the article - the correct syntax is ~site/_catalogs/masterpage/yourmasterpage.master.
Static Token for Site Collection-Relative Master Page
Note that the syntax for using this token is incorrect in the article - the correct syntax is ~sitecollection/_catalogs/masterpage/yourmasterpage.master.
Dynamic Token for SystemMaster Page
The ~masterurl/default.master token will use the current site's System Master Page.
Dynamic Token for Site Master Page
The ~masterurl/custom.master token will use the current site's Site Master Page.

Approach	Page Type	Result	Comments
Hardcode ../_catalogs/masterpage/XXX.master (or ../../_catalogs, etc., depending on how deep the page is located in the site hierarchy)	System	Works - desired master page is used
~masterurl/default.master	System	Works - System Master Page is used
~masterurl/custom.master	System	Works - Site Master Page is used
~site/_catalogs/masterpage/XXX.master	System	Works - desired master page is used
~sitecollection/_catalogs/masterpage/XXX.master	System	Works - desired master page is used
Hardcode ../_catalogs/masterpage/XXX.master	Page Layout	Error	Even if this did work, hardcoding a reference to a master page with this kind of relative path is a bad idea - remember that you may have subsites!
~masterurl/default.master	Page Layout	No effect	Simplest approach is based on information architecture - if a publishing page needs to use a different master page, put it in a different site. If this doesn't cut it, ask yourself why you really need two different looks & feels for a single site. Remember that you can override just about anything from the master page in the page layout. Did you think about designing your master page in such a way that you can override the undesirable behavior/appearance in the page layout?
~masterurl/custom.master	Page Layout	No effect	Same as above.
~site/_catalogs/masterpage/XXX.master	Page Layout	No effect	Same as above.
~sitecollection/_catalogs/masterpage/XXX.master	Page Layout	No effect	Same as above.
Hardcode ../catalogs/masterpage/XXX.master	Application	Error	Even if this did work, hardcoding a reference to a master page with this kind of relative path is a bad idea - remember that you may have subsites!
~masterurl/default.master	Application	Error	See my first big branding post for techniques applying to adjusting the look & feel of LAYOUTS pages - http://blogs.msdn.com/bgeoffro/archive/2007/11/12/branding-a-moss-corporate-intranet-portal-part-1b-branding-methods-by-scope-and-scenario.aspx . If you want to use a site or site collection-specific master page, the solution must involve an HttpModule. It'd be a different kind of branding module than I've described in my previous branding posts, as the module would need to read the Site Master Page or (more likely) the System Master Page from the current SPWeb based on the path, and then apply it to the page.
~masterurl/custom.master	Application	Error	Same as above.
~site/_catalogs/masterpage/XXX.master	Application	Error	Same as above.
~sitecollection/_catalogs/masterpage/XXX.master	Application	Error	Same as above.

Note that I didn't mention Site Pages (pages based on page layouts) anywhere in the table. You can't assign a master page to them using any of these techniques since they inherit from a page layout. Your only option in the unusual scenario of assigning a specific master page to a specific Site page would be to use a HttpModule that references the absolute path to that specific page and reassigns the master page. A better approach would be to use a page layout specifically designed for that page instance, and then override the master page as needed in the page layout.

Using custom scopes on multilanguage variation sites

bgeoffro — Sun, 24 May 2009 19:06:00 GMT

One of the great things about working on MOSS projects here in Europe is the prevalance of multilanguage requirements. You just don't encounter multilanguage requirements (at least on intranets & extranets) nearly as often in the US. I've had a lot of deep, hands-on experience with custom and variations-based multilanguage sites this year, and wanted to provide a heads-up regarding a problem and a novel solution when using variations and search.

The Problem

This is a pretty straightforward scenario you'd encounter if you are using variations to implement a multilanguage site. Assuming you've got the default shared scopes configured and are using a master page like default.master that uses the SmallSearchInputBox delegate control, here's the repro:

Create a new site collection in language X (English in this example).
Configure the site collection to use custom scopes (Site Actions > Modify All Site Settings > Site Settings > Search Settings > Use Custom Scopes).
Set the variation home ("/" in this example).
Create a variation label for language X (English in this example)
Create a variation label for language Y (Dutch in this example)
Create the variation hierarchies
Navigate to the welcome page for variation site in language X
Select the search dropdown control - "This Site:...", "All Sites", "People" appear in the list (these labels are different if language X is not English).
Navigate to the welcome page for variation site in language Y
Select the search dropdown control - "Deze Site:..." appears in the list (this label is different if language Y is not Dutch).

You'll find "All Sites" and "People" (and any other shared scopes) are missing for any variation site where the language is different from the root site. So where did they go?

The key question is, "why do items appear in the search dropdown control?" The dependency in question is a Search Display Group (Site Actions > Modify All Site Settings > Site Settings > Search Scopes). In single-language site collections, display groups and search scopes all use the same language, so no special configuration is necessary.

In Multilanguage site collections – such as those that use variations – there is an important difference in behaviors. As with single-language site collections, the search scopes and display groups are created in the top-level site’s language. However, some of the subsites are created in different languages. On each site, the search control will look for the scopes in the Search Dropdown display group (which is named differently for each language) to determine which scopes to show on the search control.

On the sites where the language is the SAME as the top-level site, all the scopes in the Search Dropdown display group will render – this is because the names of the Search Dropdown display group in the search settings and the search control match. For example, if the top-level site is English, the Search Dropdown display group is named “Search Dropdown”, and the search control on English sites will be looking for scopes in a display group named “Search Dropdown”.

On the sites where the language is DIFFERENT from the top level site, none of the scopes in the Search Dropdown display group will render – this is because the names of the Search Dropdown display group in the search settings and the search control do not match. For example, if the top-level site is English, the Search Dropdown display group is named “Search Dropdown”, and the search control on Dutch sites will be looking for scopes in a display group named “Vervolgkeuzelijst voor zoeken”, which does not exist.

The Design

Our solution was based on our requirements, which is to support the set of five languages required by our customer. The solution components are a single site collection-scoped feature with a feature receiver, which are manually activated as needed by site collection owners for sites that use variations. When the feature is activated, the feature receiver performs the following tasks:

Retrieves the list of five language-specific Search Dropdown display group names from the feature properties
Identifies the default scope in the existing Search Dropdown display group
Creates any of the Search Dropdown display group that do not exist
Ensures that all compiled shared search scopes are added to each search dropdown display group

The feature does NOT delete any of these display groups or their associated scopes upon deactivation, as it is not possible to determine which scopes were set manually. If additional language packs would be installed, we'd need to include the additional language-specific Search Dropdown display group names. Extending the feature to support additional languages simply requires adding a new property to the feature.xml <Properties/> element.

The Code

There are only two pieces to the solution - the feature manifest and the feature receiver. The example below just shows properties for two languages to keep things simple (and avoid problems handling unicode).

Feature.xml:

<?xml version="1.0" encoding="utf-8"?>

</Feature>

Feature receiver:

using System;

using System.Web;

using System.Web.UI;

using System.Web.UI.WebControls;

using System.Web.UI.WebControls.WebParts;

using Microsoft.SharePoint;

using Microsoft.SharePoint.WebControls;

using Microsoft.SharePoint.WebPartPages;

using Microsoft.SharePoint.Navigation;

using Microsoft.SharePoint.Administration;

using Microsoft.Office.Server.Search.Administration;

namespace ScopeDisplayGroups {

public class FeatureReceiver : SPFeatureReceiver {

public override void FeatureActivated(SPFeatureReceiverProperties properties) {

SearchContext searchContext;

string currentGroupName = string.Empty;

using (SPSite currentSite = (SPSite)properties.Feature.Parent)

{

//retrieve current scope display groups from this site

searchContext = SearchContext.GetContext(currentSite);

Scopes scopes = new Scopes(searchContext);

ScopeDisplayGroupCollection scopeDisplayGroups = scopes.AllDisplayGroups;

Uri siteUri = new Uri(currentSite.Url);

ScopeDisplayGroup displayGroup = null;

Scope defaultScope = null;

//retrieve new scope display group labels from feature properties

//first, iterate through the scope display group labels to find the one that exists

//so we can identify the default scope

foreach (SPFeatureProperty featureProperty in properties.Feature.Properties)

{

currentGroupName = featureProperty.Value;

try

{

displayGroup = scopes.GetDisplayGroup(siteUri, currentGroupName);

defaultScope = displayGroup.Default;

}

catch (InvalidCastException ex)

{

//do nothing if group is not found

}

//retrieve new scope display group labels from feature properties

foreach (SPFeatureProperty featureProperty in properties.Feature.Properties)

{

currentGroupName = featureProperty.Value;

try

{

displayGroup = scopes.GetDisplayGroup(siteUri, currentGroupName);

//if display group exists, add any missing compiled shared scopes

//this is a "bonus feature", since API doesn't allow us to determine which scopes are OOTB

//normally only All Sites and People are added automatically to the search dropdown feature

foreach (Scope sharedScope in scopes.GetSharedScopes())

{

//only add shared scopes that are currently compiled AND are not part of display group

if (!displayGroup.Contains(sharedScope) &&

(sharedScope.CompilationState.Equals(ScopeCompilationState.Compiled)))

displayGroup.Add(sharedScope);

}

displayGroup.Update();

}

catch (InvalidCastException ex)

{

//if display group does not exist, create the new scope display group

ScopeDisplayGroup newDisplayGroup = scopeDisplayGroups.Create(currentGroupName, string.Empty, siteUri, true);

foreach (Scope sharedScope in scopes.GetSharedScopes())

{

//only add shared scopes that are currently compiled

if (sharedScope.CompilationState.Equals(ScopeCompilationState.Compiled))

newDisplayGroup.Add(sharedScope);

}

//if one was found, set the default scope to the same value for all new display groups

//AND move it to the first choice on the list

if (defaultScope != null)

{

newDisplayGroup.Remove(defaultScope);

newDisplayGroup.Insert(0, defaultScope);

newDisplayGroup.Default = defaultScope;

}

newDisplayGroup.Update();

}

scopes.Update();

}

public override void FeatureDeactivating(SPFeatureReceiverProperties properties) {

/* no op */

//do nothing - removing search scope display groups could be destructive

}

public override void FeatureInstalled(SPFeatureReceiverProperties properties) {

/* no op */

}

public override void FeatureUninstalling(SPFeatureReceiverProperties properties) {

/* no op */

}

SharePoint AcademyLive Recommended Readings

bgeoffro — Wed, 13 Feb 2008 00:50:00 GMT

This won't mean too much for those of you who aren't attending the AcademyLive courses, but here are some recommended readings on two topics we were discussiong today - Security & Information Architecture.

Branding Lessons Learned 2: Post-launch

bgeoffro — Thu, 20 Dec 2007 20:30:00 GMT

Yay. We launched a few days ago. Now it's time for another recap of lessons learned on the technology and process fronts:

Process Learnings (AKA battle scars):

Requirements & Design.

I won't go into the reasons why, but we had an exceedingly shallow requirements gathering effort for the branding effort, basically comprised of (a) a handful of review sessions of out-of-the-box MOSS with the customer's style guide gurus and (b) a handoff from them to our dev team of the generic (but very detailed) style guide that applied to all internal websites. No wireframes, no screenshots, no "clean slate" approach to designing the look and feel - just a half-dozen or so generic design guidelines for layout changes and the hundreds of specs for fonts and colors included in the style guide for guiding stylesheet changes.
Result: CSS updates were relatively straightforward - especially when using SharePoint Skinner or the IE Developer Toolbar to identify all the styles that needed updating - since we had a very detailed style guide and developers who knew it from working on other internal websites. Layout changes were the largest resource drain - since we were extending default.master, MWSdefault.master, etc., we often encountered vexing layout bugs relating to the complex nested tables in these pages. If you are compelled down a similar requirements/design path, plan for a long test/debug cycle, at least double that of one for a "clean slate" approach. You'll probably want to weigh the cost of investing time in wireframing everything out and building these pages from scratch using the minimal.master approach vs. an extended test/debug cycle. Don't forget to think about the cost per hour of the resources involved in each stage when weighing this decision.

Testing

MOSS is a huge product and good resources are in high demand. I'm subject to the availability bias here, but I suspect that very, very few of them are in dedicated QA roles. As a result, your test team is unlikely to have deep knowledge of the product, resulting in (1) test scripts that have enormous gaps in coverage (even those of us who are immersed in this product frequently "discover" existing features they didn't know about), and (2) innumerable misidentified "bugs" that are simply caused by ignorance of standard behavior. Mitigate both issues by sending your QA folks to deep SharePoint end user training OR tasking your high-cost MOSS expert with authoring test scripts. Run the numbers to figure out which is cheaper. Further mitigate issue 2 by having an OOTB MOSS environment availble to the QA team - a VM will do - to enable testers to confirm whether or not behavior in a customized environment is as expected. Again, run the numbers to figure out if it makes sense - how much a VM costs to setup and maintain vs. wasted developer/architect time chasing down nonissues.
There are LOTS of odds & ends to cover in testing! Use Heather Solomon's checklist of branding gotchas to increase your coverage in your test scripts.

Additional Technical Learnings:

Should you create a backup of the LAYOUTS directory and modify the original (KB944105 method 1) or create a copy of LAYOUTS for each custom-branded web application and point their respective IIS sites to it (KB944105 method 2)?

We adopted the simplest possible implementation of method 2. Central Admin and SSP admin continue to use the standard LAYOUTS directory (really, you've got to have lots of extra cash floating around if you're branding those sites); all user-facing web apps used a shared customized copy of the LAYOUTS directory. We initially had a distinct copy of the LAYOUTS directory for each user-facing webapp to allow for design flexibility (see the iterative design process above), but this made for an onerous deployment process that led to more than one perceived "bug" that was actualy a deployment error.
Method 1 works if (a) you want to brand (and troubleshoot the branding of) SSP admin, and (b) Central Admin is installed on a non-WFE server OR you want to brand (and troubleshoot the branding of) Central Admin.

Odds and ends.

RunReport.aspx (List Settings > Workflow Settings > View Workflow Reports) is another branding outlier with no master page. If you need to brand this page, you could take the same approach as for the sitemanager.aspx page (see lessons learned 1).
No load test data on the HTTP Module - it didn't make the cut in our aggressive delivery schedule. Watch for future blogs on this subject in the next month or so as we roll out another branded environment.

MOSS Intranet Portal Branding Lessons Learned 1: Omissions & Test Results

bgeoffro — Thu, 15 Nov 2007 05:41:00 GMT

We've spent the past four days doing user acceptance and regression testing on our branding, and I've found a couple of essential additions. Expect more as the testing wraps up over the next week or two:

Branding the "Operation in Progress" Page. Another GIF you may want to replace is GEARS_AN.GIF if you need to adhere to strict color/look & feel guidelines.
Templatepick.aspx. Users generally only see this one if they're creating meeting workspaces from calendar events. But if they do... it inherits from application.master, which seems a strange choice, since there's no site (and therefore no theme) yet when you're hitting this page. We haven't fixed this one yet, but I'm thinking the best way to go is to follow Heather Solomon's advice and embed the necessary styles directly in the page (following KB944105 or using an HttpModule redirect, of course), or re-master it with something a little more like simple.master
Site Content & Structure Page (LAYOUTS/sitemanager.aspx). This page doesn't use any master page... if you want to brand it, you'll have to do so by direct customization (using a supported method like the KB944105 methods or a redirect via an HttpModule). Interestingly, this page does NOT include the <SharePoint:CssLink/> like all the other pages accessed via the Site Settings page... haven't figured out why yet, but I'll let you know when I do...
HttpModule applicability. This should also work for the other virtual dirs like _controltemplates, not just _layouts. You'd definitely want to test this idea first - I've only used the KB944105 methods for customizing CONTROLTEMPLATES files in my sandbox, as we didn't need to make any changes in my customer's environment.
BrandingUpdate app gotchas. We ran into two issues when installing the branding on a number of existing test sites:

Site locks. Sites that are locked as no access or read-only can't be updated. Branding updates to these sites will fail, since you can't modify them. :)
"Apply Themes" permission. I thought it'd be clever to disallow users from changing themes in addition to applying the new custom theme (you do this through Central Admin > Application Management > Site Permissions for Web App). This is a disaster - it prevents BrandingUpdate from changing the theme on existing sites, AND it prevents site owners from firing off the theme change on the receiver assembly when they create new sites. New approach: leave this permission turned on, but hide all the OOTB themes in SPTHEMES.XML. Users can select from a grand total of exactly ONE theme. :)

More reasons to avoid use of ISAPI filters. Many thanks to my MCS coworker Suman for reminding me of my need to start studying IIS7... check out this article on how you can do a lot more with managed code to extend IIS7 than you could with IIS6: http://www.iis.net/articles/view.aspx/IIS7/Extending-IIS7/Developing-a-Module-using--NET/Developing-a-Module-using--NET .

Also, I wanted to emphasize the near-inevitability of the need to customize the LAYOUTS components. There is no escape... ;) Here's a far-from-complete list of a few high-visibility components in the LAYOUTS directory that the most common role used in collaboration sites (Members) will have access to:

Upload.aspx - Collaboration users have, on occasion, been known to upload a document or two. :)
Subnew.aspx & MySubs.aspx (AKA the New Alert page and the My Alerts page) - Extensively used, especially by teams led by productivity nuts.
Viewlsts.aspx - this is used for the "Documents", "Lists", etc. pages in sites.
Recyclebin.aspx - Perhaps the most requested enhancement from SPS2003/WSSv2.. A few folks might use it. :)
Userdisp.aspx - Used when somebody wants to see user details for themselves or another user (i.e. when clicking on a user name in a "Modified By" field).

Take a few minutes to see what Visitors have access to and you'll get a smaller list, but enough to cause a jarring user experience if you've done anything more than modify the theme. And don't forget this big one... If you're deploying personal sites - everybody's a site collection admin and sees all the LAYOUTS pages.

Branding a MOSS Corporate Intranet Portal, Part 3: LAYOUTS Pages

bgeoffro — Tue, 13 Nov 2007 03:51:00 GMT

Introduction

In order to get a consistent look and feel across all the pages, we had to brand the LAYOUTS pages as well. Since we needed webapp-specific branding and didn’t want to deal with the additional effort involved in branding & testing SSPAdmin pages, I started out following what eventually came to be known as Method 2 from KB944105. After a bit of prototyping, it looks like we’ll be going with the HttpModule-based approach, plus a few exceptions handled by Method 1 from KB944105. Performance testing is coming up in the next couple of weeks, so I’ll be sure to share how that shakes out (Method 2 is our fallback if performance is a big drag).

Thanks to Liam Cleary, whose code gave me a huge kickstart on this solution.

BrandingModule Project

The BrandingModule project consists of three components:

· ResourceRedirect Class – HTTPModule used to execute master page and other resource redirects

· RedirectSectionHandler Class – Configuration file section handler for processing ResourceRediect configuration settings

· Redirect Structure – Structure used to capture individual configuration setting elements for ResourceRedirect

Redirect Structure

The Redirect Structure is a simple structure for capturing configuration settings for all five types of redirects. Usage by type is detailed in the description.

Public Members

Member	Type	Inheritance	Description
pattern	Property	n/a	· pageRedirects -Captures the CONTAINS pattern-match filter · destinationRedirects - Captures the CONTAINS pattern-match filter · pathRedirects - Captures the STARTS WITH pattern-match filter · comboRedirects - Captures the STARTS WITH pattern-match filter · masterRedirects – not used
masterPageUrl	Property	n/a	· pageRedirects -identifies replacement master page · destinationRedirects – not used · pathRedirects - identifies replacement master page · comboRedirects - identifies replacement master page · masterRedirects – identifies replacement master page
originalMaster	Property	n/a	· pageRedirects - identifies original master page used to identify a class of pages · destinationRedirects – not used · pathRedirects - not used · comboRedirects - not used · masterRedirects – identifies original master page used to identify a class of pages
destinationPageUrl	Property	n/a	· pageRedirects - not used · destinationRedirects – identifies redirect page · pathRedirects - not used · comboRedirects - not used · masterRedirects – not used

RedirectSectionHandler class

The RedirectSectionHandler is a custom implementation of the System.Configuration.IConfigurationSectionHandler class.

Public Members

Member

Type

Inheritance

Description

Create

Object

IConfigurationSectionHandler

Returns a collection of Redirect objects and performs minimal validation on entries. Throws a ConfigurationErrorsException if either of the following conditions is true:

· masterPageUrl and destinationPageUrl are blank/missing

· pattern and originalMaster are blank/missing

ResourceRedirect Class

RecourceRedirect is a custom implementation of System.Web.IHttpModule.

Public Members

Member	Type	Inheritance	Description
Init	Method	IHttpModule	Adds the context_PreRequestHandlerExecute event handler to the PreRequestHandlerExecute event handler.
Dispose	Method	IHttpModule	Non-implemented stub.
context_PreRequestHandlerExecute	Method	n/a	Adds the page_PreInit event handler to the PreInit event handler if the current handler is a page.
page_PreInit	Method	n/a	Processes redirect instructions as specified in the configuration file. Redirects are processed in the following order: 1. Destination Redirects identified in the Branding/destinationRedirects configuration section. 2. Combination Redirects identified in the Branding/comboRedirects configuration section. 3. Path Redirects identified in the Branding/pathRedirects configuration section. 4. PageRedirects identified in the Branding/pageRedirects configuration section. 5. Master Page Redirects identified in the Branding/masterRedirects configuration section.

Private Members

Member	Type	Inheritance	Description
UpdateLog	Method	n/a	Writes event log entries. Not used – intended for diagnostic purposes only.

Configuration Settings

The ResourceRedirect requires three sets of configuration settings to be registered in a web application:

· SectionGroup configuration

· HttpModule configuration

· Branding configuration

SectionGroup Configuration

The custom section group and sections for the Branding configuration require registration in the web.config file. The <configSection/> element REQUIRES the following:

<section name="pageRedirects"