Article lists

The objects available on each Zendesk page template are limited and can sometimes prevent you from creating the layouts that you want. The Article Lists plugin allows you to present a complete set of articles on any page using custom micro-templates.

Sections and categories can also be included to help build more advanced layouts like article trees.

Example

The default template simply presents articles in an unstyled list.

You can fully style and customize the article list both in terms of its look-and-feel and functionality by specifying a custom micro-template as a plugin option.

Usage

• Using attributes
• Via JavaScript

<div id="article-list">...</div>

<script type="text/javascript">
  ready(function() {
    var articleList = document.getElementById('article-list');
    if (!articleList) return;

    new Articles(articleList, {
      // 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="article-list">...</div>

<script type="text/javascript">
  ready(function() {
    var articleList = document.getElementById('article-list');
    if (!articleList) return;

    // Get categories, sections and articles
    Util.get(['categories', 'sections', 'articles']).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 Articles(articleList, {

        // Pass the collection to the plugin to avoid fetching it again
        collection: collection,
      
        // Specify a custom template to use
        template: 'custom-article-list',
  
        // Pass additional data to the templating function
        templateData: {
          currentSection: currentSection,
          currentCategory: currentCategory
        }
      });
    });
  });
</script>

The custom template could then render the article list with access to all categories, sections and articles as well as the current section and category objects.

The collection object containing articles (and possibly categories and sections) 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- and use kebab case instead of camel case.

The following article properties are passed to the templating function by default:

• id
• title (used for articles)
• name (used for categories and sections)
• html_url
• position
• promoted
• draft

The following section and category properties are required by the plugin to sort the collection of articles and also available within custom templates:

• section_id
• category_id

Events