Skip to content

Latest commit

 

History

History
146 lines (104 loc) · 4.98 KB

categories-fields.md

File metadata and controls

146 lines (104 loc) · 4.98 KB
Raw

Categories Fields

Categories fields allow you to relate categories to other elements.

Settings

Categories fields have the following settings:

  • Source – Which category group (or other category index source) the field should be able to relate categories from.

  • Branch Limit – The maximum number of category tree branches that can be related with the field at once. (Default is no limit.)

    For example, if you have the following category group:

    Food
├── Fruit
│   ├── Apples
│   ├── Bananas
│   └── Oranges
└── Vegetables
    ├── Brussels sprouts
    ├── Carrots
    └── Celery

    …and Branch Limit was set to 1, you would be able to relate Fruit, Vegetables, or one of their descendants, but no more than that.

  • Selection Label – The label that should be used on the field’s selection button.

Multi-Site Settings

On multi-site installs, the following settings will also be available (under “Advanced”):

  • Relate categories from a specific site? – Whether to only allow relations to categories from a specific site.

    If enabled, a new setting will appear where you can choose which site.

    If disabled, related categories will always be pulled from the current site.

  • Manage relations on a per-site basis – Whether each site should get its own set of related categories.

The Field

Categories fields list all of the currently-related categories, with a button to select new ones.

Clicking the “Add a category” button will bring up a modal window where you can find and select additional categories. You can create new categories from this modal as well, by clicking the “New category” button.

When you select a nested category, all of the ancestors leading up to that category will also automatically be related. Likewise, when you remove a category from within the main field input, any of its descendants will also be removed.

Inline Category Editing

When you double-click on a related category, a HUD will appear where you can edit the category’s title and custom fields.

Templating

Querying Elements with Categories Fields

When querying for elements that have a Categories field, you can filter the results based on the Categories field data using a query param named after your field’s handle.

Possible values include:

Value Fetches elements…
':empty:' that don’t have any related categories.
':notempty:' that have at least one related category. 
{# Fetch entries with a related category #}
{% set entries = craft.entries()
    .<FieldHandle>(':notempty:')
    .all() %}

Working with Categories Field Data

If you have an element with a Categories field in your template, you can access its related categories using your Categories field’s handle:

{% set relatedCategories = entry.<FieldHandle> %}

That will give you a category query, prepped to output all of the related categories for the given field.

To loop through all of the related categories as a flat list, call all() and then loop over the results:

{% set relatedCategories = entry.<FieldHandle>.all() %}
{% if relatedCategories|length %}
    <ul>
        {% for rel in relatedCategories %}
            <li><a href="{{ rel.url }}">{{ rel.title }}</a></li>
        {% endfor %}
    </ul>
{% endif %}

Or you can show them as a hierarchical list with the nav tag:

{% set relatedCategories = entry.<FieldHandle>.all() %}
{% if relatedCategories|length %}
    <ul>
        {% nav rel in relatedCategories %}
            <li>
                <a href="{{ rel.url }}">{{ rel.title }}</a>
                {% ifchildren %}
                    <ul>
                        {% children %}
                    </ul>
                {% endifchildren %}
            </li>
        {% endnav %}
    </ul>
{% endif %}

If you only want the first related category, call one() instead, and then make sure it returned something:

{% set rel = entry.<FieldHandle>.one() %}
{% if rel %}
    <p><a href="{{ rel.url }}">{{ rel.title }}</a></p>
{% endif %}

If you just need to check if there are any related categories (but don’t need to fetch them), you can call exists():

{% if entry.<FieldHandle>.exists() %}
    <p>There are related categories!</p>
{% endif %}

You can set parameters on the category query as well. For example, to only fetch the “leaves” (categories without any children), set the leaves param:

{% set relatedCategories = entry.<FieldHandle>
    .leaves()
    .all() %}

See Also