How to edit the SharePoint 2013 Preview file for a Master Page

In a previous post, I covered the new SharePoint Design Manager by showing how to add Device Channels and Converting an HTML page into a Master Page. I then took it to the Composed Looks available for power users and showed how to create your own Composed Look. There has been one thing that I was never really 100% comfortable with and that was the Preview file for Master Pages. In this article, I want to go in depth into how the Preview file is created and how you can customize it.

What is the Preview file associated to Master Pages?

Let’s start from the beginning, in a few articles online you may have seen the mention of a Preview file that has the same name as a Master Page and the author mentioning it’s important to have it.

We have established that now we work in the HTML file and SharePoint takes care of the Master file. But, what about the preview file, what is it for exactly and how do you change it?

Note: Don’t worry if you do not see a html file along with the Master and the Preview. The html file is for the Design Manager and is created when you activate the Publishing Infrastructure Feature.

The Preview file for Master Pages has a very precise goal.

It allows your Master Page to show up in Composed Looks:

It is also responsible for generating previews of your Master Page in different formats:

Already we can tell we are going to have some issues because of the different sizes and the different screen sizes.

Recap: We can assume that the Preview file is not a required file for Master Pages to work. It is only required if you want the Master Page to show up in the “Site Layout” menu of Composed Looks and to generate previews for the Power User before selecting the actual Master Page.

The Preview file MUST be named exactly like the SharePoint Master Page it is associated to.

Preparing the SharePoint Master Page to create a Preview file

The actual file is easy to create, simply copy paste one that already exists like Oslo or Seattle and rename it. Voilà! Your Master Page now shows up in the drop down menu for Composed Look. We saw that in my post on Composed Look so I won’t cover it here again. Our goal will be to properly edit this Preview file in SharePoint.

First let’s edit the Master Page to have something to test

To make sure I have something to test in the preview file, I need something different in a Master Page. If you were at SPC in Vegas you might want to refer to SPC065 a session they cover this very well. I am going to take a similar example by creating a Footer.

I will begin by copying the Seattle Master Page and renaming it to Sharegate.

So far, that was the easy part.

Saving your CSS file in a very specific location

I am going to start by creating a blank CSS file where I will save my custom CSS stuff. But you can’t just store it anywhere you want. Similar to the SharePoint 2010 theming engine, the SharePoint 2013 theme engine requires the CSS file to be store in the Style Library under the correct language in a folder called Themable. This is VERY important, otherwise nothing will work. The Theming engine depends on the CSS stored in that folder.

Now I will quickly reference my CSS in my Master Page directly.

Opened Sharegate.html in Edit Mode and added a CSSRegistration:

Since I am working with Design Manager (using html files) I can only edit the HTML file. The trick is to write your CSSRegistration properly or it won’t work. Remember, we are in an HTML file and not aspx.

<!--SPM:<SharePoint:CssRegistration Name="https://niaulin.sharepoint.com/sites/benjamin/Style Library/en-US/Themable/Sharegate.css" runat="server" />-->

Directly below the other CSSRegistration already there in the html file, towards the end of the <head> tag.

My CSS had a basic background-color red on the <h1> tag so after I click on save and change the “Change the Look” settings to use my Master Page I should be able to see the difference.

If you are not working with HTML Design Manager

On the other hand, the code is different if you are linking your CSS directly in a Master Page and not using any html files for your branding.

Open the .master file and add the following instead, below the existing CSSRegistration:




You don’t have to use <%$SPUrl if you don’t want to. Enter the url for your CSS file directly in the quotes of the Name= if that’s what you prefer. Beware of changing URLs though.

Let’s take it out for a spin

To make sure everything is ok so far and that we understand what has happened, let’s try some theming.

I changed the CSS in my Sharegate.css to:


h1 {

/* [ReplaceColor(themeColor:"SuiteBarBackground")] */ background-color:#FF0000;

}

This still gives me a Red background color but I also said to use the same color as the one associated to “SuiteBarBackground” in the .spcolor file we saw in our last post for the Composed Look.

Now if I go to Change The Look in the Site Actions or Site Settings and change the Color Palette, I should see the background color of the Site title change as well.

Notice that the preview does not show any of my changes so far.

Let’s click on “Try it out”

As you can see my background color took the same color as the Suite Bar Background on the top, it is now green.

Awesome! Now let’s create a footer to complete our design test

For the fun of it I want to create a quick Footer to have a new <div> in our Master Page to really show you a complete tour of the Preview file we will have to create.

Create a footer in SharePoint Master Page 2013

To create the footer I will simply create a <div> and a <span> with some text in it, most of the work will be in the CSS file. This <div> needs to be right after the closing tag of the contentBox div shown below.

</pre>
<div id="myfooter">
     <span class="myfootertext">This footer was created by Benjamin Niaulin

     </span></div>
<pre>

This gives me the following result on my SharePoint Master Page:

Now all I need to do is play with the CSS while remembering to apply theming to get what I want.

Here is what my new CSS looks like (I changed the red background on my h1 to match the blue):


h1 {

/* [ReplaceColor(themeColor:"SuiteBarBackground")] */ background-color:#0072c6;

}
h1.ms-core-pageTitle {

/* [ReplaceColor(themeColor:"SuiteBarText")] */color:#fff;

}

#myfooter {

height:32px;

width:100%;

padding:8px 20px;

position:fixed;

left:0px;

bottom:0px;

z-index:1000;

/* [ReplaceColor(themeColor:"SuiteBarBackground")] */ background-color:#0072c6;

/* [ReplaceColor(themeColor:"SuiteBarText")] */color:#fff;

}

.myfootertext {

vertical-align:middle;

}

Needless to say that with my design so far the colors of the background and the text of the Site Title and Footer will now automatically change based on the Color Palette chosen as part of the Composed Look.

Create the SharePoint Master Page Preview file

This is why you clicked on the link and arrived here, the Preview file associated to your SharePoint 2013 Master Pages. It took me a while to fully understand how it works.

It’s as if the Preview file is a Master Page on its own…kind of.

Although it is associated to your Master Page, I realized it really wasn’t that much. We name the .preview file exactly the same as the Master Page so SharePoint knows which one to pull when you need to preview it. But, the preview file really has nothing else that ties it to your Master Page. It’s a Master Page on its own that needs to be modified.

After all my modifications on the site title and the footer I added, here is what my preview looks like:

and

A big problem with the Preview file

As you just saw, there are at least two sizes the preview of your SharePoint 2013 Master Page comes in. What do you think will be my problem?

All sizes in CSS will have to be re-written to use % instead of pixels. That is going to be a pain.

Understanding the SharePoint Preview file

First thing you need to know is that the best way to look at it is as Text.

The SharePoint Master Page Preview file is split into four sections.

I skipped through the large file to give you smaller screenshots above.

So we have 3 [SECTION] separating the file into 4.

  1. The first section identifies which .spcolor file you would like to use in this preview. This is really for the first screen when you are choosing between multiple “Looks”, the Gallery if you want. This has nothing to do with the .spcolor file associated to your Composed Look, it’s really only for the preview.
  2. The second section identifies the .spfont file you would like to use in this preview. Again this is the same thing as the .spcolor file. So far so good.
  3. The third section is crucial, it’s the CSS. However, it’s not the CSS you are used to. You will notice that they all have a prefix of [ID]. This is to identify which theme this CSS property is associated to. Remember that all the Preview files will be loaded at the same time on a single page. It’s important for each of these to have the [ID] in front.Also it is very important to use ONLY CSS Classes and no IDs! Let’s put some perspective on it.

    All these previews above are using [ID] in front of each of their CSS styles to identify which square it will be associated with. What do you think would happen if we started using Id’s instead of classes inside our styles? (Do not confuse [ID] with a CSS style that references an Id)

    It is extremely important for us to use CSS classes only in our preview file.

    A common practice is to name your CSS classes in the Preview file with .dgp-nameofclass. The dgp stands for Design Gallery Preview and is not necessary, it’s really just following a naming convention that SharePoint already has.

    Remember to use only % in your CSS for sizes and not pixels.

  4. The fourth section is the HTML that is shown in the Preview of the Master Page.

Let’s add our changes so the Preview file reflects our changes

The first 2 sections defining the font and the color palette I wish to use, I don’t really need to touch in this scenario because I didn’t create any custom ones. What I do need is to define my new CSS classes in the 3rd section and add the additional HTML in the 4th.

I started with the last section to add my HTML in there, it looks a lot like the HTML we used for the actual Master Page except it uses classes and not IDs.

</pre>
<div class="dgp-myfooter">
     <span class="dgp-myfootertext">Preview of the Footer text is here

     </span></div>
<pre>

As for the CSS in the Preview file of the Master Page:

Simply go to the end of the CSS Section and copy paste your CSS classes.

Every selector needs to have an [ID] token and remove the selectors that are using Ids and use classes. (like we did in the section 4) I also need to change all the attributes using pixels into percentage and rename them to .dgp-nameofclass. Also, since the preview file does not use the theming engine we will have to replace the annotations defining the theming colors into something that can be used in the preview file. Tokens that will be picked up by a JavaScript SharePoint uses.

Here is what the CSS looks like in my Preview file after I copy pasted at the bottom of the 3rd section and made my modifications:

[ID] .dgp-myfooter {

height:4%;

width:100%;

padding:1% 2%;

position:absolute;

left:0px;

bottom:0px;

z-index:1000;

background-color: [T_THEME_COLOR_SUITEBARBACKGROUND];

color: [T_THEME_COLOR_SUITEBARTEXT];

}

[ID] .dgp-myfootertext {

vertical-align:middle;

}

Let’s look at the changes

After I saved all my files I went back to Change the Look menu in SharePoint 2013 and this is what I saw.

Notice that my footer now shows up in the small preview, let’s try the larger preview.

Try changing the colors everything will work as expected since we used the Tokens to define the colors for both the background and the text of the footer.

Conclusion

There are other new cool things like the ThemableForegroundImage with SharePoint 2013 that use the Theming Engine. We will cover that in a next blog post. Right now we covered extensively the Composed Look and the Design Manager throughout all my blog posts. Hope this helps you edit the Preview file that is associated with your Master Page, it took me a while to figure it out and frankly, the SPC Session that covered it really helped. The Master Page Preview file feels to me as a master page of its own just with different ways of writing it.

This should show some very interesting concepts inside your company, to create these “Composed Looks” and allowing the Power Users the control of choosing different colors based on their region, team, etc… But keeping a standardized company Look and Feel.

Advertisements

6 thoughts on “How to edit the SharePoint 2013 Preview file for a Master Page

  1. Pingback: How to edit the SharePoint 2013 Preview file for a Master Page | AllThingsSharePointCanada

  2. Pingback: The NEW SharePoint Color Palette Builder Tool | Benjamin Niaulin [SharePoint MVP]

  3. Todd Ryan

    Hi, I am not having any luck with it in SP. I mean it works, but if you resize the page it stays where it was and any body text will hide behind the footer and the page will scroll past the footer. Have you tested this scenario or am I missing something her?

    Thanks in advance!

  4. Patrick Groen

    It seems users need more than read permissons to be able to see the result a the custom css in the Themable folder. Am I right? After I granted contribute permissions to a user, the branding was available.

Comments are closed.