I did it, I launched myself into the unknown today and built myself a Display Template in SharePoint 2013. To be honest, it’s a lot easier than I originally thought, as long as you have some basic understanding of HTML and CSS. My favorite feature in SharePoint 2013 is the Search and everything that comes with it, that’s why instead of building a custom HTML menu that will only work on one page, I wanted to build something that is reusable, requires little to no code and is powered by the Power Users entries. What I mean by that is I want a regular SharePoint Power User to be able to choose what the menu is going to show.
Here is what we’re going to build, the finished Display Template is available at the end of this article:
Why SharePoint Search and why Display Templates?
One of main factors that made me migrate to SharePoint 2013 is Search and all the upgrades it brings to the table. In the past, I was often limited to my Site Collection or finding a developer to get something done. The thing is, I don’t code! I am one of those IT guys that got pulled into SharePoint by its massive vortex. Don’t get me wrong, I love SharePoint, but it doesn’t make me a developer. So I am always looking to find ways to build things that are easy to use for me and my Power Users.
Well I won’t go over the details again as I have in the past, but it was completely revamped, including the FAST technology. What makes it all worth it are the changes to the Search Results Web Part and the new Content Search Web Part.
If you want to learn more about those, check out my previous articles as I will assume you know how to build the Query in these Search Web Parts.
What is a Display Template?
If you have worked with the Content Query Web Part, this will sound very familiar. Display Templates are effectively simple designs that you build, that will be reusable by a particular Search Web Part. For example, if you build a Display Template for the Search Results Web Part, it will be the only one to be able to use it. However, it will be reusable in many contexts. See it this way, if you build an animated menu, well it’s the Search Results that will populate the content. So you can use it to show Tasks, Documents, Pages, etc… Very useful, especially for Cross-Site Publishing in SharePoint.
Understanding SharePoint Display Templates
To build your own « Reusable Design » you will need to build your Display Template in pieces. You will see that Display Templates are made of different types of files.
As you can see above, the Control of this Display Template is the main container that says whether or not there should be paging for example and how to load the results.
Then, we have the « Item » part of our Display Template, similar to itemstyle if your remember the Content Query Web Part. The Item tells SharePoint how to render each individual items returned by the Web Part in question. This is usually where most of our custom HTML goes as we try to make individual items look good. Here is where the Item part of our Display Templates are:
Note that Control and Item Display Templates are individual files that do not necessarily have to work with one another. Let me explain, if you build a Control and Item Display Templates to show something, it doesn’t mean that the Control part HAS to be used with the Item Display Template you have built, they are completely independent from one another. It’s in the Search Web Parts that you will specify which Control to use and which Item to use. Therefore you can have built a container or « Control » that has many different ways of showing items with different « Item » Display Templates.
Managed Properties: I wish I could cover Managed Properties as a small section of this article but unfortunately, I cannot. There is a lot to cover and I strongly recommend you learn what Managed Properties are and how to use them properly before continuing. Essentially when Search looks at its index, it sees Managed Properties that contain one or multiple « Crawled Properties » as well as some settings that say how we can use this Managed Property. The Search Web Parts can only display Managed Properties, this isn’t the same as your « Metadata » or Column Names.
I know, sounds complicated doesn’t it… It’s not that bad, but you will need to understand it before building your Display Template.
To tie this in to the Display Template we’re about to build, you can only show Managed Properties in your HTML. Of course you can add your own custom content manually, but if you are looking to add SharePoint content in your template based on Search Results you will need to declare the Managed Properties you are about to use and only use those. The beauty of the Content Search Web Part is you will be able to do a lot of it manually through the Web Part settings.
Start building the Control Display Template for our SharePoint menu
I hope this article will help you build more Display Templates in the future. Personally, I asked my colleague Yohan, author of Image Slider with SharePoint 2013 Search Results Web Part to help me get started. I went to Codrops and downloaded the source files, all of them. Of course, the menu there is not made for SharePoint at all, which means we’re going to have to do a lot of changes for this to work in our context.
I’ll look at the index.html using my browser and you’ll notice that there is a lot of extra stuff we don’t need. They did that plugin to showcase how to do it and for the regular web, SharePoint already codes with tons of CSS.
Before you begin, we’ll need to upload all of the folders in our Style Library. Of course you can store them somewhere else, as long as people will be able to read these files you are fine. Then we will change our Display Template to link to this new location, wherever you chose to store them. I am going to create a folder in my Style Library called « Sharegate » and store them inside of it.
And within it, I uploaded all of the files except the index HTML file.
Now that we organized ourselves properly, we can start looking at the HTML and the CSS that actually make up the animated menu. What we need to do, is open the index file that came in the download and identify what will go in the Control and what will go in the Item Display Templates. Let’s take a look.
Here is what my Control Template looks like, by simply cutting the pieces I need.
You’ll notice however that I told SharePoint to load the context RenderItems within the <ul>, basically I am telling it that this is where the Item Display Template will start in a way.
Remember one thing, your Display Templates should always have a div, the first one will not be rendered but is necessary for SharePoint to recognize where to start.
We can now upload our Search Results Display Template under _catalogs/masterpage/Display Templates/Search/ because this is a Search Results Display Template. You’ll see a JS file with the same name automatically get created, do not touch that file.
Editing the Item Display Template for our SharePoint menu
This is where all the magic happens, the first thing we absolutely need to do is tell SharePoint what Managed Properties we plan to use in this Display Template. So under your ManagedPropertyMapping in the <head> of your Item Display Template, make sure you enter the name you want to use with the Managed Properties that will be assigned to it. By default, we already have a few like Title and Path.
The next thing I did was create variables, though it wasn’t necessary it makes it easier when writing our template. All I really did is copy the <li> section of the HTML file and change the fields for the hyperlink and span to variables returned from the Search Results using Managed Properties.
Let’s upload this to the same location as our Control Display Template under _catalogs/masterpage/Display Templates/Search/.
And we’re done! Now, wherever you add the SharePoint Search Results Web Part, you will be able to change the way results appear to make them like the menu we’ve built.
Here is our result:
Reusable Search-Driven SharePoint menu
The cool thing about what we’ve done, is that we used Search. Our hard work on the Display Template can easily be reused by everyone in our organization. For example, I see us using the menu to replace our Tiles when we create a new Team Site. But since we are using the Search Results Web Part, we can show anything we want with this menu and that is truly wonderful. We can adapt the Search Query to show Tasks from the Site Collection that are assigned to the current user and still not completed. Or show the organizations latest announcements, tailored to each user that visits because remember, this is using Search. We can easily create contextual queries based on who visits the page, filter by User Profile properties and more. The possibilities are incredible, because with Display Templates all we do is build a beautiful design, any type of content returned will be able to fit and use the Display Template. Even a Task list can be a Slider or Image Carousel, as long as you have a column with a hyperlink to a picture.
My hopes is that you see how powerful Search with Display Templates can be and start exploring this.
SharePoint 2013 Animated Menu Display Template Download
Copy the Sharegate folder in your Style Library and the Display Templates under _catalogs/masterpage/Display Templates/Search/.
You can also visit my friend Yohan's blog and download the Slider Image Display Template.
Session Recording: I presented at the Boston SharePoint User Group as well as a few others on this particular subject. Hopefully the recording of building killer visuals with SharePoint Search and Display Templates will provide you with better insight on how to use this feature.