Never before has it been so easy to add an unlimited number of custom notifications or alerts to your help center. With the Notifications plugin you have unprecedented control over how your notification look, where they are displayed and what content they contain.
This extension compliments the built-in notification feature available in all of our themes, which is configurable using theme settings.
Standard notification styles
The example below demonstrates the four default styles available through the extension: error, warning, success and tip.
The content of your notifications can be provided as static text, localized dynamic Content or content from articles with specific labels. Regardless of which approach is taken, the content can contain HTML elements (like links).
Dismissible notifications
You can optionally make your notifications dismissible.
Dismissed notification remain hidden for the duration of the browser session, until you close your browser.
Like all of our other extensions, you can also use custom micro-templates to make your notifications look and behave however you like.
Installation
The Notifications extension is included for free in all of our themes and can be found in the theme’s Assets folder. To begin using the extension, add a reference to it in your theme’s footer.hbs template:
<script type="text/javascript" src="{{asset 'extension-notifications.min.js'}}" defer></script>
Creating notifications
To create notifications you must either:
-
Define the notification content using the
contentoption, which can be static text or dynamic content if you need to support multiple languages; or -
Identify articles to convert into notifications using the
labelsoption, which is a comma-separated list of article labels. The extension will convert each article matching one or more of the labels you provide into a notification, using the article content as the notification content.
Use data-element="notification" on an element to create a new notification.
<div data-element="notification" data-type="success" data-content="This is the notification message"></div>
<div data-element="notification" data-type="error" data-labels="notification_error"></div>
If data attributes are used you will need to ensure that the allow unsafe HTML setting is enabled within Zendesk Guide.
The Notification extension can be initialized using JavaScript:
<div id="notification">...</div>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', () => {
new Notification(document.getElementById('notification'), {
// Options go here
});
});
</script>
User-specific notifications
Using JavaScript you can show notifications to specific subsets of users that visit your Help Center. For example, to show a success notification to users with a tag of special_user, you could use the following code:
{{#if signed_in}}
<div id="notification"></div>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', () => {
fetch('/api/v2/users/me.json')
.then(function(response) { return response.json(); })
.then(function(json) {
var user = json.user;
if (user.tags.indexOf('special_user') !== -1) {
new Notification(document.getElementById('notification'), {
content: 'This is a notification that only some users can see.',
type: 'success',
// Other options go here
});
}
});
});
</script>
{{/if}}
Any other user property could be used as a condition, like the user’s role or organization membership. To learn more about the user properties returned by the Zendesk REST API, refer to the Users endpoint documentation.
Options
Options can be passed via data attributes or JavaScript.
For data attributes, append the option name to data- and use kebab case instead of camel case.
| Name | Type | Default | Description |
|---|---|---|---|
| id | string | null | The ID of the notification (required if the notification is dismissible). |
| content | string | '' | The content to display within your notification. |
| labels | string | '' | A comma-separated list of labels used to identify articles. |
| type | string | 'error' | The type of notification to use (error, warning, success or tip). |
| dismissible | boolean | false | True if the notifications should be dismissible. |
| template | stringnull | null | The name of the template to use. |
| templateData | object | {} | Additional data to expose to the templating function. |
Custom micro-templates
Using custom micro-templates you can customize the appearance and behavior of the notifications and even present other data within them like the article title. The template itself will receive one or more notification objects. Each notification object has the following properties:
notificationswhich is an array of notification objects, each with the following properties:url(only populated if articles are used)title(only populated if articles are used)bodybody_plaintype
dismissible
<% notifications.forEach(function(notification, index) { %>
<% if (notification.type === "error") { %>
<div class="notification <%= notification.type %>"<% if (dismissible && notification.id) { %> data-notification-id="<%= notification.id %>"<%} %>>
<% if (notification.title) { %>
<h3><%= notification.title %></h3>
<% } %>
<%= notification.body %>
</div>
<% } %>
<% if (notification.type === "warning") { %>...<% } %>
<% if (notification.type === "success") { %>...<% } %>
<% if (notification.type === "tip") { %>...<% } %>
<% }) %>
Events
| Class | Properties |
|---|---|
notification:render | Fires when the notification has been rendered. |
