The objects available on each Zendesk page template are limited and can sometimes prevent you from creating the layouts that you want. The Section Lists plugin allows you to present a complete set of sections on any page using custom micro-templates.
Categories can also be included to help build more advanced layouts like lists of sections grouped by category.
Usage
Via data attributes
Use data-element="section-list"
on an element to create a list of sections. The default template simply presents sections in an unstyled list.
-
-
<div data-element="section-list"></div>
If data attributes are used, you will need to ensure that the allow unsafe HTML setting is enabled within Guide.
Via JavaScript
The Section List plugin can be initialized using JavaScript:
<div id="section-list">...</div>
<script type="text/javascript">
ready(function() {
var sectionList = document.getElementById('section-list');
if (!sectionList) {
return;
}
new Sections(sectionList, {
// Options go here
});
});
</script>
When using a custom template additional data can be passed using the templateData
option and it may be necessary to fetch and process objects from the REST API first. For example, the following code could be used on the Section page:
<div id="section-list">...</div>
<script type="text/javascript">
ready(function() {
var sectionList = document.getElementById('section-list');
if (!sectionList) {
return;
}
// Get categories, sections and articles
Util.get(['categories', 'sections']).then(function(collection) {
// Get the object representing the current section
var currentSection = collection.sections.filter(function(section) {
return section.id === {{section.id}};
})[0];
// Get the current category
var currentCategory = collection.categories.filter(function(category) {
return category.id === currentSection['html_url'];
})[0];
new Sections(sectionList, {
// Pass the collection to the plugin to avoid fetching it again
collection: collection,
// Specify a custom template to use
template: 'custom-section-list',
// Pass additional data to the templating function
templateData: {
currentSection: currentSection,
currentCategory: currentCategory
}
});
});
});
</script>
The custom template could then render the section list with access to all categories and as well as the current section and category objects.
The collection
object containing sections (and possibly categories) is sorted and organized such that parent objects have a children
property, which is an array of child objects. For example, if categories are fetched, a given category’s children
array will contain all section objects belonging to that category.
Options
Options can be passed via data attributes or JavaScript.
For data attributes, append the option name to data-
.
Name | Type | Default | Description |
---|---|---|---|
collection | object | {} | An object containing an array of objects representing sections (and possibly categories). If the collection is not provided, the plugin will fetch categories from the Zendesk REST API. |
categories | boolean | true | True if category objects should be returned with sections. |
categoryId | string number null | null | Limit sections to those in a given category. |
properties | array | See below | The list of properties from the REST API response to pass to the templating function. |
template | string null | null | The name of the template to use. |
templateData | object | {} | Additional data to expose to the templating function. |
The following article properties are passed to the templating function by default:
id
name
html_url
position
The following section and category properties are required by the plugin to sort the collection of articles and also available within custom templates:
parent_section_id
category_id
Events
Class | Properties |
---|---|
sectionList.render | Fires when the section list has been rendered. |