Add and configure the Recommended Items and Popular Items Web Part in SharePoint Server 2013

This is a blog post in the series “How to display Recommendations and Popular items on a website”. In the previous post, I showed you how to modify the Content Search Web Part (CSWP) to log the Views usage event, and how you can use Windows PowerShell to start Usage analytics. In this blog post:

Note: The examples in this blog series are based on an on-premises installation.

Add a Recommended Items Web Part to a page
Navigate to the page where you want to add the Recommended Items Web Part (RIWP). In our Contoso scenario, we want to add the RIWP to our catalog item page. Do the following:

1.  Select the Settings menu --> Edit page.
2.  In the Web Part Zone where you want to add the Web Part, select Add a Web Part.
3.  In the Categories list, select Search-Driven Content.
4.  In the Parts list, select Recommended Items, and then Add.

In our Contoso scenario, we‘ll show the RIWP below the CSWP.

RIWP added to item page

About the recommendedfor managed property
In a previous blog post, I told you about the UsageAnalyticsId managed property that is used by Usage analytics to specify how recommendations between individual items should be calculated. The result of this calculation is sent to the recommendedfor managed property. The RIWP uses the recommendedfor managed property to query for recommendations. You don’t need to know about this managed property when you configure the RIWP. But, to understand how the query in the RIWP works, it’s important that you keep the recommendedfor managed property in mind.

Configure the Recommended Items Web Part
When you configure the RIWP, you should configure it on an item details page where recommendations have been generated.  Remember, in a previous blog post I told you how I generated recommendations by inviting some co-workers to a “click party.” At this “click party” I told my co-workers to click specific items so that recommendations would be generated. So, in our Contoso scenario, I added the RIWP to an item details page where I knew recommendations had been generated through the clicking of my co-workers.

Here’s what you should do to configure the RIWP:

1.  Select the Settings menu --> Edit page.
2.  In the RIWP, select the Web Part Menu --> Edit Web Part.

Edit Web Part

3.  In the Web Part tool pane, select Change query. This will open a dialog box.
4.  In the Build Your Querydialog box, select the following:

  • In the Get recommended items for section, select A token from the URL and then select from which URL value you want to get recommendations. In our Contoso scenario, we want to get recommendations from {URL.Token.2} (number) .
  • In the Restrict by app section, select Specify a URL, and then enter the URL of your catalog.

Configure query for RIWP

So now you might be thinking "OK, that was easy, but what does this actually mean?" Well, understanding what this means is a bit complicated. So, let’s take a deep breath and take a closer look.

  • A token from the URL means that we want to get recommendations for a value that is used in the URL.
  • {URL.Token.2} is a query variable that represents the second value in the URL as counted from right to left. For example, in the URL https://www.contoso.com/computers/desktops/5637145799/5637146352, the query variable {URLToken.2} represents the value 5637145799.  Remember, when we connected our publishing site to the catalog, we specified that the value of Group Number should be used as the second to last value in the URL of our catalog item page. That means that the query variable {URL.Token.2} represents the value of Group Number.  Also, we mapped UsageAnalyticsID to Group Number so that the Usage analytics calculation would be based on Group Number
  • Specify a URL means that we want to specify from which site we want to get recommendations, in this case our Authoring site.

But from these settings, it’s not clear which managed property is used in the query. So, to view more information about the query, select TEST. The query that is issued by the Web Part is shown in the Query text section.

Query text in RIWP

If we break this down, we get the following:

  • recommendedfor is the managed property that is used in the query.
  • The colon : means “contains.”
  • 5637145799 is the value of the query variable {URL.Token.2}, which is a Group Number value.
  • path:"https://ib-perf-8/sites/catalog" is the URL to our Authoring site.
  • (IsDocument:"True" OR contentclass:"STS_ListItem") narrows the search result down to only documents or list items.

If we put all this information together, we can understand that the query means the following:

From the URL of the Authoring site, search for document or list items where the value of the managed property recommendedfor contains the value that is currently used as the second value in the URL, counting from right to left.  

So, now we know what the query means. But we’re not quite done with the configuration. In the SEARCH RESULT PREVIEW section, we can see that all items in a product group are displayed, for example all SV Keyboard E10 (notice that they all have the same value for Group Number in the URL).

Recommended items in groups

All items in the product group are shown because the Usage analytics calculation is done on the group level (remember, we mapped UsageAnalyticsId to ows_ProductCatalogGroupNumber). But we only want to display one item per product group.

Luckily we can do this by grouping search results. To group search results, do the following:

5.  Select REFINERS --> Show more.

Select Show more on REFINERS tab

6.  From the Group by menu, select Show all properties.

Show all properties for grouping results

7.  We want to show only one item per product group, so we select ProductCatalogGroupNumberOWSTEXT (the managed property of Group Number). We only want to display one item per group, so we leave the value in Show there results as 1.

Group by ProductCatalogGroupNumberOWSTEXT

In the SEARCH RESULT PREVIEW, we can now see that only one item per product group is shown.

One item per group is recommended

8.  Select OK to save the changes.
9.  In the Web Part tool pane, in the Number of items to show field, enter how many items you want to display in the Web Part.

Number of items to show

10.  Select OK, and save the page.

Even though it doesn’t look good, good recommendations are now displayed on our catalog item page.

Recommendations displayed in Web Part

About the display template that is used by the Recommended Items Web Part
Just as you do with the Content Search Web Part (CSWP), you use display templates to control how content should be displayed in a RIWP. In an earlier blog post, I explained how you can upload and apply display templates to the Content Search Web Part. You can do the same for the RIWP, but the display template that is used by the RIWP contains important code that logs the two usage events Recommendation Displayed and Recommendation Clicked

Remember, in an earlier blog I told you that there are three default usage events in SharePoint Server 2013. The usage events Recommendation Displayed and Recommendation Clicked are used to record statistics of how visitors have interacted with the content on your website. When an item is displayed as a recommendation, a Recommendation Displayed usage event is recorded. When an item is clicked on when it is displayed as a recommendation, a Recommendation Clicked usage event is recorded. I will show you how you can view these statistics in a later blog post. 

In the previous blog we modified the CSWP display template to log the Views usage event. The logging of the Recommendation Displayed and Recommendation Clicked usage events are done in the RIWP. The default display template that is used by the RIWP is Item_RecommendationsClickLogging. This display template contains the two functions LogRecsViewToEventStore and LogRecsClickToEventStore. These two functions log the Recommendation Displayed and Recommendation Clicked usage events.

LogRecsViewToEventStore function

LogRecsClickToEventStore function

When you change your RIWP display template, you should copy the Item_RecommendationsClickLogging file, make changes to the copied version, and apply it to your RIWP. That way you don’t have to worry about adding code in the same way that we did for the CSWP.

After applying the changed display template to the RIWP, the recommended items are displayed nicely.

Recommendations displayed with images

Add a Popular Items Web Part to a page
You can display the most popular, that is, the most viewed, items within your catalog by adding a Popular Items Web Part (PIWP) to your category page. It’s important to understand that when you add a PIWP to your catalog page, the PIWP will automatically show the most viewed items within each category. For example, if a visitor is viewing the Cameras category, the PIWP will show the most viewed items within the Cameras category. If a visitor is viewing the Camcorders category, the PIWP will show the most viewed items within the Camcorders category.

To add a PIWP, navigate to the page where you want to add the PIWP. In our Contoso scenario, we’ll add a PIWP to our category page. Do the following:

1.  Select the Settings menu --> Edit page.
2.  In the Web Part Zone where you want to add the Web Part, select Add a Web Part.
3.  In the Categories list, select Search-Driven Content.
4.  In the Parts list, select Popular Items, and then Add.

In our Contoso scenario, we‘ll show the PIWP above the CSWP.

PIWP added to page

Configure the Popular Items Web Part

1.  Select the Settings menu --> Edit page.
2.  In the PIWP, select the Web Part Menu --> Edit Web Part.

Edit Web Part

3.  In the Web Part tool pane, select Change query. This will open a dialog box.
4.  In the Restrict by app section, select Specify a URL and enter the URL of your Authoring site.
5.  In the Restrict by tag section, select Restrict by current and child navigation terms.

No results are displayed in the SEARCH RESULT PREVIEW section. What’s going on?

No popular items returned

To find out more about the query that the PIWP issues, select TEST. On the TEST tab we can see the Query text.

Query text for PIWP

The query text means the following:

  • path:"https://ib-perf-8/sites/catalog" is the URL to our Authoring site.
  • owstaxIdMetadataAllTagsInfo is the managed property that is used in the query.
  • The colon : means “contains.”
  • #91eb9f0d-3e5a-41a8-8487-78dfe234ca7c is the GUID of the current category. In this example the current category is Cameras.
  • (IsDocument:"True" OR contentclass:"STS_ListItem") narrows the search result down to only documents or list items.

If we put this information together, we can understand that the query means the following:

From the URL of the Authoring site, search for document or list items where the value of the managed property owstaxIdMetadataAllTagsInfo contains the GUID of the current navigation category or any of the children of the current navigation.

An important piece of information that we can see in the query text is that the PIWP uses the owstaxIdMetadataAllTagsInfo managed property in its query. You can’t change the query in the PIWP to use another managed property. That means that for the query in the PIWP to work correctly, the owstaxIdMetadataAllTagsInfo managed property needs to include the value of the managed property that we use to drive managed navigation.  In our Contoso scenario, the managed property that drives managed navigation is owstaxIdProductCatalogItemCategory. So, what we need to do is to map the crawled property of owstaxIdProductCatalogItemCategory to the owstaxIdMetadataAllTagsInfo managed property. 

I showed you how to map a crawled property to a managed property in an earlier blog.

IMPORTANT: You have to do the mapping on the Authoring site.

In our Contoso scenario, the correctly mapped owstaxIdMetadataAllTagsInfo property looks like this:

New crawled property mapping

After you have changed the mapping of the property, you have to start a full crawl.

But there is one very important thing that you can’t see in the query text, and that is how the search results are sorted. The PIWP sorts search results in a descending order on the ViewsRecent managed property. By default, the ViewsRecent managed property contains the number of views for an item within the last 14 days (I’ll show you how you can change this to, for example, the last 7 days in another blog article). This means that the query issued by the PIWP will do the following:

From the URL of the Authoring site, search for document or list items where the value of the managed property owstaxIdMetadataAllTagsInfo contains the GUID of the current navigation category, or any of the children of the current navigation. Sort the search results in descending order of views for the last 14 days.

When the full crawl has finished, you’ll see search result in the Web Part.

Popular items are returned

6.  Select OK to save the changes, and save the page.

Popular items displayed in the Web Part

To display the popular items nicely, you can apply a display template in the same way that you did with the CSWP.

To check that the PIWP is working correctly, go to the Cameras section. On this page, the most viewed items within the Cameras category are displayed.

Popular cameras

When we go to the Camcorders category, the most viewed items within the Camcorders category are displayed.

Popular camcorders

Our PIWP is working the way it should. Nice!

So now you know how to configure the RIWP and the PIWP. You might have noticed that throughout the examples I showed, I was always logged in to my account.

Logged in user

In the next blog post, I’ll explain how all of this works if the website only has anonymous users, that is, users who’re are not logged in.

Next blog post in this series
Use recommendations and popular items on websites with anonymous users.