Create a custom Handlebars template to display tabular data

Use this guide if you want to create a custom Handlebars template for the Content by Search app that is distributed as part of the INTRANET edition of the WordPress + Office 365 plugin.

Before you start

  • You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
  • In addition you have also already have successfully configured the integration capability of the plugin and the Content by (SharePoint Online) Search app is working as expected i.e. displaying search results when used on a WordPress post or page.
  • You read and understood the basics of how existing Handlebar templates can be customized.
  • You are an Administrator for your WordPress website and you can access the WPO365 plugin's wizard to generate new shortcodes for the Content by Search app.

About this example

The result of the example in this article will retrieve data from a calendar in SharePoint Online and output a basic Events table as shown below.

The objective of this article is to demonstrate how anyone can achieve a similar result for their own specific use case and data.

Please note The HTML, JavaScript and CSS in this example have not been optimized and polished!

The search query

To get the SharePoint Search Query right, start by downloading and installing the SharePoint Seach Query Tool from here. The tool will help you test your query and optionally find the (managed) properties that contain the custom data that you would like to surface like the Location and (Event) Date in this example.

For this example I would like to retrieve from a specific SharePoint Site Collection https://wpo365demo.sharepoint.com/sites/training and from that SharePoint Site Collection I'd only like results of a specific SharePoint Content Type called Event. Therefore I am using the following Query Text

Path:"https://wpo365demo.sharepoint.com/sites/training" ContentType:Event

Click Run to see the results returned by the query.

The tool also allows you to see what (managed) properties are available for this result when I click View > Managed Properties for one of the results.

From the list of managed properties it's then easy to see that you would need to select the properties EventDateOWSDATE and Location to display the event's location and date.

Important Review this article if you are new to the SharePoint Search Schema.

Create / Customize a Handlebars template

Getting the search query right is one thing. Getting the Handlebars template another. An example of the template used for this article can be downloaded from cbs.intranet.events.template.html.

The basic Working with Handlebars templates documentation explained that the app expects a template file to contain four template elements.

  • jshelpers for your own custom Handlebars (block) helpers. Please have a look at cbs.intranet.list.template.html to understand how you can implement such custom helpers. If you want to implement custom handlers you can omit this element or simply leave it empty.
  • header for the header that is rendered immediately below the search box and message bar but above the search results. Use this template element to place your custom CSS stylesheets and possibly other elements that you’d like the app to render at this location. However, there is no contextual data available for this template element.
  • item for the search result item that is rendered as an item that is part of a list of items. This template element will basically receive the result item as contextual data. Therefore you could simply use {{Title}} to render the Title of the search result item returned by Content by Search‘s SharePoint Online search query or {{jobTitle}} to render the Job Title of a user that is returned by the Employee Directory‘s Graph query.
  • footer for a banner or a text with a similar function that can be placed below the paging component. However, there is no contextual data available for this template element.

Whilst the jshelpers, header and footer basically speaks from themselves the structure of the actual item template deserves a short explanation.

<main id="item" type="x-handlebars-template">
  {{#ifCond count '==' 0}}
  <div class="pintraTr">
    <div class="pintraTh eventType">Type</div>
    <div class="pintraTh eventTitle">Event</div>
    <div class="pintraTh eventLocation">Location</div>
    <div class="pintraTh eventDate">Date</div>
  </div>
  {{/ifCond}}
  <div class="pintraTr">
    <div class="pintraTdIcon pintraTd eventType">
      <div class="pintraItemIcon">
        {{fabricIcon 'Event'}}
      </div>
    </div>
    <div class="pintraTd eventTitle">
      <a class="pintraItemLink" target="{'_blank'}" href="{{Path}}" target="_blank">{{Title}}</a>
    </div>
    <div class="pintraTd eventLocation">{{Location}}</div>
    <div class="pintraTd eventDate">{{formatDateTime EventDateOWSDATE 'l LT'}}</div>
  </div>
</main>

It is important to realize that the item template is rendered for each SharePoint Search result item. However, if you would like to add an extra row before the first item to display the column headers you can do so by testing if the current item being processed is the first. This is basically what is achieved with the #ifCond helper at the top. When count equals 0 (which will be true for the first item being displayed per page of items), it will add an extra CSS table row that is then used as a table header row. 

Important The property count is added by the Content by Search app and when you are customizing a Handlebars item template for the Content by Search app it is safe to assume that this property is added to the context of each result item.

The block that then follows the #ifCond Handlebars helper finally outputs the actually item data. The plugin almost (see below Generating the shortcode > Select properties) transparently passes the SharePoint search result item's properties as the context for the Handlebars template. This means that you can basically access all properties of the item by their corresponding (managed) property name. Obviously, the SharePoint Search Query Tool again is essential in discovering those names, especially because SharePoint often (automatically) creates (managed) properties with non-intuitive names.

Important Whenever you'd like to access an item's properties inside of an Handlebars helper you would need to understand that Handlebars creates a sub template for each template inside a helper and this sub template will have its own scope. This also means that the SharePoint Search result item is now available in the parent scope. So instead of writing

{{#ifCond count '==' 0}}
<div class="pintraTr">
  <div class="pintraTh eventTitle">{{Title}}</div>
</div>
{{/ifCond}}

you would need to write 

{{../Title}}

instead as shown below.

{{#ifCond count '==' 0}}
<div class="pintraTr">
  <div class="pintraTh eventTitle">{{../Title}}</div>
</div>
{{/ifCond}}

Upload a customized Handlebars template

Once you're happy with your customized Handlebars template, you can either upload it through FTP to your WordPress website's upload directory or simply upload the (template saved as an HTML file as a new) file to the Media Library.

Generating the shortcode

Perform the following steps to generate a shortcode.

  • Navigate to WP Admin > WPO365 > ... > Content by Search (SharePoint Online) shortcode generator.
  • If a warning is shown that the plugin cannot discover Your SharePoint home URL then enter is manually e.g. https://wpo365demo.sharepoint.com (but replace wpo365demo with your tenant's own SharePoint home prefix).
  • Select Local SharePoint Results as result source.
  • Ensure that the option to Use (Handlebars) template is checked.
  • Update the Template (URL) with the full URL for the custom template that you uploaded in the previous step e.g. http://www.your-website.com/wp-content/uploads/2020/04/cbs.intranet.events.template.html.
  • Ensure that the option to automatically start searching whenever the app is loaded is checked.
  • Update the Query template with the query you tested with the SharePoint Query Tool e.g. {searchterms} ContentType:Event Path:%22https://wpo365demo.sharepoint.com/sites/training/*%22 (please note that in this case double quotes have to be URL encoded using %22).
  • Enter the non-default properties that should be returned as part of the item e.g. Location|EventDateOWSDate (please note that properties need to be chained together with the "|" (pipe) character.

Obviously you can configure more e.g. don't show the search box, paging and add translations. However, for this example at least the previous steps are essential.

Using the shortcode

Perform the following steps to add the app plus its configuration to any WordPress page or post.

  • Click Copy shortcode to clipboard button at the end of the Content by Search (SharePoint Online) shortcode generator.
  • Create a new WordPress post or page.
  • Click to add a new (Gutenberg Shortcode) block.
  • Paste the shortcode from your clipboard e.g. by pressing Ctrl+V.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us