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