CategoryModel
Whenever you’re dealing with a category in your template, you’re actually working with a CategoryModel object.
# Simple Output
Outputting a CategoryModel object without attaching a property or method will return the category’s title:
<h1>{{ category }}</h1>
# Properties
CategoryModel objects have the following properties:
# ancestors
Alias of getAncestors().
# children
Alias of getChildren().
# cpEditUrl
Alias of getCpEditUrl().
# dateCreated
A DateTime object of the date the category was created.
# dateUpdated
A DateTime object of the date the category was last updated.
# descendants
Alias of getDescendants().
# enabled
Whether the category is enabled.
# group
Alias of getGroup().
# hasDescendants
Whether the category has any descendants.
hasDescendants will return true even if all of the descendants are disabled. If you want to determine if the category has any enabled descendants, you can do this instead:
{% set hasDescendants = category.getDescendants().total() != 0 %}
# id
The category’s ID.
# level
The category’s level.
# link
Alias of getLink().
# locale
The locale the category was fetched in.
# next
Alias of getNext().
# nextSibling
Alias of getNextSibling().
# parent
Alias of getParent().
# prev
Alias of getPrev().
# prevSibling
Alias of getPrevSibling().
# siblings
Alias of getSiblings().
# slug
The category’s slug.
# title
The category’s title.
# uri
The category’s URI.
# url
Alias of getUrl()
# Methods
CategoryModel objects have the following methods:
# getAncestors( distance )
Returns an ElementCriteriaModel prepped to return the category’s ancestors (if it lives in a Structure section). You can limit it to only return ancestors that are up to a certain distance away by passing the distance as an argument.
# getChildren()
Returns an ElementCriteriaModel prepped to return the category’s children. (This is an alias for getDescendants(1))
# getDescendants( distance )
Returns an ElementCriteriaModel prepped to return the category’s descendants. You can limit it to only return descendants that are up to a certain distance away by passing the distance as an argument.
# getGroup()
Returns a CategoryGroupModel object representing the category’s group.
# getLink()
Returns an <a> tag, set to the category’s URL, and using the category’s title as the text.
# getNext( params )
Returns the next category that should show up in a list based on the parameters entered. This function accepts either a craft.categories variable (sans output function), or a parameter array. If you use this within a craft.categories loop, it will return the next category in that loop by default.
# getNextSibling()
Returns the category’s next sibling, if there is one.
getNextSibling() will return the next sibling whether or not it’s enabled. If you want to get the closest enabled sibling, you can do this instead:
{% set nextSibling = craft.categories.positionedAfter(category).order('lft asc').first() %}
# getParent()
Returns the category’s parent, if it’s not a top-level category.
getParent() will return the parent whether or not it’s enabled. If you want to get the closest enabled ancestor, you can do this instead:
{% set parent = craft.categories.ancestorOf(category).order('lft desc').first() %}
# getPrev( params )
Returns the previous category that would have shown up in a list based on the parameters entered. This function accepts either a craft.categories variable (sans output function), or a parameter array. If you use this within a craft.categories loop, it will return the previous category in that loop by default.
# getPrevSibling()
Returns a category’s previous sibling, if there is one.
getPrevSibling() will return the previous sibling whether or not it’s enabled. If you want to get the closest enabled sibling, you can do this instead:
{% set prevSibling = craft.categories.positionedBefore(category).order('lft desc').first() %}`
# getSiblings()
Returns an ElementCriteriaModel prepped to return the category’s siblings (if it lives in a Structure section).
# getUrl()
Returns the category’s URL, if any.
# hasDescendants()
Returns whether the category has any descendants.
# isAncestorOf( category )
Returns whether the category is an ancestor of another category.
{% nav page in craft.categories.group('whiskey') %}
{% set expanded = category is defined and item.isAncestorOf(category) %}
<li{% if expanded %} class="expanded"{% endif %}>
{{ item.getLink() }}
{% ifchildren %}
<ul>
{% children %}
</ul>
{% endifchildren %}
</li>
{% endnav %}
# isChildOf( category )
Returns whether the category is a direct child of another category.
# isDescendantOf( category )
Returns whether the category is a descendant of another category.
# isNextSiblingOf( category )
Returns whether the category is the next sibling of another category.
# isParentOf( category )
Returns whether the category is a direct parent of another category.
# isPrevSiblingOf( category )
Returns whether the category is the previous sibling of another category.
# isSiblingOf( category )
Returns whether the category is a sibling of another category.
Here’s an example of getNext() and getPrev() in action:
{% set params = {
section: 'cocktails',
order: 'title'
} %}
{% set prevWhiskey = category.getPrev(params) %}
{% set nextWhiskey = category.getNext(params) %}
{% if prevWhiskey %}
<p>Previous: <a href="{{ prevWhiskey.url }}">{{ prevWhiskey.title }}</a></p>
{% endif %}
{% if nextWhiskey %}
<p>Next: <a href="{{ nextWhiskey.url }}">{{ nexWhiskey.title }}</a></p>
{% endif %}