Master Pages | Jussi on SharePoint

One of the truly great and new features in SharePoint 2013 (Preview) is Device Channels. In a nutshell, Device Channels provide a model for content editors, site admins and developers to provide content manipulation for different browsers and devices based on their capabilities.

The old way of doing things

In SharePoint 2010 the official browser support is fairly clear, and you can see the full table of supported browsers here. For comparison, have a look at the full table of supported browsers for SharePoint 2013 here. In essence, Internet Explorer 7, 8 and 9 are supported for SharePoint 2010, assuming you are using the 32-bit version. Google Chrome and Mozilla Firefox are also now supported, whereas Internet Explorer 6 is totally not supported.

For public-facing sites the typical approach was to create one Master-page, and inject or replace the linked CSS-files depending on browser version. In reality this meant that if anyone was still using IE7, we’d inject some CSS hacks as to not break the site visually or functionally. Simple HTML would do the trick:

   1:  <!--[if IE 7]>

   2:  <link rel="stylesheet" type="text/css" href="/_layouts/JussiOnSharePoint/IE7hacks.css"/>

   3:  <![endif]-->

While highly effective and simple to use, it also caused a lot of issues. One being that we’d easily end up doing multiple if-decisions to detect all possible browser versions, and point to different CSS-files. It was also hard to target specific browsers based on their User-Agent strings, such as IE7 with specific capabilities. URL Rewrite module for IIS gave us a somewhat working solution but required some tinkering with IIS and one had to tinker with the regular expression-based rules to catch all browsers, combinations and options. Even then SharePoint’s support for detecting different browsers was limited at best.

Device Channels to the rescue

Device Channels are used to detect which browser a visitor is using, and to replace the Master page to a more suitable one. This means we can use Device Channels to detect mobile device users, tablet users, desktop users and differentiate between these channels and the capabilities each device’s browser has. As an example, we might choose to not differentiate iPad users from desktop users, since essentially iPad-users tend to have a rather good resolution and the built-in Safari browser supports most capabilities we might already be using.

Device Channel functionality does not remove the need to fine-tune CSS or HTML to provide hacks for specific browser, but gives a nicer way to approach the problem space.

The requirement to use Device Channels is that your Site collection has to have Publishing features, so enable that if it’s not yet enabled in your Site Collection:

Make sure to also enabled the Web-scoped Publishing Feature:

The SharePoint Server Publishing Infrastructure Feature, which is scoped for the Site Collection, also depends on the hidden Publishing Mobile Feature. By this time, you should also have the Publishing Mobile Feature enabled. You can verify this with PowerShell:

Configuring Device Channels

Now that Device Channels is enabled through the Publishing features, we should be able to create channels for our target browsers. You can choose to target mobile and non-mobile browsers. In Site Settings | Device Channels, you should see the list for all the channels. You’ll have a Default channel, which is used by default or when any of the previous channel rules do not match.

I’ve added two more channels – one for Google Chrome-users, and one for Internet Explorer 7 users. The reason I’m interested in IE7 users is that it’s officially not supported in SharePoint 2013.

For Google Chrome users, the alias that I’m using is ChromeDesktop – thus, I’m planning to target desktop users of this fine browser. In Device Inclusion Rules for this channel I’ve included my User-Agent string:

To find out your User-Agent string, go here.

For IE7 users, the Device Inclusion Rules are similar but targeting the IE7 User-Agent string:

I’m using Windows Server 2012 (RTM) as my development platform, so to check what the User-Agent string for older IE versions is simply change your browser mode to IE7 via the Developer Tools (F12) in IE:

And reload the whatsmyuseragent.com page.

Now we have three channels: ChromeDesktop, IE7Desktop and Default. Let’s set different Master pages for each by going to Site Settings | Master Pages:

By default all channels are using the same v15.master Master page, which you can now change to any other Master page you have deployed in your Master Page Gallery. When users access your site in Google Chrome or IE7, they’ll be given the same content with a different master page. All others get whatever you’ve set for the default channel.

Custom Master pages, Page Layouts and Device Channels

You can now create your customized Master pages and Page Layouts to better target and manipulate content for different channels. I created a simple Visual Studio 2012 project as a delivery vehicle for my customized Master pages and Page Layouts. It’s exactly the same as what you would do in Visual Studio 2010 when you target SharePoint 2010.

I’ve added one module as a container for my two custom Master pages, GoogleChrome.master and IE7.master:

I’ve also added a GoogleChromeWebPartPage.aspx Page Layout in case I want to fine-tune content layout for a given channel.

The Elements.xml is very simple and minimal:

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

   2:  <Elements xmlns="http://schemas.microsoft.com/sharepoint/">

   3:    <Module Name="MasterPages" Url="_catalogs/masterpage" Path="">

   4:      <!-- Custom Master page for Google Chrome users -->

   5:      <File Path="MasterPagesGoogleChrome.master" Url="GoogleChrome.master" Type="GhostableInLibrary" />

6:

   7:      <!-- Custom Master page for IE7 users -->

   8:      <File Path="MasterPagesIE7.master" Url="IE7.master" Type="GhostableInLibrary" />

9:

  10:      <!-- Google Chrome Page Layout: Web Parts everywhere -->

  11:      <File Path="MasterPagesGoogleChromeWebPartPage.aspx" Url="GoogleChromeWebPartPage.aspx" Type="GhostableInLibrary">

  12:        <Property Name="Title" Value="Web Part Page Layout for Google Chrome devices" />

  13:        <Property Name="ContentType" Value="$Resources:cmscore,contenttype_pagelayout_name;" />

  14:        <Property Name="PublishingPreviewImage" Value="~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/BlankWebPartPage.png, ~SiteCollection/_catalogs/masterpage/$Resources:core,Culture;/Preview Images/BlankWebPartPage.png" />

  15:        <Property Name="PublishingAssociatedContentType" Value=";#$Resources:cmscore,contenttype_welcomepage_name;;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF390064DEA0F50FC8C147B0B6EA0636C4A7D4;#" />

  16:      </File>

  17:  </Module>

  18:  </Elements>

The Feature is Site-scoped, and has no code:

After deploying the solution, I should be able to go back to Site Settings | Master Pages to verify that I can now select the corresponding Master pages for each channel:

The final configuration for each channel looks like this:

In my Visual Studio project I can now change any relevant portions of the UI via the targeted Master page. Let’s change the icon for both Master pages – the Google Chrome Master page will get the nice ~~Metro~~ ~~Windows 8~~ Modern UI Style-themed icon, and IE7 will get the old but familiar icon:

To replace the site icon, just change the line that points to SiteLogoImage:

   1:  <SharePoint:SiteLogoImage CssClass="ms-siteicon-img" name="onetidHeadbnnr0" id="onetidHeadbnnr2" LogoImageUrl="/_layouts/15/MobileUI/chromeicon.jpg" runat="server"/>

I’m including the two icons in my solution package and deploying them to /_Layouts/15/MobileUI. I could also change the relevant CSS-files, provision my own custom logic or add custom code to better differentiate between browser versions. Device Channels essentially give me a path, and it’s up to the developer to decide what happens then.

Regular users will now see the default channel. This is the view when accessing my site with IE10 on Windows Server 2012:

By switching the browser mode to IE7 (via Developer Tools), I get the new site icon:

You’ll also see that the Edit Links-control has moved a bit. This is because the Master page I’m using as a template is from a different one than v15.master, which the default channel is using.

Google Chrome users are also feeling the love:

Page Layout is the same for all channels, there’s no built-in ability to change that on the fly. What is needed is some logic in my Page Layouts to decide what to show and what to hide based on the channel.

In my custom Page Layout, which was part of the small solution package I deployed, I’m using a Device Channel Panel, which is part of the Publishing functionality. This allows me to include or exclude certain parts in my Page Layout, such as HTML-tags. I need to use my Device Channel naming inside the Page Layout, so it’s probably a good idea to keep the naming simple and short. Specify a channel (or channels) in the IncludedChannels-property:

   1:  <PublishingWebControls:DeviceChannelPanel runat="server" IncludedChannels="ChromeDesktop">

   2:      <b>This is for Google Chrome users only</b>

   3:      <img src="/_layouts/15/MobileUI/chromeicon.jpg" border="0" />

   4:  </PublishingWebControls:DeviceChannelPanel>

When I replace my Page Layout for the landing page to my custom Page Layout, I’m seeing the same content with IE10 and IE7 as before. When using Google Chrome I see additional content:

Additional reading

There’s some good content on Technet for mobile device support and capabilities for SharePoint 2013. Other than that, not much officially available from Microsoft yet.

Master Pages are one of many great things I love in SharePoint. Especially with SharePoint 2010 it seems most (not all) limitations have been removed or pushed further back, liberating the site builder to better adjust the overall look and feel of SharePoint.

Default Master Pages

By default, SharePoint Server 2010 ships with a lot of Master Pages. The relevant ones are the following:

v4.master: This is the default white and blue design primarily aimed for intranet and partially extranet uses. Technically this file resides at C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATEGLOBALv4.master and shouldn’t be edited from its original location. I know it’s tempting but refrain from touching the file at all. A copy of this file is cached on SharePoint WFE’s, edited versions are also stored in the content database.
nightandday.master: This is a sample master page you can either switch on, or keep on using if you provision a new Publishing Site. I’m not a big fan of this and normally just change it to v4.master while I work on the actual Master Pages, that will be customized or custom coded.
simplev4.master: Quoting MSDN, “SharePoint Foundation includes seven pages that use the simplev4.master master page file. These pages render even if the site master page is broken or not accessible to the current user”. Among these are pages like Login.aspx and Error.aspx. I wouldn’t edit this file either – it’s in C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATELAYOUTS.
MySite.master: This is obvious – the Master Page used for My Sites. Sits under C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATEFEATURESPersonalizationSite. It goes without saying you should keep your hands off from the original files.
“The old bunch” of Master Pages: These are the oldish Master Pages from MOSS 2007: BlackBand, BlackSingleLevel, BlackVertical, BlueBand, BlueGlassBand, BlueTabs, BlueVertical, GlassBand and OrangeSingleLevel. They all reside as a feature at C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATEFEATURESPublishingLayouts. Not really used anymore but if you insist, you could probably hack something together by using thse templates.
Minimal.master: A child of v4.master, used for Search results and similar. Does not include Quick Launch navigation or Ribbon. Located at C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATEGLOBALminimal.master.
Default.master: Upon migration from MOSS 2007 to SP 2010 you can choose to keep the old UI, which comes from Default.master. Also in C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATEGLOBAL.
Applicationv4.master: Used for Application Pages under /_layouts/.

Customizing Master Pages

As I see it, there’s only two paths you should follow when customizing Master Pages. In no order of preference, these are:

Create a copy of v4.master and work your way from there: This is the fastest route for any intranet delivery, where UI and graphical elements are not the main target of customization. This often applies to projects where changing the logo or fine-tuning Quick Launch navigation is an acceptable end-result.

The downside of using v4.master as a template is the messiness. The markup, it’s not something to write home about. Unless your folks love horror stories. The styling, crappy commenting and other minor things really get irritating if you need to work under a tight schedule and modify elements on a pixel by pixel basis.

Use Randy’s Starter Master Pages as a template: First, download the excellent Starter Master Pages templates from CodePlex. You can probably spend a few days building your custom UI and layouts from here. Best suited for public-facing sites, extranets and larger intranets where exact requirements and other UI standards dictate majority of the work. Requires somewhat more groundwork to get things whizzing.

Which tools can I use to customize a Master Page?

It’s really up to you to choose your preferred tools. I’m often opposed to using SharePoint Designer but this is one of the (rare) instances where I’m encouraging the use of this power tool.

A couple of principles that I suggest to keep in mind:

Always have a development site that you can destroy and recreate in a matter of seconds

A simple Remove-SPSite & New-SPSite is enough

Do packaging and fine-tuning in Visual Studio. Always. It’s worth the additional two minutes.
Deploy everything through SharePoint packages (wsp-files). Avoid direct publishing through SharePoint Designer – it’s an invitation for additional problems and issues in the future.
Copy-paste content between Visual Studio and SharePoint Designer through Notepad. You want to avoid any formatting and encoding issues.

Some people seem to prefer a true HTML design tool such as Dreamweaver from Adobe. You can also rely purely on Visual Studio, especially with the recently released web standard update for CSS 3 and HTML5.

From HTML prototype to a finished Master Page

If you choose to forfeit v4.master and build something from scratch – or are willing to re-build a lot of the existing elements – create a HTML prototype without using SharePoint Designer. This forces you to understand the structure of your Master Page; any future design changes are easier to reflect when you know each line by heart. Even massive changes are fairly easy to implement using this approach. It will take a bit more time and effort initially but this pays off when you templatize your creations.

Note: The HTML prototype does not need to have any SharePoint controls that actually work. Placeholders and mockups are a viable option here.

When you have your HTML prototype ready for testing, benchmark against any browsers you feel should be supported. Fix errors and test again. You might want to get more coffee at some point. Don’t try to do this in one day – oftentimes small UI errors are hard to spot with tired eyes and mind.

Finally, move your HTML prototype to SharePoint Designer and replace placeholders with actual SharePoint controls, tags and other decoration. Avoid changing your HTML at this point, otherwise you’re invalidating your tested prototype and need to restart browser compatibility testing again. I hate that.

Try deploying your solution to SharePoint through Visual Studio. You should be able to quickly spot any glaring errors with IE9’s Developer Tools and/or Firebug.

Don’t worry about packaging that much for now. Chances are you need to tweak, change, alter and modify your creation numerous times. Each time you re-open your solution you’ll have a chance to make packaging a little bit better. And squash those pesky bugs that somehow keep appearing when you least expect it.

Summary

The overall concept is simple: Create a HTML prototype, fine-tune & decorate with SharePoint Designer (or directly with Visual Studio if you’re feeling.. audacious), and package for deployment.

In true life it’s sometimes challenging to choose the path between v4.master and Starter Master Pages. If unsure, go with the latter. If you know things are not going to evolve a lot, opt for v4.master.

Jussi on SharePoint

Get-SPJussi -Mojito:$true

Tag Archives: Master Pages

Targeting multiple browsers and devices in SharePoint 2013 using Device Channels