Zendesk's Help Center theme customization, part 1: How we use Zendesk features

This is the first in a series of posts on the different elements we use in creating and supporting our Help Center customizations. The goal is to provide enough information that anyone could build similar customizations on their own. These posts are a starting place; we aim to provide more code examples in the future.  

To start, let’s take a look at some of the Zendesk features we use to manage data for modular theme customizations at Zendesk.

Dynamic content

Documentation: https://developer.zendesk.com/rest_api/docs/support/dynamic_content

Dynamic content allows Support users to configure localized text values that are accessible within Guide. Support users with sufficient privileges may update dynamic content text values at any time and changes will be immediately reflected.  A simple UI value like “Browse common questions” is one such example.

Dynamic content may also be created and updated via the API for automated changes:
https://developer.zendesk.com/rest_api/docs/support/dynamic_content#update-variant

An interesting way to leverage dynamic content is to deliver encoded strings in formats like JSON or Base64, instead of just simple text.  This allows us to supply structured data to the modules. Consider values like:

{“jsonConfigKey”: “An Example Title”}

or

QW4gRXhhbXBsZSBUaXRsZQo=

( Generated with: echo "An Example Title" | base64 -i - )

Our theme strategy uses several values similar to these.  They’re stored as dynamic content and rendered as JavaScript variables or HTML contents within Guide.  Be advised that dumping a lot of information into dynamic content may slow down your user’s Help Center experience, especially if large values need to be decoded with JSON.parse() or atob().

Now let’s take a look at how we access dynamic content in Guide.

Curlybars

Documentation: https://developer.zendesk.com/apps/docs/help-center-templates/introduction

Curlybars is Guide’s server side templating language.  It allows developers to control what HTML and dynamic content is rendered to the browser using in a limited set of supported theme files such as document_head.hbs or article.hbs. It uses syntax similar to the Handlebars templating language, which is frequently used by web apps on the client side, but the two should not be confused.

Dynamic content delivery

All dynamic content items registered in the Support product are accessible within any of the supported Guide theme Curlybars templates.  We utilize the footer.hbs template to output preconfigured JavaScript objects the modules use to build the responsive UI.

Here’s an example within a <script> block:

The {{dc ‘<name>’}} blocks are substituted with the appropriate values when the template is rendered on the server side.  The result delivered to the client follows:

It’s important to be absolutely sure any dynamic content that’s intended to be used in this fashion is properly escaped when it is stored.  Additionally, only trusted users or apps should have access to dynamic content as it is a potential abuse vector.

Helpers

Documentation: https://developer.zendesk.com/apps/docs/help-center-templates/helpers

As you may have noticed in the previous code example, we rely not only on dynamic content, but also other data provided by the Curlybars helpers like t and asset. Respectively, they supply common translations and asset URL locations.  Conditional rendering using if and else blocks is also accomplished using helpers.

Placement

Theme modules don’t inherently know where they should appear and require a target HTML element to ensure they render themselves in the proper placement.  We use placeholder elements in the standard Guide templates do this.

The following code example is the entirety of our home_page.hbs file:

The div elements merely provide id attributes as targets for the modules.  Arbitrary context information may be passed using custom HTML attributes like the data-page attribute seen here.

Zendesk Help Center API

Documentation: https://developer.zendesk.com/rest_api/docs/help_center/introduction

While Curlybars offers the ability to preload a lot of useful information on pages, a theme module may need to access information that’s not available everywhere.  Using the Help Center API and the Zendesk Support API to fetch additional information on page load augments the dataset available for use.

Part 2 of this series follows: How we use open source tools.

Please post your questions in the comments section below.

Disclaimer: Zendesk provides this article for informational purposes only. Zendesk does not provide support for the content.