In my previous blogpost I already introduced the SharePoint Display Templates. This blogpost is more like a collection of small things that I ran into while working with Display Templates.
Types of Display Templates
There are different types of Display Templates in SharePoint and of every type there is already a number of templates available in SharePoint. Therefore it is advisable to check if there's any Template already present that fits your needs (For me it's never good enough so I always end up creating my own templates ☺). If you even want to make a tiny difference to the standard templates, don’t change the standard template, but instead copy it and create a new custom one.
You can find an overview of types of- and standard Display Templates here.
Managed Properties
Managed Properties are SharePoint columns which can be retrieved by Display Templates. These come in all shapes and sizes, so there are several different ways to display them. More about that later in this blogpost.
In SharePoint there are more properties than just the Managed Properties, they're called Crawled Properties. It's not possible to retrieve the value of these Crawled Properties directly in the Display Templates. You have to map them to a (existing or newly created) Managed Property. You can read here how to do that.
Personally, I used a Site Collection in SharePoint Online, which means I didn't have access to Central Admin. Instead I created the Managed Properties from within the site collection via this url:
https://[JourDomain].sharepoint.com/_layouts/15/listmanagedproperties.aspx?level=sitecol
Retrieve Managed Properties
In the <head> section of the Item Display Template, there's a <mso:ManagedPropertyMapping msdt:dt="string"> tag. That's where you should define
the Managed Properties which you want to retrieve. It looks something like this:
<mso:ManagedPropertyMapping msdt:dt="string">'Link URL'{Link URL}:'Path','Line 1 code'{Line
1}:'Title','Line 2 code'{Line 2}:'Description'</mso:ManagedPropertyMapping>
The syntax to define a Managed Property looks like this:
'Property Display Name'{Property Name}:'Managed Property Name'
- Property Display Name is, according to Microsoft, the property name that
shows in the Web Part editing pane when the display template is selected. I don't really get what they mean here. I don't see it anywhere. If anyone knows more
about this, I'd be happy to hear about it!
As far as I know, this is the value with which you call the Managed Property in the script on the Display Template. - Property Name is an identifier that uses localized string resources to look up the name of the managed property. It is also the value that appears
in the Property Mappings section of the Web Part settings menu. When you edit the settings for a Web Part, you can change this value to change what managed property
is associated with the field that appears in the Web Part.
This property is only useful if the Web Part settings menu has the 'Property Mappings' option. If it has not, you can skip this part of the syntax and just use this:
'Property Display Name':'Managed Property Name' - Managed Property Name is a string of one or more managed properties, separated by semicolons. At run time, the list is evaluated from left to right, and the first value that matches the name of a managed property of the current search item will have its value mapped to this slot. This enables you to write a display template that can work with multiple item types and that can use consistent rendering if compatible properties are present.
After you map a property, you can get its value in script by using the following code inside the <body> tag:
<!--#_
For this example, I have partially copied the standard SharePoint TwoLine Item Display Template (and modified it a bit), because it makes it very clear where the three different
values show up.
var title = $getItemValue(ctx, "Line 1 code");
_#-->
You can use variables within the sections of JavaScript as you typically would, to manipulate variables and create HTML strings to be rendered on the page at run time. But,
to reference variables declared in the script directly in the HTML, you must use the following format:
_#= variabele =#_
In case of a text value it makes sense to use this syntax:
_#= $htmlEncode(variabele) =#_
The htmlEncode encodes the characters that can crash a script. For example, a quote (') will be encoded to '.
Take a look in the standard Display Templates library that SharePoint has to see what the possibilities are. Furthermore, this website has a lot of valuable information about scripting in Display Templates.
Displaying images
The image and icon Managed Properties actually consist of just text, a url to be precise. To convert it to a visible image, you have to call the Managed Property inside the
src of a <img> tag. It would look something like this:
<img src="_#= variabele =#_" alt=""
/>
There is a catch here though. SharePoint doesn't like urls with spaces in it… Usually spaces are converted into %20, but unfortunatly not in this case. Therefore you have
to make sure that the Picture Library in which the images are stored, does NOT contain spaces. Another option is to put some JavaScript together that turns spaces into %20 (don't
know how to do that, never tried).
Displaying dates
This is a nice one as well, because you have the freedom to choose the format you prefer. It could look something like this:
_#= variabele.format("d MMMM yyyy") =#_
You can also split up the date. I created a colored square myself, in which I displayed the date in two separate pieces. The day and month are displayed below each other
instead of inline:
<div class="date-formats">
<span>_#= variabele.format("d") =#_</span> <!-- day in integer -->
<small>_#= variabele.format("MMMM") =#_</small> <!-- month in string -->
</div>
There's an overview of all available date formats here.
Displaying file type icons
File type icons are a special case, because it doesn't work the way you would expect, at least not in Search Result Display Templates (no idea why, but it is what it is). The file type icon is the little icon in the first column, for example in Document Libraries, that indicates the type of document. It can be a MS Word icon, or Excel, PDF, etc.
To get it done anyway, we're just going to steal it out of a ContentBySearch Display Template. Here's how to do that:
-
Add the following code into the tag of the Control Display Template:
<script>
$includeScript(this.url, "/_layouts/15/search.cbs.js");
</script> -
Add the following line of code to the '<!--#' section in the Item Display Template:
var iconUrl = Srch.ContentBySearch.getIconSourceFromItem(ctx.CurrentItem); -
Call the variabele in an <img> tag like this:
<img src="_#= $urlHtmlEncodeString(iconURL) =#_" />
And we're done! I didn't cover any styling here, so it might be that you still have to fix that. I'll soon release a detailed tutorial about creating a 'My Documents' Display Template, in which I also cover the file type icon.
Well, that's it for now, hopefully this was useful to you ☺
Wil je dit in het Nederlands lezen?
No comments:
Post a Comment