Working with Handlebars templates

Introduction

Starting with v9.5 the Employee Directory (Microsoft Graph),the Content by Search (SharePoint Online) and the Yammer for WordPress apps that ship with the INTRANET edition of the WPO365 plugin can be customized using Handlebars.js templates. This will provide you with the power necessary to build semantic templates effectively with no frustration.

Create your own Handlebars.js template

To instruct the Content by Search and Employee Directory apps to use Handlebars templates (instead of the previously used static placeholders for primary, secondary, tertiary and meta text) you need to check the Use (Handlebars) template option on the respective shortcode generators (see WP Admin > WPO365 > … > Content by Search (SharePoint) and WP Admin > WPO365 > … > Employee Directory (Graph)). Once checked, you’ll notice that another field Template is visible. This setting allows you to configure the location where the app should try and download the (custom) Handlebars template from. By default it is set to the absolute URL that pointis to the Handlebars template that ships with the plugin. To create your own Handlebars template, download this template and use it as a reference that you’ll be customizing rather than starting from scratch.

Please note that you’ll find the original templates also on Github Gist:

Structure your own Handlebars.js template

The app expects that the template file contains 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.

Publish your own Handlebars.js template

Once you’re happy with your own Handlebars.js template you should upload it to your WordPress server either with the help of an FTP client or simply as a new item in the Media Library.

Please note that you should not try and replace the out-of-the-box templates that ship with the plugin or you risk losing your changes when you update the plugin.

A more advanced example

A more advanced example demonstrating how to create a custom Handlebars template to display tabular data can be found as part of the new WPO365 documentation service
https://docs.wpo365.com/article/80-create-a-custom-handlebars-template-to-display-tabular-data.

Sharing is caring

If you developed a super cool template then please don’t hesitate and share it with the rest of the world: Sharing is caring. Simply place it online e.g.
https://gist.github.com/ and leave a comment at the bottom of this page. I’m sure we’ll love it as well as all of the customers world wide using the WPO365 plugin!

120+

5 Star Reviews

20K+

Installations

400K+

Downloads