Categories

Categories are a simple way to classify items under a common subject or even a simplified way to create relationships between items.

Categories can be managed under ‘Settings’ > ‘Categories’. Or they can be created on the fly within any module configured to support Categories.

When managing categories, you can type your new category name at the top and use the “Add” button to add it to the list of categories available.
Currently, category items cannot be edited once created, only removed.
To remove a category, simply click the “x” icon next to its name.

Categories vs Tags

Categories are a global classification system, as they can be applied to any supporting content module throughout the CMS - not just the module where they might have been created. As such, all Category items will display everywhere where a Category option is present. This is unlike Tags, which are only relative to the specific module where they were created and are being used. They do not become available for other content modules to use.

How to use Categories

Generally, the intended use for Categories is to display filtered content, on the front-end website, specific to a particular category. Or even to group content items into categories for clearer display or organisation of content.

You may also have other use cases where Categories may prove useful, such as cross-linking multiple items together in a type of relationship.

The simplest way to display content filtered by Category is to use the Component Manager to configure your desired module.
In the screenshot example below, we’re filtering Blog Posts by a Category called “Blog: News & Events”.

Categories - Component Manager

This generates the following module tag:

{% component type: "module", source: "Blog", layout: "Blog List Layout", filterBy: "ItemCategories", filterValue: "Blog: News & Events" %}

Create Dynamic Category Listings

Listing categorised items on a page manually, as per the above example, may not be feasible if you’re categories are many or changeable. And, in the case of a Blog, you’ll probably want to keep the Posts displaying within the main Blog layout.
Creating category links to dynamically change the listings page is straightforward and powerful.

Let’s say, on a Blog Post detail page you want to link to all other Blog Posts that also share common Categories to the current Post.

In your Blog Post Detail layout you might start by listing out all the currenty assigned Categories like so (this will be the same for any type of module):

{% for cat in this.itemcategories %}
    {{cat}},
{% endfor %}

Now, to make these dynamic links to the Blog listing page we’ll make the following adjustments. Adding the anchor element, which we'll link to your main Blog page, along with an appended URL parameter that will form our unique reference to each specific category:

{% for cat in this.itemcategories %}
<a href="/my-blog?cat={{cat | url_encode}}">
    {{cat}}
</a>,
{% endfor %}

Next, we adjust our overall listing page. So in the case of a Blog, this would be the “General Blog Layout” in the Blog module’s Layout section, under “Blog Layouts”.

Categories - General Blog Layout

Instead of simply listing the Blog’s Post’s as per the default component tag, like:

{% component type:"module", source: "Blog Post", layout:"List", filterBy:"parentid", filterValue:"{{this.id}}" %}

We want to make some conditions here so that categorised post’s can be listed if one of our dynamic category links are being used instead.

Our adjusted code might look like this:

{% if request.request_url.params.cat %}
{% assign filterValue = request.request_url.params.cat %}
{% assign filterBy = 'ItemCategories' %}
{% else %}
{% assign filterValue = this.id %}
{% assign filterBy = 'parentid' %}
{% endif %}

{% component type:"module", source: "Blog Post", layout:"List", filterBy: "{{filterBy}}", filterValue: "{{filterValue}}" %}

The above code looks for our category URL parameter, and if present, adjusts the filterBy and filterValue attributes, allowing the component to filter by the desired Catergory and output the filtered Blog Posts.
When the category URL parameter is not being used (ie: not present) the filters revert to the default values, listing all Blog Posts.



External Resources


Please let us know if you have any other contributions or know of any helpful resources you'd like to see added here.


Questions?

We are always happy to help with any questions you may have.
Send us a message at support@treepl.co and we will consult you as soon as possible.