Skip to main content
Kinetic Community

Bundle Category Helper

Overview

Category listing with sub-categories, sort order, and display names using category attributes.

The CategoryHelper java class is a helper file to manage the use of categories and allow category attributes to be used to create subcategories, readable display names that can include special characters, and sort categories and subcategories based on integers. This allows the user to create unlimited nested categories and categories with duplicate names. 

The CategoryHelper.jspf file can be found on github.

Usage

  1. Put the CategoryHelper.jsp file into the kinetic/app/bundles/<space name>/bundle/ directory.
  2. Include the CategoryHelper.jspf in the initialization.jspf file (this line should be where other helpers are included):
    <%@include file="CategoryHelper.jspf"%>
    
  3. Instantiate the CategoryHelper in the initialization.jspf file in the "<%-- Load helper(s) --%>" section:

    request.setAttribute("CategoryHelper", new CategoryHelper());
    
  4. On pages that you need to use categorization, load all categories with ${CategoryHelper.getCategories(kapp)}. This builds the categorization object that you will use the methods on. In the examples below bundleCategories is the variable we are using to access the object:
    <c:set var="bundleCategories" value="${CategoryHelper.getCategories(kapp)}"/>

Creating Categories, Attribute Definitions, and Category Attributes

Please refer to the Kinetic Request CE user guide for information on how to create categories and attribute definitions. The main "root" (first-level) categories will need to be created at this point so that the name can be available for the sub-categories.

To use all the features in the CategoryHelper, the following attribute definitions need to be created:

  1. Display Name 
    This attribute will be used as the displayed text for the name if it is present. This allows duplicate category names and special characters in the name (only dashes are allowed in the authoring tool).
  2. Parent
    This attribute value will be the name of the parent category.
  3. Sort Order
    This value will be an integer and used to sort the category level items.

Defining Sub-categories

To create sub-categories, an attribute named "Parent" needs to be defined and then added to sub-categories with a value of the parent category name (not display name). All categories without a "Parent" attribute will be considered "root" or first-level categories. 

Display Name

The Display Name attribute allows the use of special characters or duplicate a name to be shown in the bundle while maintaining an easy to use and allowable name in the Request CE console (duplicates are not allowed). The CategoryHelper falls back to Name if "Display Name" is null or missing.

Sort Order

Default sort order is Sort Order Attribute -> Display Name -> Name. The Sort Order attribute allows the categories to be sorted per level / branch (sort order is compared against siblings). The attribute will be evaluated if an integer is entered and will default to null and put at the end /  bottom if it is null or any other type of data is used.

   

Example

The below illustration shows the above three attributes being used. 

  1. Desktop-Monitor has a parent attribute with value "Desktop"
  2. Desktop-Monitor has a display name with a value of "Monitor"
  3. Desktop-Monitor has a sort order of 1 so it is first in the list of it's level / branch.

Root Categories Example

Using the variable "bundleCategories" from the usage description above, the code below shows a loop that will list each root category name.

 <c:forEach items="${CategoryHelper.getCategories(kapp)}" var="category">
     <div>${category.getDisplayName()}</div>
 </c:forEach>

Sub-category Example

Building on the Root Categories Example above, we can list the sub-categories of a category by using getSubcategories() method.

<c:forEach items="${CategoryHelper.getCategories(kapp)}" var="category">
    <div>${category.getDisplayName()}</div>
    <ul>
        <c:forEach var="subcategory" items="${category.getSubcategories()}">
        <li>
            <strong>${subcategory.getDisplayName()}</strong>
        </li>
        </c:forEach>
    </ul>
</c:forEach>