Omicron Llama

Coding all day, every day.

SharePoint 2013 Design Manager – It Kinda Sucks, It’s Kinda Good

SharePoint 2013 has touted quite a few new features which allegedly ‘enable’ developers from more web design backgrounds to work in the platform. There is an encouragement to use more modern development techniques such as pure JavaScript and HTML to use technologies like REST to develop applications. And fitting in with this trend is the encouragement of web developers to be able to create designs for SharePoint sites without needing to know too in-depth knowledge about ASP.NET web forms, particularly how MasterPages and SharePoints Page Layouts work.

The Design Manager steps in as promising to “makes it easier to create a fully customized, pixel-perfect design while using the web-design tools that you’re already familiar with.“. Now, designers were able to this perfectly well in previous versions of SharePoint, granted that they became familiar with dealing with extremely bloated markup, most of which SharePoint needed to provide its rich functionality. All we had to do was learn which bits never to remove and to build designs in and around the dozens and dozens of lines of code that SharePoint uses. Randy Drisgill has kept the design world in SharePoint much more manageable with his stripped-down master pages which contain only the markup that SharePoint needs to get itself working.

The general idea…

In this post I’ll go through my own experience of using the Design Manager, how it compares to what the tutorial actually recommends you do, and how I reckon it would work in real life. More importantly, if the Design Manager really is the better way forward for designers to go. (Spoiler: Yes. Yes it is. In my opinion.)

The tutorial I’ll follow is detailed on MSDN here: How to: Convert an HTML file into a master page in SharePoint 2013 which covers the first and main thing we encounter when branding a site – building a masterpage.

The general workflow of using the design manager is as follows:

  1. Create a static HTML Mockup of how you want the site to look
  2. Convert it into a masterpage
  3. Add SharePoint functionality using “snippets”
  4. Preview & Fix Issues
The main promise is that you can use your favourite HTML editor to create, fix and maintain your masterpage. You could do this before by editing .master files, as I said before, but there is one benefit now that comes into play that has a slight sting in its tail, but once you get used to it it may actually be a better way of working. 
What really happens is that SharePoint generates a .master masterpage file from your uploaded HTML markup file. The HTML markup file is then linked to that masterpage file. Any changes you make to the HTML file cause the .master file to re-generate. You can edit the resulting .master file if you want by unlinking from the HTML (it’s a list item property of the HTML file, called ‘Associated File’), but then changes to the master file are lost when you re-associate.

Trying it out

So to begin with, I started off with a nice little HTML mockup of a very simple design I created. I called it SampleDesign. Here’s how the markup looks in my favourite HTML editor (Visual Studio 2012, which is a damned good HTML editor nowadays).
Now it’s off to the Design Manager to upload. And this is where things get interesting. As the MSDN Documentation says, SharePoint will add some markup to your page when it’s converted to a masterpage. Upload the file to somewhere in your masterpage gallery (preferably in its own folder in the gallery) then  use the ‘Convert an HTML file to a masterpage’ option under ‘Edit Master Pages’ within the Design Manager. Once you’ve done this, open the file you uploaded, using your favourite HTML editor.

Whoa. Comment blocks everywhere! And this is one of the slightly nicer things about this method – no longer will your editor complain about lots and lots and lots of SharePoint ASP.NET tags all over the place, these are all commented out.
Now the next thing to do is to take your design, replace out all the ‘stub’ content in your page with the SharePoint-Provided Snippets. Let’s replace my site title in the H1 tag with the snippet provided in the design manager. But wait, here’s our problem. Our beautifully simple design has been way too cluttered with SharePoint stuff. Lets add the snippet to our original, simple design mockup that’s stored locally, by copying and pasting (ignore the fact I’ve stuck a div inside an H1).
That was relatively simple. Lets see what happens when we re-upload this to the site:
That’s…. not bad. A little less painful than trying to figure out where in the muddle of all the markup that snippet was supposed to go. 
But here we have a problem. We have a disconnect between our beautifully simple HTML mockup we created, complete with snippets, and the ‘live’ SharePoint copy of the masterpage. What do we do? Microsoft recommends that we connect a shared drive to the masterpage gallery and let us edit the HTML masterpage directly from the gallery, yet it’s full of comments and snippet code already injected by SharePoint.
Well what seems to make sense to me is to first design your simple HTML mockup. Then go into the Design Manager and get the snippets you need, and then insert them. Make sure you have ALL of the ones you think you will need for your design. Try to make the HTML markup that you have to upload as final as possible, in that you have the layout and snippets all in place, and have resolved some of the HTML markup issues using the Preview button. Keep as much control of the layout in CSS as possible (which is a good design practice anyway). 
That way, once you’ve uploaded the HTML file and SharePoint has converted it into a masterpage, you can continue to tweak the design directly on the server by only modifying the CSS files for your design.
Another thing that makes this whole method slightly more encouraging is what SharePoint does to generate the Ribbon – It’s a single line of SharePoint snippet. This vastly reduces the bloat we used to have in the classic masterpages, but they still could have done it better by doing something similar with all the controls needed within the HEAD tag.

Another snippet

Lets add another snippet and try out this workflow again. This time I’ll add a searchbox snippet:
Nice and easy, got my referenced CSS file in there too to stick it up on the right:
Upload it back to the masterpage gallery, and have a look at the converted markup….
As predicted, it’s converted everything nicely. Lets see how the Visual Studio Design View treats this, just out of curiosity…
… not so fantastic. Might as well stick to the code view and use the Design Manager Preview to see how things are going…
… that’s a little better.


Now, the MSDN tutorial recommends you upload a valid XML file. Fair enough, but lets see how ‘valid’ our bare HTML mockup is with just the added snippets from the SharePoint site (not the generated HTML masterpage, but the one we started with, and then added to):
That’s not too good. Ignore the 1 error I made by putting a div within an H1 tag, the rest are all to do with SharePoint’s attributes that it’s added (such as div webpartid=… ).

The Workflow as I see it

So, to summarise the workflow as it appears to work best:
  1. Design your HTML mockup for the masterpage as complete as you can make it.
  2. Use CSS extensively to control layout (as you should be)
  3. Add all the SharePoint snippets you will need to the appropriate areas
  4. Upload to the masterpage gallery, in its own folder for the design
  5. Convert it to a masterpage using the design manager
  6. Use the Preview tool to find and sort any problems.
    1. Try to use the CSS files for your design to sort the issues where you can, but if you have to change the markup, then do so in your original, local file then re-upload.
    2. Try to make the uploaded HTML file a ‘final’ kind of copy.
  7. Publish it. Then get ready for deployment.

Design Packages

So now you’ve got a design just the way you want it, and now you need to push it somewhere else. Enter the Design Packager. This generates a WSP file that will live in the Solutions gallery (Sandbox definitely not out of the picture then, especially if the Design Manager continues to live on in the next version of SharePoint). Bare in mind that when you create a design package, it saves it in the Solutions gallery of the site but doesn’t activate it. It’s probably not wise to activate it on the site you created it in anyway. 
Download it, upload it into the destination site and activate it. When I first did this I got an error (see right), but when I looked at the Solution gallery it seemed to be activated anyway. So no harm done (it seems).
 It’ll create the files/folders in the masterpage gallery. You can then see it available when you access the ‘Assign master pages to your site based on device channel’ option, on the Publish and Apply Design page of the Design Manager. This page just happens to be the classic ChangeSiteMasterPage.aspx of yore. If you don’t see it here, you might have to Publish and Approve the masterpage HTML file. Don’t do this on the generated .master file, they are linked.
Publish the HTML file and both the html and master go to ‘Pending’…
… mark the HTML as approved and they both go to ‘Approved’.

In Summary

So – good things (in my opinion) about the design manager:
  • Lets you edit HTML markup to describe a page layout, rather than a messy ASP.NET master page
  • Lets you package and deploy all assets needed for your branding solution
Bad things:
  • If you want to keep as much readability as possible, you will need to maintain a local / source-controlled version of your mockup, complete with inserted snippets.
  • Snippet markup could probably be a bit more terse and lightweight. Your HTML is still a bit polluted.
  • What you end up editing still isn’t fully valid HTML5, so your editor might complain. But hopefully not as much as before.

Would I use it in real life?

… maybe. I’m not a designer at heart, but I can implement a flat design concept. I like the ability of being able to do most stuff within the site itself and then being able to package it and deploy it elsewhere. A lot of the time  in Visual Studio doing this before was spent in getting the solution to do what I want, activating features and such. This has now been simplified greatly, if I use this technique.

4 thoughts on “SharePoint 2013 Design Manager – It Kinda Sucks, It’s Kinda Good

Leave a Reply

Your email address will not be published. Required fields are marked *