Sections

JavaScript

Our themes and plugins are built on top of a powerful set of JavaScript functions which you can take advantage of when writing custom code.

A typical theme contains the following JavaScript files:

├── assets/
│  ├── page-article.js
│  ├── page-request.js
│  ├── page-requests.js
│  ├── util.min.js
│  └── plugins.min.js
└── script.js

The script.js contains JavaScript that’s common to all themes and responsible for functionality like dropdown menus and social share links. The JavaScript files within the assets/ folder are described in the sections below.

Page-specific scripts

Functionality specific to the Article, Request and Requests pages are contained within the page-article.js, page-request.js and page-requests.js files, respectively.

Each is referenced on the page template itself:

<script type="text/javascript">
  document.documentElement.classList.add('article-page');
  document.documentElement.classList.add('article-' + {{article.id}});
</script>

<script type="text/javascript" defer src="{{asset 'page-article.js'}}"></script>

Utility functions

JavaScript functions required by our themes and plugins are contained within the util.min.js. A reference to it is contained within the document_head.hbs template and should not be removed.

We recommend that you review the util.js source file to learn more about the complete set of available functions used in our themes, as each is accompanied by a full comment block description outlining its purpose and parameters. The most commonly-used utility functions are described below.

ready

ready(callback)

Executes the given callback function when the page is ready.

ready(function() {
  // Do something when the page is ready
});

If ready() is called after the page is ready, the callback function will be executed immediately.

each

each(selector, callback)

Executes the given callback function once for each DOM element matched by the selector.

each('ul > li', function(el) {
  // Do something with the list item
});

closest

Util.closest(el, selector)

Returns the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.

var navLink = document.querySelector('.nav-link');
var nav = Util.closest(navLink, '.nav');

get

Util.get(objectTypes, [properties])

Returns objects from the Zendesk REST API using a cached fetch request.

Util.get(['categories', 'sections', 'articles']).then(function(collection) {
  // Do something with the collection of objects
});

The following object types are supported:

  • categories
  • sections
  • articles
  • topics
  • posts

The collection object returned in the callback function contains an array of objects for each of the object types specified. The objects are as described in Zendesk’s REST API documentation, with object properties filtered by the specified properties.

replaceWithSVG

Util.replaceWithSVG(els)

Replaces one or more images with inline SVGs. The function accepts a DOM element, NodeList or selector string as an argument.

Class names and attributes from the original element will be copied across. You can therefore add any required utility classes (e.g., .fill-current) to the original element in your template.

// Using a selector
Util.replaceWithSVG('.svg-icon');

// Using a DOM element
var img = document.getElementById('svg-image');
Util.replaceWithSVG(img);

Alternatively you can use the data-inline-svg attribute to automatically apply this method to the element.

<img src="category.svg" alt="..." data-inline-svg>

onTransitionEnd

Util.onTransitionEnd(el, callback)

Invokes a callback function when the transition effect on a given element has ended. If there is no defined transition duration on the given element the callback function will be called immediately.

var el = document.getElementById('an-element');

Util.onTransitionEnd(el, function() {
  // Do something when the transition ends
});

el.classList.add('opacity-0');

debounce

Util.debounce(function, wait, [immediate])

Creates and returns a new debounced version of the passed function which will postpone its execution until a certain number of milliseconds have elapsed since the last time it was invoked. At the end of the wait interval, the function will be called with the arguments that were most recently passed to the debounced function.

var onScroll = Util.debounce(function(e) {
  // Do something on scroll
}, 200);

window.addEventListener('scroll', onScroll);

Pass true for the immediate argument to cause debounce to trigger the function on the leading instead of the trailing edge of the wait interval. This could be used, for example, to prevent accidental double-clicks on a “submit” button from firing a second time.

template

Util.template(templateString, [settings])

Compiles a template string into a function that can be evaluated for rendering. Template strings can both interpolate values using <%= … %> as well as execute arbitrary JavaScript code with <% … %>.

renderTemplate

Util.renderTemplate(el, templateId, data)

Renders a custom template within the given element using arbitrary data. Useful for rendering complicated bits of HTML from JSON data sources.

For more information, refer to micro-templating.

Plugins

Additional JavaScript functionality can be added through our range of plugins.