Scenario
It’s odd, but SharePoint handles links in search results differently than you might expect. To clarify, I’m talking about those items that have a content type of “Link,” meaning they’re typically in a Links list a SharePoint site. By default, links will be displayed in search results just fine, but when you click on one, you’re taken to the display form of the link within the Links list instead of the actual destination of the link.
Expectation
Most of the customers I’ve worked with would much rather click on the link and go directly to the link, instead of having to first go to the display form, then click on the link again to finally get to it. Of course, I agree with that and that’s the purpose of this post. Let’s walk through how to create a custom display template specifically for “Link” items in a SharePoint 2013 environment.
Solution
Overview of solution steps
- Create a Links List
- Create a Managed Property and Start a Full Crawl
- Create a Display Template
- Create a Result Type
- Test Your Search Results
Create a Links List
This is necessary to ensure that you have some content to crawl in the next step. You need to have at least one links list with at least one link in it to continue. If you already meet this requirement, you can skip to the next section, “Create a New Managed Property.” Follow the steps below to create a new links list.
- Navigate to a SharePoint site of your choice.
- From the gear menu in the upper-right of the page, click “Add an app.”
- Select the Links app, give it a name, and click Create.
- Add a couple of links to the list. It’s a good idea to give them different names and URLs so that you can easily differentiate between them while testing. Also, it’s nice if they’re working links, so be sure to use working URLs.
Create a New Managed Property and Start a Full Crawl
The crawled property that contains the actual URL of a link is ows_URL. This crawled property is already mapped to an existing managed property called OWS_URL. However, if you attempt to reference OWS_URL in your display template, you’ll only get “undefined” as a return value because the OWS_URL managed property is not marked as “Retrievable” in the search schema within Central Administration. When I tried to edit the OWS_URL managed property and mark it as retrievable, I received a message stating: “The settings could not be saved because of an internal error: The managed property “OWS_URL” has an invalid name: The following invalid characters were used: ‘_’.”
Welcome to SharePoint. This is a built-in managed property with an underscore in the name, yet SharePoint won’t allow you to update it through the GUI because it has an underscore in the name. Confused? Me too. Don’t waste any more time on this and move on to create your own managed property.
I decided to create my own managed property to avoid tampering with the built-in one since SharePoint typically doesn’t like it when you change anything that’s there by default. I created a new managed property called owsURL, mapped the ows_URL crawled property to it, and then ran a full crawl. Running a full crawl is necessary for the change to take effect. Follow the steps below to create the new managed property and start a full crawl.
- Navigate to your Search Service Application within Central Administration.
- In the left navigation, click “Search Schema.”
- Click “New Managed Property.”
- Fill out the form as shown in the list below. If not specified, there’s no need to change the field.
- Property name: owsURL
- Retrievable: Yes – check this box
- Safe: Yes – check this box
- Mappings to crawled properties: ows_URL
- Click OK
- In the left navigation, click “Content Sources.”
- Now we’ll start a full crawl on the content source. Starting a full crawl can put a load on your server(s) and cause a degradation in SharePoint’s responsiveness. It’s advisable to perform this step after hours when users are not interacting with the system. Hover over the “Local SharePoint sites” content source, open its drop-down menu, and then click “Start Full Crawl.” (I’m assuming this is the correct content source. You’ll want to start the full crawl on the content source that contains your newly created Links list).
- You’ll get a prompt asking “Are you sure you want to start a Full Crawl?” If you’re comfortable with the potential performance impact to your users, then click OK.
Depending on how much content you have, the full crawl can take minutes or hours. While the crawl runs, you can move on to the next section and create the display template.
Create a Display Template
The display template controls how the search result looks and behaves. Follow the steps below to create a new display template.
- Navigate to the top-level site of your SharePoint site collection that contains your links list.
- From the gear menu in the upper-right of the page, click “Site settings.”
- Under “Web Designer Galleries,” click “Master pages and page layouts.”
- Click on the “Display Templates” folder.
- Click on the Search folder.
- Download Item_Default.html. Leave your browser open as you’ll come back to it.
- It’s not recommended to change Item_Default.html itself because it’s a default file included with SharePoint. Instead, rename your local copy of Item_Default.html to Item_Link.html and customize that going forward. This is the recommended name only because it matches the naming convention used by the other display templates. If you want to make this stand out as a customization, I recommend adding a prefix for your company name. For example, I might call mine Quisitive_Item_Link.html or something similar. You can name it whatever you like.
- Open Item_Link.html in your favorite text editor.
- Replace all content in Item_Link.html with the code in the file I’ve linked to below.Eric’s copy of Item_Link.html on OneDrive
- Save Item_Link.html.
- Switch back to your browser and upload Item_Link.html to the Search Display Templates folder. You’ll see it appear in the list there under Item_Excel_HoverPanel.html. You should also see Item_Link.js appear. This file is automatically generated by SharePoint and you never have to touch it, so don’t. J
With that, you’re done with the display template and ready to move on to the next section to create a result type.
Create a Result Type
Why is this necessary? Well, technically it’s not, but I don’t want my custom display template that I created specifically for links to be used for anything else because that would cause some confusion. The result type maps the type of search result to a particular display template. In this case, I want all search results that have a content type of “Link” to use my “Link Item” display template. Follow the steps below to create a result type.
- Navigate to the top-level site of your SharePoint site collection in which you’ll be searching. This could be a stand-alone search site collection or a content site collection that has a search site within it. Either way, it’s best to navigate to the top-level site.
- From the gear menu in the upper-right of the page, click “Site settings.”
- Under the “Site Collection Administration” heading, click “Search Result Types.”
- Click “New Result Type.”
- Fill out the form as shown in the list below. If not specified, there’s no need to change the field.
- Give it a name: Link
- Which source should results match?: “Local SharePoint Results“
- Open the “Show more conditions” section, and configure this section as shown below.
- ContentType
- “Equals any of…“
- Link
- Within the Actions section, open the “What should these results look like?” drop-down menu and choose “Link Item.”
- Click Save
- You should be taken back to the “Manage Result Types” page where you can now see your newly created result type near the top under the “Defined for this site collection” heading.
With all that hard work done, you’re ready to move on to the next step and Test Your Search Results.
Test Your Search Results
- Navigate to the search center.
- Enter a query that will return an item whose content type is Link. If you’re having trouble finding any, you can search for “ContentType:Link” and you’re guaranteed to get one if you have any.
- Verify that your search results are displaying the correct URLs visually as well as functionally. That is, you should both see the correct link and be taken to it when you click on a search result.