Sunday, November 24, 2013

Building a News Rotator with a Content Search Web Part

Mike Marnocha, Technology Director, CMS & Web Platforms

I have presented this as a demo in SharePoint Saturday Michigan in the past. The goal of this post is to show how you can easily integrate a news or image rotator into SharePoint 2013 using the Content Search Web Part (aka CSWP). In previous posts we have shared some of the architecture of how this could be applied, and how to leverage search and build queries using the CSWP.

Here is what we are going to create:

The Setup

We will use SharePoint 2013 and build a news rotator using no server side code. We will leverage a 3rd party jQuery carousel rotator such as This will present an interesting design problem with how you implement the item and control template. Normally the control renders first followed by the item template for each item, but we need to get the items first and then generate the control.

Advantages of Content Search Web Part

Some of the advantages of the CSWP over other web parts such as Content Query Web Part are:

  1. Performance: The web part gets content from the search index instead of a query to the database. SharePoint 2013 search is built on FAST technologies and is highly optimized.
  2. Ease of Development: You can customize the web part using HTML/CSS/JS and don’t need to learn XSL.
  3. Data Selection: The CSWP has a nice wizard that allows you to select what content to display, no CAML!
  4. Scope: Since you have access to search you are not limited to a single site collection.

The Plumbing

First we want to get the source HTML/CSS/JS from since I am choosing “Flavor 1”. You can find other carousel rotators out there and the process would be similar. Here is what I am downloading:

  6. (saved as jquery-1-6-0.js)

When working with CSWP you will be customizing or creating Display Templates. Display Templates are located in the Design Package or /_catalogs/masterpage/ folder. You can map a drive or access using Windows Explorer by going to your Site Settings->Design Manager->Upload Design Files.

Once you have the masterpage folder open, let’s add a folder “spsaturday” to put our downloaded artifacts into. Then create 3 subfolders for images, script, and styles. Put the images into images, css into styles, and .js files into script folder. Also add a file in script folder called “carousel_data_helper.js”. We will use this file later.

The Content Search Web Part

First we need to upload some images to our Image library, assuming you have a publishing site, or team site with publishing features enabled. Next we edit the homepage and add a web part from the “Content Roll Up” Category.

Click “Change Query” on the web part properties. For select a query choose “Pictures (System)”, Restrict by app to “Current site”. This query should get recent pictures that you uploaded, but you can change this query to get the content you need. For example you could get news articles by a content type.

Next we want to set the Display Templates for Control to “Slideshow” and Item to “Large Picture”.

You can save the web part and publish the page. At this point we have used the out of box controls to create a decent news rotator. Next step is to create a new display template based on the Agile Carousel control. The advantage is the 3rd party controls can have more features like thumbnails, back, next, pause, touch friendly controls, or just a better layout.

The Display Template

Display templates are like master pages, you customize an html file and it converts to the artifact needed. For display templates it converts your html to a .js file. Display templates are stored in the /_catalogs/masterpage/Display Templates/Content Web Parts/ folder. One easy way to make your display templates is to copy one of the out of box templates. There are two types of templates for our purpose, a control template and an item template. The control template is usually used for the header, footer, or paging controls. The item template is the content rendered for each item in results.

Go to the Content Web Parts folder and make a copy of Control_Slideshow.html and Item_LargePicture.html and rename to Control_Slideshow_SharePointSaturday.html and Item_LargePicture_SharePointSaturday.html.

First thing you want to edit is the <title> </title> tag. This is what will display in the drop downs for the CSWP. I suggest “SharePoint Saturday Slideshow” and “SharePoint Saturday Large Picture”. Save the files and edit your CSWP to use the new display templates.

The Code

Now we have all our files in the correct place it is time to customize and inject our carousel control. First thing we want to do in the Control is to include our css and js files. The syntax for that goes in the <script> </script> tags and looks like this:

Insert this into the Control_Slideshow_SharePointSaturday.html

Now we get to the design issue. The agile carousel takes as an input a JS object of data that contains the items to display. The normal order of execution is for the control to render first and then each item is plugged in. We want to build the JS object during item control execution and then have the control run as a post-render function. To help us with this we will use the carousel_data_helper.js file to create a global variable and function to build the data used by control.

Edit carousel_data_helper.js and add the following code:

This gives us the myData object and a function to call from the item template to add to that object.

Next let’s edit the Item_LargePicture_SharePointSaturday.html and call this function in the helper.

Last step is to get the carousel code into the control. Let’s edit the Control_Slideshow_SharePointSaturday.html:

The key here is the ctx.OnPostRender.push() function. It allows us to run code after the items have been rendered. I had some server specific issues and added a small delay using setTimeout. Then I’m able to call $(“#flavor_1”).agile_carousel() passing in the myData object and specifying the additional parameters used for size and transition settings.

The Goods

Here is a link to the source files used in this demo in case you want to try it out or customize further:

Wrap Up

Hopefully you take away from this session a new trick to quickly deploy a custom news rotator to your SharePoint environment. If you would like to learn more in depth about content search and display templates I highly recommend two videos from the SharePoint 2012 conference on this topic. One of the videos shows how you can implement an infinite scrolling control for search.

Using jQuery and Display Templates to create modern Web Sites

Customizing Search Experiences in SharePoint 2013