Monday, 6 January 2014

Extending the SP2013/Office 365 search hover panel (e.g. adding “post to my feed” functionality)

The enhanced search experience is one of the great things about SharePoint 2013, and the “hover panel”, which shows more information about the result when you hover over it, is a key part of that. Being able to peek inside a document or presentation, or see a preview of a web page without clicking on the result makes for way more efficient searching. Just like search results themselves, the appearance and functionality of the hover panel can be easily extended with HTML, CSS and JavaScript – in this post I am providing some sample code I’ve used in conference talks, which I think highlights things in this area quite well. My sample could be used as-is or modified to provide some other customization to the hover panel.

For context, here’s a reminder of what the hover panel looks like:

Standard hover panel 2 
Actually that image shows a document preview *without* Office Web Apps being available – just a simple summary of the document is shown. Arguably the more normal experience is to have OWA (for example it is standard in Office 365), and in this case you can page through the document/presentation to see if it’s what you’re looking for:

Standard hover panel - OWA

Great. So now let’s look at tweaking the hover panel to add some custom behavior.

Customizing the hover panel – adding an “action”

[Minor diversion/story]: In September 2013, Microsoft added some new functionality to Office 365 which allows a user to “post to Yammer” from the search hover panel. The entry point is a new “action” in the bottom part of the hover panel:

O365 post to Yammer

As a coincidence, a few months earlier in April 2013 I had demo’d a very similar customization at the SharePoint Evolutions Conference in London, but in my case my code was posting to the SharePoint 2013 social feed (i.e. not Yammer). Spookily enough, I had even chosen the same word, “POST”:

Hover Panel actions - with guide - edges
Seeing the Office 365 change reminded me that I should post this code somewhere – maybe it could be useful to you if your organization uses the SharePoint newsfeed rather than Yammer, or you’re just generally looking for technical info on the hover panel.

[End of minor diversion/story]

My customization

My code modifies the hover panel for all item types (e.g. web page, Word doc, Excel doc etc.). As described above, the “POST” action is added to the actions bar. When clicked, a textbox appears *in the hover panel* to allow the user to type a message to post (to the accompany link):

Hover panel - before post to feed - large

[I’m sure the UX team at my place of work would have something (very bad!) to say about this, but really I’m just trying to show that you can do all sorts of things with the hover panel :)]

I display a new button to do the actual “Post” at this point. Once a message is typed and this button is clicked, an AJAX request is fired to the SharePoint social API, and a success or failure confirmation is displayed in the hover panel:

Hover panel - after post to feed - small
And as you’d expect, the message has now been broadcast to my followers (with a link to the original document) and is now listed in the activities section of my profile:

Message shown in social feed

Search hover panel – key info

The hover panel is broken down into three areas:

Hover Panel - with guide with edge 
All this stuff comes from HTML/JavaScript files in the Master Page Gallery of your SharePoint search site – so to be clear, let’s say you have a Search Center site at a URL of “/search” (as in Office 365), then these files can be found in that site’s Master Page Gallery. You’ll find the files under the “Display Templates/Search” folder path:

Search display templates
Firstly you’ll notice above that there is a HTML file for every JavaScript file – this is the case for any site which has the publishing feature enabled and therefore Design Manager support for display templates. Past that, there are three broad types of file:

  • “Item” display templates - for each item type, such as Item_PDF.js, Item_Word.js, Item_Person.js and so on. Customize these if you wish to tweak how that particular Result Type looks in search results
  • “Hover panel” templates – again for each item type, such as Item_PDF_HoverPanel.js and so on. Customize these to tweak the hover panel (which is what we’ll be doing in this post)
  • Files for “misc” things - like best bets, the search box control etc.

Importantly, as well as the “per item type” files there are some “common” files – these are hooks which can be used to implement customizations across all Result Types, without having to edit the files for each one. Effectively there is some pseudo-inheritance implemented in JavaScript by Microsoft, where both the “common” and “specific” templates are used provide the UI for a specific item (nice work Product Group). For the hover panel, this works in the following way:

  • Each “specific” file provides some outer HTML which may be specific to that item type, but also calls functions called:
    • ctx.RenderHeader()
    • ctx.RenderBody()
    • ctx.RenderFooter()
  • These functions are implemented in the “common” files

Effectively you could throw away the idea of calling the common functions for a specific item type if you wanted, and provide an entirely custom hover panel - usually you’ll want to keep the consistency though. The common files are:

Common display templates
It’s these files we’ll be modifying.

Code for my customization

So my sample adds some HTML/CSS, but also has some custom JavaScript code – effectively the moving parts are:

  • Some new CSS and JavaScript files, which need to be referenced on the page
  • Some changes to the HTML/JS files in the Master Page Gallery which are used for the hover panel

Here’s a run-down of the changes I make to which file:

File

Change description

Item_CommonHoverPanel_Actions.html Adds the “POST” action link which sits in the “actions” bar
Item_CommonHoverPanel_Body.html Adds the core customization – the textbox which appears for the comment to be typed into, and the button which does the actual “Post”.

Also has the JavaScript call to my custom JavaScript function which does the processing work.
COB-js-demos.js Custom JavaScript file holding my custom functions such as:
“ShowHoverPanelTextBox”
“PostToCurrentUserFeed”
etc.

I added this to the page using a CustomAction.

As you can see, I’m modifying the HTML file and allowing the JS file to be generated. In production you may want to package the JS files as a WSP and overwrite the OOTB ones (keeping a copy of the original of course). I’ll provide a link to a zip file with all files at the end, but here is the new code in each:

Item_CommonHoverPanel_Actions.html
** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **
Item_CommonHoverPanel_Body.html
** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **
COB-js-demos.js
** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

So in summary we reference the custom JS file on the page (e.g. in a ScriptLink, CustomAction or script tag in the master page) and make the changes to the hover panel files. I’m supplying all the files which make up my solution in the zip linked below, but just as a set of files - you’ll need to package  them into a WSP if that’s what you need (and choose where you want CSS/JS files to deploy to). 

Summary

The search hover panel is a key part of the SharePoint 2013/Office 365 search experience, and is designed to be customized to meet different needs. A new behavior can be implemented across all item types or just for a specific one, such as a Word document or “person” result. In this sample I have shown not only how to tweak the HTML/CSS, but also provide some custom AJAX-based functionality in the hover panel. I chose to use the SharePoint social feed, but the mechanics could be adapted to any behaviour which SharePoint exposes through REST/CSOM/other client APIs.

Download

COB.SharePoint.SearchHoverPanel-Files.zip

4 comments:

Dan said...

Hey Chris great article as always... Just wondering if your same solution could be "tweaked" to work elsewhere within the farm. Say for example a list document attachment.. Open the item and hover over the attachment link ? Or hiver over an element in a list view to preview the attachment to that list item

Chris O'Brien said...

@Dan,

Yes, that was something I always meant to look at - I'm pretty sure there's a lot of overlap between the hover panel shown in search *and* that within lists/libraries. My expectation would be that this could be implemented without too much extra effort, but I'm not sure about the specifics right now I'm afraid..

Cheers,

Chris.

Alex Wilmer said...

So.. very interesting article, but this:

Window.cob = Window.cob || {};
Window.cob.sharepoint = Window.cob.sharepoint || {};
Window.cob.sharepoint.jsdemos = Window.cob.sharepoint.jsdemos || {};
Window.cob.sharepoint.jsdemos.ui = Window.cob.sharepoint.jsdemos.ui || {};

...is a mortal sin in my opinion.

Chris O'Brien said...

@Alex,

Yes, there are probably better options for JS namespacing - and I'm no JavaScript guru. What would you recommend?

Cheers,

Chris.