Customising the Content Search Web Part – Part 1 – What you get in the box

This is the first post in a series I will be writing on the Content by Search Web Part (aka CSWP).
  1. What you get in the box (this post)
  2. Custom Display Templates with JavaScript
  3. Going Old Skool with XSLT
  4. Packaging & Deployment in Visual Studio

Search is quick, Search is vast, Search is better .. Well where do I start? SharePoint 2013 is all about Search. It has a completely rebuilt search engine which incorporates a lot of the awesome power that Microsoft gained from FAST over the years.

I’ve seen, a lot of SharePoint projects over the years which have been based heavily around Search, typically using custom developed web parts based on the Search Core Results web part. Because the core search web parts used XSLT for their rendering we could totally customise the interface and output. They included an out of the box “paging” capability and through the query syntax you could build quite sophisticated queries.

Search gives you the ability to pull immensely vast amounts of information from your sites (or other sites, public websites, file shares, even Exchange!) and return them in an extremely quick fashion. In terms of querying and returning information it is formidably fast the only real  downside being the time it takes for search to actually index your content (which even on a well optimised farm was only going to be around 15 minutes at best). SharePoint 2013 introduces Continuous Crawls which basically allows content to be indexed almost immediately (with typically around a 30 second delay).

Even without those indexing issues though the main problem with these search based approaches is that they tended to have very unsophisticated editing capabilities for the people building the pages. You needed to have a damned good knowledge of the Search Keyword Query Syntax and this was just yet another hurdle for editors who are just trying to put pages together

Enter the Content Search Web Part!
The SharePoint 2013 solution to this is the Content by Search Web Part (CSWP) which is basically designed to be a replacement for the trusty Content by Query Web Part (CQWP) which we have been used to using in most of our projects in SharePoint 2007 and 2010.

This includes a number of outstanding features:

  1. Very advanced “query editor” which use a separate pop-up dialog. This allows you to define very complex search queries to bring back almost any granularity of information
  2. Query shortcuts are also built into the query editor, so you can easily tell the web part to only return content from the current site, or site collection, or just return documents / pictures, or a whole range of other content.
  3. A range of different Display Templates are provided allowing you to switch between different “styles” (including paging!). These templates are fully extensible and adding your own custom templates will be covered in Part 2 of our series.
  4. The values being shown in the output can be controlled and modified using “Property Mappings” (which is covered later in this post).
  5. User Profile Tokens allow values in the current user’s profile to be swapped out “on the fly”. This is massive! This alone makes the CSWP worthwhile (e.g. pull back all news articles tagged with the user’s department?)

I could go on because this web part is immense and in every way an improvement. The performance is lightning quick and if you aren’t using it then you really need to consider why not!

The “Build Your Query” wizard
The first thing we will look at is the query editor. This is a fantastic new wizard interface which you can access from the Web Part properties.

Change Query pops up the Build Your Query pop-up

This allows at first a basic mode which allows you to select from various prebuilt result sources. This in itself probably allows you to meet 90% of your search requirements.

In Basic Mode, you can pick from result sources, restrict by site / URL and access basic selections

The basic mode also allows access to an easy “Restrict by app” which effectively means “restrict by URL” but allows you to easily pick “Current Site” and “Current Site Collection”.

In Advanced mode you can construct pretty much any query you want using the SharePoint 2013 Keyword Query Language (KQL) Syntax.

Advanced Mode allows extensive custom KQL queries, such as the above which returns people who have a profile picture and their “About Me” section contains the word “SharePoint”

You can even refine this further using the “Refinement” panel which allows you to cherry pick different values in a very similar fashion to the refinement panels you will have seen in SharePoint search results pages.

You can cherry pick refiners to trim down the results, much as you would if you were viewing a Search results page.

You also have an ever-present “Test Results” panel on the right hand side which allows you to view what you might get in your results given the current settings…

One other new addition is a new user token which allows you to include properties from the current user in your search queries dynamically (clearly great minds think alike… ).

Adding the current user puts {User.Name} in the query

Using the “Name of the user who runs the query” token places a construct of {User.Name} which will basically replace that with the name of the current user each time the page is accessed. I have found however that you can swap this out with other user profile properties as well (such as {User.Department} or {User.JobTitle} .. however not all of them seem to work, some experimentation is required!).

This provides an amazing opportunity to create truly personalised feeds of information where the results are relevant to the current user, based on whatever they have selected in their profile.

.. All in all, this is a fantastic improvement over any of the previous query editing interfaces in SharePoint, and allows you to configure in some cases extremely complex queries.

Switching Display Templates and Configuring Property Mappings

Note – in Part 2 of this series we will look at building our own custom Templates, but for now we will be looking at how we can customise the look using the out of the box templates.

Now this should be familiar to anyone who is used to working with the Content by Query Web Part.

First up lets talk about the display templates. A bunch of these come out of the box and basically control the look and feel of the contents of the web part. There are two types which you can select:

  • Control Templates – These determine the rendering container or wrapper of the contents
  • Item Templates – These determine the rendering of each item which is returned in the results
Display Templates are picked from the Web Part Properties

These are all JavaScript based, so you might see some delays before it renders, but they are in my experience both fast and adaptable.

The specific templates you get are:

Control Templates

  • List
  • List with Paging
  • Slideshow

Item Templates

  • Diagnostic
  • Large Picture
  • Picture on Left, 3 Lines on right
  • Picture on Left, 3 Lines on bottom
  • Recommended Items: Picture on Left, 3 Lines on right
  • Two Lines
  • Video

Most of these should be pretty self-explanatory but some of them deserve special mention.

The List with paging control template adds next/previous paging controls (implemented using Async JavaScript) while the Slideshow control template provides a javascript based fade-in / fade-out animation.

The Video item template actually adds an HTML5 video object but probably the most useful one is “Diagnostic”. When picked this displays detailed information about your Property Mappings which is what allows you to really understand what information your Content by Search Web Part is displaying ..

Property Mappings
So .. what are these property mappings and what do they do?

Well .. you remember some of the difficulty in trying to map fields to a Content by Query web part (and passing them back to the back-end XSLT)… well the Content by Search Web Part uses Property Mappings which map to Display Templates (which are JavaScript powered) .. and it works incredibly well!

Basically the Item display template you pick will have a number of properties which need to be mapped, so in the example below I have picked the Item Template “Picture on Left, 3 Lines on right”.

As a result there are 5 properties which need mapping:

  • Picture URL (i.e. the image to be displayed)
  • Link URL (i.e. where you should go when you click on the item)
  • Line 1 – I have chosen Title
  • Line 2 – I have chosen Description
  • Line 3 – I have chosen LastModifiedTime
Property Mappings allow you to control what appears in what parts of the chosen template

The templates are generally intelligent enough to know if the property doesn’t have any values, or if you haven’t actually mapped it to anything.

So this is yet another level of customisation you can apply, and the drop-down menu on each mapping allows you to cherry pick from the properties which have been indexed and mapped in the current search service.

The really great thing here is that the mappings will change depending on the template (and when you get to building your own, you can specify your own mappings). This is where the Diagnostic item template really comes into its own, as it allows you to pull in 9 fields of your choice and it displays detailed information from the results, showing you what the value is and what the mapping is for each item.

Well that is all for now so hope you realise like I do how powerful the Content by Search Web Part can truly be.

Next in the Series : Custom Display Templates with JavaScript

  • Martin Hatch


    I have also noticed the paging arrows tend to move around when you are paging. This is almost certainly a CSS bug so should be pretty easy to fix.

    I've also noticed that the Display Templates tend to switch around while you are in edit mode (and don't always match the final layout). I think this is due to mainly JavaScript caching, so always make sure you Save a draft to check it out before publishing any pages with these web parts!

    And yes, part two is on the way soon 😉

  • Kjetil

    Ive just started playing with this web part and Im experiencing some problems with it showing pictures when Im editing the web part, but as soon as i go to normal page view the images are gone. This happens when I choose list with paging, and certain "item display templates".

    Also I have a question to you guys. Is it normal for the arrows in the "list with paging" view to move from one side to the other when going to new page in this view.

    This was a good post. Waiting for part two. Is it on its way? =)

  • hurna

    The title issue sounds like the same issue we were experiencing in 2010 where search was displaying the first visible text instead of the document title. This was only occurring with Word files. See the forum post below for a windows registry change that worked in 2010 to force the entered title to be displayed:

    I love how so many of the "features" of Microsoft products sure look like bugs to the rest of us.

  • Colin

    A further update. Your advice has got me further so thanks for that. I created a completely new managed property and mapped it to OWS_MODIFIED and that worked. Now the strange part. I changed the builtin LASTMODIFIEDTIME to just OWS_MODIFIED and it doesn't work. It looks like the built in ones are the ones that try to be clever and do additional things. I suspect that is what he was refering to when he said it can't be done – that is you can't change builtin values in a way that is predictable.

    Anyway, thanks again for your suggestion.

    Best wishes…..

  • Colin

    Hi Martin, Thanks for the info. I did initially think that was the case but after completely failing to get it working I posted on another blog and had various replies. One of them (from someone who would certainly know about this) said:

    Metadata Extraction is part of SharePoint 2013 and is intended to provide better metadata for common things like title and modified date. It doesn't function off of a crawled property – it extracts the value from the document body. I don't know of any way to turn it off….

    I'll have another go but his explanation and my investigation so far shows that it can't be done. Of course it is always possible that my investigation was wrong and when I asked the question in the first place I got the explanation wrong leading to a wrong answer from the other guy:-(

    Best wishes…..

  • Martin Hatch

    You can easily get around those problems by creating new managed properties which map direct to your library columns, instead of using the slightly weird OOB "mashup" properties.

  • Colin

    To continue from the porevious post: Creation date works so if you filter on docs created in the last 5 days say that will work as expected. However, if you filter on LastModifiedTime the results are very strange. It will use the file metadata sometimes but if it finds a date near the begining of the document it will use that instead. For example, if I create a document yesterday with the text "My birthday 21st April 1974" it will use that date as the LastModifiedDate. How on earth does anyone think the modified date can be 30 years before the doc was created. However, it isn't even as if it always does that. It seems to be random whether it uses text near the start of the doc or the metadata.

  • Anonymous

    It looks good but sadly there are a great many bugs. Title is an interesting one. I have a word document called say "Interesting Doc.docx", I give it a title in word options of "Interesting Doc" and when I store it in a SharePoint Library I give it a title (which SharePoint asks me for) of "Interesting Doc". When I do a full crawl and look in the CSWP it tells me that the title is "Something Stupid". THen I realise that near the beginning of the document I have that text. It seems the author of the web part tried to be clever and ignored the various places I have put the title and instead looked through the document for some text that they thought could be used for a title instead. The Content Query Web Part gets it right of course. This alone makes the CSWp almost useless. Its behaviour with LastModifiedTime is even sillier but I post separately about that.

  • Saani

    I want to display today birthday and present month birthday when i am trying today birthday it i staking year 2000 by default how to remove that and how to fetch the current month birthday please helpme!!