Upgrading a 2010 Publishing Site to SharePoint 2013 Part Two

Published

If you have a look at the TechNet SharePoint 2013 Preview articles, you'll see that Microsoft has done a great job of documenting a lot of the cool new features in 2013. The first paragraph briefly describes an improvement to the Word cut and paste experience for content authors. I can't say enough how important I see that being, so I've devoted a full post just to that topic at SharePoint 2013 Word Cut and Paste.

Naturally I was keen to try the feature out, so one of the first things I did was open my new 2013 blog site (which still looked like 2010), and paste some rich text in from Word. Boy was I disappointed to see that it didn't work. What I didn't realize is that I had to complete the site collection upgrade to be able to see the new feature (yes 2010 mode really does work like 2010).

It was now time to try the Site Collection Upgrade. Much like in 2010, in the Site Collection Administration section of Site Settings, there is a Site collection upgrade option. Running this goes through the site collection upgrade, and another log file is generated. I still had missing features for some of our products that I hadn't tested the upgrade on yet, but otherwise the upgrade went well.

Again like 2010, the resulting site worked but looked all wrong, for the same reasons. The upgrade had changed the master page reference to a new v15.master page, that didn't have any of my custom branding on it. It was time to figure out Design Masters, which are the new way of doing master pages in 2013.

The TechNet article is pretty light on branding improvements, but the design goal from the product team was to make it much easier for web developers to brand SharePoint with the tools and techniques of their choice. I deferred to Jeff Clement (our in-house user experience and HTML guru), and he put together the following information.

Branding Process for blog2013.petercarson.ca

After reading several TechNet documents, PowerPoint presentations and developer blogs for information on SharePoint 2013 branding methodology, I found the following results.

The Design Manager

A new addition to SharePoint is the Design Manager. This is an interface that allows designers to quickly and easily create and maintain custom site designs within SharePoint. The biggest advantage to its inclusion is that it allows you to quickly and easily edit master pages in real time using any web development tool you prefer; SharePoint Designer is no longer required.

The developer starts by importing their master page HTML file into SharePoint, which then converts it into a master page that creates a synchronous .master version of the file. The benefit to this is that designers never need to touch the master page file; everything can be done in HTML. Any changes to the master page HTML file are immediately propogated to the SharePoint .master page. You can even rename or relocate the master page and SharePoint is smart enough to recognize and update itself to reflect those changes.

The Master Page

When it comes to branding, the official Microsoft documentation makes mention of uploading not only the master page HTML, but also its associated CSS and JavaScript assets to the master page folder (see http://msdn.microsoft.com/en-us/library/jj163942(v=office.15).aspx). Navigating to the upload step of the Design Manager instructs you to map a network drive to the following location: http://blog2013.petercarson.ca/_catalogs/masterpage/ (see http://blog2013.petercarson.ca/_layouts/15/DesignMapDrive.aspx).

After reading a few professional developer blogs, it seems the popular method of branding development is to create a subfolder within the /_catalogs/masterpage/ folder that will contain all the master pages, page layouts and assets for the custom branding solution. This is a different approach than what we're used to in SharePoint 2010 with the Style Library. The Style Library still exists in SharePoint 2013, but it seems to have less precedence for the purposes of site branding.

When you look at the code of an existing master page, a lot of what you see is what's been inserted by SharePoint. With the shift to using HTML, you only see code that is available for editing. All the dynamic server-side .NET and SharePoint code does exist in the HTML file, but it is commented out using a special commenting system.

Some of the special comments you'll find in the master page HTML:

<!--SPM:
<!--CS: and <!--CE:
<!--MS: and <!--ME:
<!--PS: and <!--PE:

Here's an example of a content placeholder within HTML code using the comment scheme:

<!--MS:<asp:ContentPlaceHolder ID="PlaceHolderMain" runat="server">-->
...
<!--ME:</asp:ContentPlaceHolder>-->

As far as I can tell - since there doesn't seem to be any existing documentation about this - when the HTML file is saved and synchronization to the .master file happens these comments are parsed by sharepoint into ASP, .NET and SharePoint server code. This allows the designer to focus on what matters most to them: the HTML.

Server-side code can be edited inside the master page HTML file just as you would in the .master file, the only difference is that the modifications need to happen inside the comments.

Upgrading an Existing or Starting a New Master Page to SharePoint 2013

Upgrading an existing master page is a manual process, but it's not nearly as painful as it sounds, at least for simple sites. Here is what I did for Peter's Blog:

Go to the Design Manager
Go to step 3: Upload Design Files
Create a mapped network drive on your computer that points to the location suggested by SharePoint - in my case it was http://blog2013.petercarson.ca/_catalogs/masterpage/
Go to step 4: Edit Master Pages
Click on the Create a minimal master page link
Give the new Master Page a name - in my case I called it "PetersBlog-New"
Go to the mapped network folder and your new master page HTML file will be there. Note that it is only the HTML file and there is no associated .master file
Open up the old master page and into your new master page HTML, bring over only the HTML markup that comprises the design of the site. Be sure to carry over any class names or ID's that seem important
Save your HTML file and then go to step 4: Edit Master Pages
Click on the Convert an HTML file to a SharePoint master page link
Select your master page HTML file and click the Insert button
The page will refresh and your file will appear in the Design Manager: Edit Master Pages list
Click the ... icon to open the file flyout menu, click the ... icon within the flyout and click Publish a Major Version to publish the page. Note that any changes to the HTML file will result in the master page being set back to draft mode

To start a new master page just follow all the same steps as above, with the exception of step 7, where you'll be porting over HTML from your HTML mockup rather than an old master page. Other than that, everything else follows the same steps.

Code Snippets and the Snippet Gallery

SharePoint 2013 has introducted an interface called the Snippet Gallery. The Snippet Gallery serves as a repository of common SharePoint code that designers can customize, copy and paste into their layouts and master pages.

For example, you may have created a master page but now want to insert a dynamic top navigation control. This can be done by clicking the design tab of the Snippet Gallery and clicking the Top Navigation button in the ribbon. The HTML snippet for the control will load into a text area that the designer can than copy and paste at the desired location in their design file.

There are snippets in the Snippet Gallery for navigation, admininstration, containers, web parts and custom .Net markup.

Page Layouts

When you create a page layout from the Design Manager you get an HTML file that contains a minimal page layout and all the fields that come from the content type that you based the page layout on. When you make changes to this HTML file the corresponding .aspx page layout is updated behind the scenes.

Design Packages

Along with everything else, the Design Manager also includes the ability to export a package of your design for easy import to other site collections. The packages does not include default SharePoint design files. Upon export, you can download the compiled .wsp file. It willk also appear as a line item in the Solutions Gallery.

Composed Looks

Composed looks are essentially SharePoint themes. They consist of several components:

Name – the name of the Composed Look
Master Page – for defining the overall layout of the site
Theme URL – Points to an XML file that defines all of the colors you want to apply to different CSS. This works similarly to 2010 except you make your own theme id’s instead of using Accent1, Accent2, etc.
Image URL – Points to an image that can be used to replace a background image in the CSS
Font Scheme URL – Points to an XML file which defines the fonts that can be applied to CSS
Display Order – Helps you arrange the available composed looks

Composed looks could be useful for creating a standard set of site templates for client use.