Using jQuery and jqplot in your display template to show a piechart refiner

With the display templates in SharePoint 2013 being built in html and javascript you can easily re-use exisiting javascript frameworks like jQuery.

The jquery plugin called jqplot is one of many charting plugins available. It is more or less randomly chosen and the technique shown in this post can be re-used with many other plugins available.

Using the piechart available in jqplot can make your refiner look like below:

jqplot_refiner

 

The display templates used for refiners are located in the master page gallery, in folder “Filters” in the “Display Templates” folder. For more information about display templates, have a look a Steve Peschka’s article Using Query Rules, Result Types and Display Templates for a Custom Search Sales Report in SharePoint 2013

On your enterprise search site, go to Site Settings –> Master pages and page layouts. Go to the “Display Templates” folder, then “Filters”. The easiest way to edit files is to click on the “Library” tab, then “Open with Explorer”

image

To create a new display template make a copy of “Filter_Default.html”, and renamed it to “Filter_PieChart.html”.

Prior to editing the file, you can uploaded a couple of dependencies. I’ve put jquery-1.7.2.js as well a my own script “Filter_PieChart_script.js” (attached) into the folder. You also need copy the entire jqplot folder (as a sub folder) into the Filters folder. Download jquery and jqplot from https://www.jquery.com and https://www.jqplot.com.

Now, on to editing the file.

First thing to change is the title tag. The title tag is used in the refiner configuration when chosing the refiner display template you want to use. 

 <title>Refinement Item PieChart</title>

I’m leaving all the other properties of the file. Now, on to the interesting part – how to include other scripts in a display template.

There is a number of techniques:

  • Use the $includeScript function in a <script>-tag
  • Use SharePoint Script On Demand (SP.SOD) in a <script>-tag
  • Add the scripts to the master page

I’m using a combination of the two first options. The difference between the two functions is that $includeScript loads the script asynchronously as fast a possible, but there is no guarrantee that the script is loaded. It’s suitable for small scripts like my Filter_PieChart_Script.js which is only used  to set up jqplot.

For larger scripts like jquery and jqplot the SharePoint Script On Demand functions are more suitable. With SP.SOD it is possible ensure that a script is loaded before you try to start using it. It is also possible register dependencies between the scripts to make sure scripts are loaded in the correct order.

The code snippet below is from the modified Filter_PieChart.html where a <script>-tag has been added.

  
 <body>
     <script>
  
          $includeScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Filters/Filter_PieChart_Script.js");
          SP.SOD.registerSod('jquery-1.7.2.js', this.L_Menu_BaseUrl + "/_catalogs/masterpage/Display Templates/Search/jquery-1.7.2.js"); 
          SP.SOD.registerSod('jquery.jqplot.js', this.L_Menu_BaseUrl + "/_catalogs/masterpage/Display Templates/Filters/jqplot/jquery.jqplot.js"); 
          SP.SOD.registerSod('jqplot.pierenderer.js', this.L_Menu_BaseUrl + "/_catalogs/masterpage/Display Templates/Filters/jqplot/plugins/jqplot.pieRenderer.js"); 
          SP.SOD.registerSodDep('jquery.jqplot.js', 'jquery-1.7.2.js');
          SP.SOD.registerSodDep('jqplot.pieRenderer.js','jquery.jqplot.js');
          $includeCSS(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Filters/jqplot/jquery.jqplot.css");
 </script>

The custom script Filter_PieChart_Script.js is loaded with $includeScript, in addition to jquery, jqplot and the pierenderer which are loaded in the correct order with SP.SOD.

The last function used in $includeCSS which can be used to load additional CSS.

Now, go far down in the file and find

 <div id='Container'>

This is the actual part that displays the normal refiner action links. There is lots of other code in this template. Mostly of it is used to do result site merging of common file types. PPT, PPX, PPS etc are combined into the PowerPoint type.  The same for other file types. This part is nice to, so just jump down to the Container-div tag.

Delete everything inside this tag. I’ve modified it look like this:

  var pieChartId = ctx.RefinementControl.containerId + "_pieChart";
  var pieHeight = 240 + ((listData.length-1)*20);
  
 _#-->
  
         <div id='Container'>
             _#= Srch.U.collapsibleRefinerTitle(ctx.RefinementControl.propertyName, ctx.ClientControl.get_id(), refinerCatTitle, iconClass) =#_
  
             <div id="_#= pieChartId =#_" style="height: _#= pieHeight =#_px; width: 180px;"></div>
  
         </div>
         <!--#_
  
  $addRenderContextCallback(ctx, "OnPostRender", function(){
  SP.SOD.executeFunc("jqplot.pierenderer.js", null, function() {
  SetupPieChartFilter(pieChartId, listData) 
  });
  }); 
  }
  }
 _#-->
  

I’ve added a couple of variables, pieChartId and pieHeight. The pieChartId will later be used to create a div tag, and also handed to jqplot to tell it where to draw the pieChart. The pieHeight is calculated dynamicly since the legend is under the pie chart the size will vary depending on the number if items in the refiner.

The only html added is the div-tag with the pieChartId. After the html comes the intresting part. The function $addRenderContextCallback is run after the filter is rendered. We’ll run our code inside here, since we then now that everything is rendered. The code uses the SP.SOD.executeFunc to make sure jqplot is loaded. The it calls my custom function SetupPieChartFilter which uses jqplot functions to draw a pie chart based on the listData in the refiner (script attached).

Once the html is saved SP2013 will generate a Filter_PieChart.js which will be used by the browser. Now the only thing you need to do is to configure the refiner web part to use the new display template:

  1. Edit the page
  2. Edit the Refinement webpart
  3. In the Refinement settings, click “Choose Refiners…”
  4. Select the FileType chose your new Display Template “Refinement Item PieChart”¨

image

Click OK, Apply etc, and you should be all set!

Download the display template (you still need to download jquery/jqplot)

Download the full Visual Studio solution which will deploy a SharePoint feature with the display template (jquery and jqplot are downloaded from cdn.jsdelivr.net)

WSP file