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 %}