CategoriesWebAPI, or $categories, is a Velocity ViewTool that allows you to work with categories in dotCMS templates and scripts.

The tool is automatically initialized by the Velocity framework and extracts the current user from the HTTP session; all methods are called with $categories, such as in the following three identical calls in different Velocity syntactic styles:

$categories.getCategoryByKey("category-key")
${categories.getCategoryByKey("category-key")}
$!{categories.getCategoryByKey("category-key")}

All category operations respect the user's permissions.

Viewtool Methods#

---

Each of these methods requires the $categories namespace.

Category Object Methods and Properties#

---

Category objects retrieved with the viewtool represent hierarchical category entities. The methods and properties below are used with the retrieved objects, rather than the viewtool itself.

Properties / Getters#

The properties below are aliases of getter methods; a standard dotCMS Velocity pattern is that get methods without arguments can be simplified by removing the get and lowercasing the following character. As such, inode, below, can also be expressed as getInode().

Setter Methods#

Modifying most content in the dotCMS system requires a Workflow operation. However, Velocity setter methods for categories will immediately modify the category within the dotCMS system, and subsequent get calls will reflect the last set value.

Utility Methods#

Permission-Related Methods (Permissionable Interface)#

Usage Examples#

---

Get and Display Child Categories by Key#

## Get child categories of a category with a key of "products"
#set($childCategories = $categories.getChildrenCategoriesByKey("products"))

<ul>
#foreach($category in $childCategories)
    <li>$category.categoryName</li>
#end
</ul>

Retrieve a Single Category and Display Its Properties#

## Get a specific category by key
#set($productCategory = $categories.getCategoryByKey("electronics"))

#if($productCategory)
    <h2>$productCategory.categoryName</h2>
    <p>Category Key: $productCategory.key</p>
    <p>Category Inode: $productCategory.inode</p>
    <p>Category Description: $productCategory.description</p>
    <p>Category Sort Order: $productCategory.sortOrder</p>
#end

## Alternative: examine by map
#set($categoryMap = $productCategory.map)

## Access properties from map
<ul>
    <li>Name: $categoryMap.get("categoryName")</li>
    <li>Description: $categoryMap.get("description")</li>
    <li>Key: $categoryMap.get("key")</li>
    <li>Inode: $categoryMap.get("inode")</li>
</ul>

Get Nested Categories with Depth Levels#

## Get all descendant categories with their hierarchy levels
#set($allCategories = $categories.getAllActiveChildrenCategoriesByKey("main-menu"))

#foreach($categoryMap in $allCategories)
    #set($level = $categoryMap.get("level"))
    #set($category = $categoryMap.get("category"))
    
    ## Indent based on level
    #foreach($i in [1..$level])
          
    #end
    - $category.categoryName (Level $level)<br/>
#end

For an alternate aproach to climbing category trees: You can also check for active children from an already-fetched category, using the object's methods.

#set($parentCategory = $categories.getCategoryByKey("main-menu"))

#if($parentCategory.hasActiveChildren())
    <p>This category has active subcategories</p>
    #set($children = $categories.getActiveChildrenCategories($parentCategory))
    <ul>
    #foreach($child in $children)
        <li>$child.categoryName</li>
    #end
    </ul>
#else
    <p>No active subcategories</p>
#end

Get Categories Associated with Content#

## Get all categories assigned to a specific contentlet
#set($contentCategories = $categories.getInodeCategories($contentlet.inode))

#if($contentCategories && $contentCategories.size() > 0)
    <div class="content-tags">
    #foreach($cat in $contentCategories)
        <span class="tag">$cat.categoryName</span>
    #end
    </div>
#end

Get Active Categories Sorted by Name#

## Get active child categories sorted alphabetically
#set($sortedCategories = $categories.getActiveChildrenCategoriesOrderByName("parent-category-inode"))

<select name="category">
    <option value="">Select a category...</option>
    #foreach($category in $sortedCategories)
        <option value="$category.inode">$category.categoryName</option>
    #end
</select>

Get Immediate Child-Category Keys#

## Get all immediate child categories and extract their keys
#set($productCategories = $categories.getChildrenCategoriesByKey("products"))
#set($categoryKeys = $categories.fetchCategoriesKeys($productCategories))

## Use the keys for further processing
#foreach($key in $categoryKeys)
    Category Key: $key<br/>
#end

Toolbox Mapping#

---

The following example shows how the CategoriesWebAPI Viewtool is mapped in the toolbox.xml file:

    <tool>
        <key>categories</key>
        <scope>request</scope>
        <class>com.dotcms.rendering.velocity.viewtools.CategoriesWebAPI</class>
    </tool>