Corey Roth [MVP]

SharePoint Designer is quite useful in the development cycle of display templates.  It's on the of the quickest ways to make changes.  Design Manager is probably one of the better routes, but if you have issues using it, SPD is not a bad option.  There are a few quirks though when working with SharePoint Designer, so I wanted to show my tips today.

1) Know how to find your display templates

The first thing to know is where to find your display templates.  This is not as obvious as you would think.  Use SharePoint Designer and open the site collection hosting your site (even if your Content Search web part is on a subsite).  You might think, I can find them under Master Pages because that's where they are actually located.  Wrong.  Here is what happens.

When you browse to Master Pages -> Display Templates -> Content Web Parts, you get an empty folder.  That's because SPD is filtering for files with a .master extension.  You can tell because Master Pages is highlighted.  How do you get around this?  You have to browse using All Files.  For those of you around in the 2007 era, this might look familiar. 

Click on All Files -> _catalogs -> masterpage -> Display Templates.  Once you do, you'll be able to find all of the templates you would expect.

2) Edit files in advanced mode

Due to this little quirk, using this next tip will save you a lot of clicking.  Depending on how you open the file and then edit it, when you go back to the file list, it will reset to Master Pages and then you won't see any files in the browser.  You can avoid this, by always choosing Edit File in Advanced Mode from the context menu.

3) Be aware of save conflicts

A save conflict is going to cost you a minute of your life that you'll never get back. When it happens you will get an error like the following.

Server error: Save Conflict

Your changes conflict with those made concurrently by another user.  If you want your changes to be applied, click Back in your web browser, refresh the page, and resubmit your changes.

After that you will get a Save as dialog. 

Just click Save and surprisingly the file will save without any other issues.  I see this issue happen mostly after copying a file -> renaming it -> and then trying to save.  To work around it, copy the file, edit it first, and then rename it.

4) Watch your encoding when renaming files

For some reason after you copy and rename a display template, the encoding will get messed up.  Take a look at the screenshot below.

Notice on the ManagedPropertyMapping line it shows ' instead of a single quote?

You can correct this by doing Reset to Site Definition on the file.  After you do, be sure and delete the duplicate copy it makes, because it will show up inside your Content Search web parts.

5) If you first don't succeed, try, try again

For some reason, when you click on All Files occasionally, it will just sit there forever and never return any results.  If this occurs, just click on something else such as Home or Subsites and then click back to All Files.  That usually fixes it.  If all else fails, close SPD and start over.

6) Forever unghosted even after Reset to Site Definition Perhaps the biggest caveat when working with SharePoint Designer is that your files will be forever unghosted / customized.  Even if you reset to site definition, the files will remain customized as indicated by the big "i" icon.  The original file will get restored and your current version will be renamed as a copy though.  That means the good news is that you can get back to the original version.  The bad news is your file is still customized. 

Keep that in mind when working with SPD.  This might be acceptable in your development lifecycle.  You can always build your templates in SPD and then deploy them later via Design Manager.

More at SPC14

Why do I keep blogging about Display Templates lately?  Because, I am speaking about them at my talk (#SPC3000) at SharePoint Conference 2014.  Be sure and attend if you want to learn more!

Also if you haven't seen my post Four tips for working with jQuery and DIsplay Templates, be sure and check it out!