Categories are an excellent method for sorting and grouping content on your Site in an intuitive, hierarchical way.

Categories can be useful in a number of situations:

• segmenting blogs and services

• displaying related services on a page due to those items being in the same category.

• Categories are also used in eCommerce to form product catalogues and groups.

• Building a menu of categories with items displayed underneath

Each Category can optionally have an automatic system detail Page enabled for it, which will be accessible at a URL which is based off the category's ancestor's in the hierarchy, followed by its own unique slug e.g. the following category structure:

• Shop

  • Clothing

    • Unisex

      • Hats

Would have the following URL for the Hats detail page:

/shop/clothing/unisex/hats

You can optionally apply a Category Detail Layout to all of these enabled detail Pages.

This Article shows how to filter WebApp and Module Items using their category_ids parameter.

Introduction

In this set of Articles, we'll show you the Liquid syntax needed to get the most out of Categories on the Front End.

You can use Category IDs to filter WebApp, Module or eCommerce Product Items when including a List View in the Page.

Filtering by a Single Category or Multiple Categories

You can filter by a single Category using category_ids:

{% include 'module'
   id: '3'
   layout: 'default'
   per_page: '20'
   sort_type: 'properties.name'
   sort_order: 'asc'
   category_ids: '1' 
%}

You can filter by multiple Categories using comma-separated values in the category_ids parameter:

{% include 'module'
   id: '3'
   layout: 'default'
   per_page: '20'
   sort_type: 'properties.name'
   sort_order: 'asc'
   category_ids: '1,2,3' 
%}

WebApps and Modules

This parameter works whether you're filtering WebApps or Modules!

WebApp

{% include 'webapp'
   id: '3'
   layout: 'default'
   per_page: '20'
   sort_type: 'properties.name'
   sort_order: 'asc'
   category_ids: '1,2' 
%}

Module

{% include 'mdoule'
   id: '3'
   layout: 'default'
   per_page: '20'
   sort_type: 'properties.name'
   sort_order: 'asc'
   category_ids: '1,2'
%}

eCommerce Products

{%- include 'ecommerce/products'
    layout: "my_layout"
    category_ids: '1,2'
    type: 'list' 
-%}

Nested Categories

If you filter by a Category which contains sub-Categories, the results will include all Items belonging to the Sub-Categories.

E.g. If you have a Products Category containing Merchandise and Music, filtering by the ID of the Products Category will return all Items belonging to Products, Merchandise and Music.

Introduction

In this set of Articles, we'll show you the Liquid syntax needed to get the most out of Categories on the Front End.

The following features are available in WebApp and Module Layouts only, as they require access to a particular Item's category_array field. In Module Layouts, they'll only be available in the item.liquid file.

• Using the category_array field to access the IDs of Categories that have been assigned to the current Item

• Displaying all Categories that belong to the current Item

• Displaying the first, last or nth Category which belongs to the current Item

• Check if an Item has an Nth Category assigned to it

Accessing the Category Array Field

Each WebApp or Module Item has a Category Array field stored inside the this object. For WebApps, you can access this in the Layout file. For Modules, you can access this in the item.liquid file in the Layout folder: {{this.category_array}}

This will output the IDs of Categories which are assigned to the current Item in an array e.g. if the Item is assigned to Categories with ID 1 and 2 it will look like this:

[
  "1",
  "2"
]

Displaying all Categories that belong to the current Item

To loop over all these Category IDs you can use a Liquid For Loop:

{% for category in this.category_array %}
  {{category}} <!-- outputs the ID of the Category -->
{% endfor %}

Once you have the Category ID, you can use the Categories data object to access any other Category fields, e.g. the name:

{% for category in this.category_array %}
  {{context.exports.categories.data[category]}} <!-- outputs this Category JSON Object -->
  {{context.exports.categories.data[category].name}} <!-- outputs this Category name -->
{% endfor %}

Displaying the first, last or nth Category which belongs to the current Item

Instead of using a Loop, you can access a specific index of the category_array field and use it to fetch a particular Category ID.

First in Category Array

You can use the following to only output the name of the first category assigned to the Item:{{context.exports.categories.data[this.category_array.first].name}}

Last in Category Array

You can use the following to only output the name of the last category assigned to the Item:{{context.exports.categories.data[this.category_array.last].name}}

Nth in Category Array

You can use the following to only output the name of a specifc category assigned to the Item, by its zeroed-index, where 0 is the first and 1 is the second:

<!-- Fetch second Category name -->
{% assign categoryID == this.category_array[1] %}





{{context.exports.categories.data[categoryID].name}}

</div>

Check if an Item has an Nth Category assigned to it

If you want to make sure the category item in the array you are calling exists first, then you should do the following: First category in the array:

{% if this.category_array[0] != blank %}
    {{context.exports.categories.data[this.category_array[0]].name}}
{% endif %}





</div>

Second category in the array (and so on):

{% if this.category_array[1] != blank %}
    {{context.exports.categories.data[this.category_array[1]].name}}
{% endif %}

Global List of Categories

Outputting the Categories Data Variable as JSON

The following Liquid outputs a JSON object containing the details of all Categories:

{{context.exports.categories.data}}

This object stores every category in key-value pairs where the key is the ID of the Category and the value is an object containing all other available fields.

Accessing a specific Category via ID

As the Categories data Object is a key map, you can access any specific category by accessing the object and then passing in the Category's ID in square brackets: {{context.exports.categories.data['1234']}}

Accessing a Category's Fields

Once you've accessed the value of that Category via it's ID, you can access that Category's Fields using dot notation. For example, here we'll access its name: {{context.exports.categories.data['1234']}}.name}}

Other available fields are:

• id - the ID of the Category

• name - the name of the Category

• parent - the ID of the Parent Category if there is one

• slug - the end of the URL for the Category Detail Page which is unique to this Item

• meta_title - the meta-title of the Category

• meta_desc - the meta-description of the Category

• og_title - the open graph title of the Category

• og_desc - the open graph description of the Category

• og_type - the open graph type of the Category

• twitter_type - the twitter type of the Category

• full_slug - the full (relative) URL for the Category Detail Page

Looping over all Categories on the Site

If you wish to display all the Categories on the Site, you can loop over them all. Inside the For Loop you can display any HTML or Category fields you like.

If you want to skip any Categories, you can use Liquid if statements and the continue tag to do this:

Filtering WebApps and Modules

See more here:

Category Detail Pages

Default Fields

The following tags are available within the Category Detail Layout:

You can use any of the Liquid which you can use on Pages in the Category Detail Layout:

Category Detail Pages give you additional features including Breadcrumbs, Parent Category Lists, Child Category Lists and more.

Breadcrumbs

Output breadcrumb of Categories to the current Category page using the defined layout:

Parent Category List

Output parent Categories using the defined layout:

Child Category List

Output child Categories using the defined layout:

Items in this Category

Output all items categorised to the current Category Page using the defined layout:

Note that this will only output items in this specific Category. To output all items that belong to sub-Categories, then add another parameter of show_all_sub_items: 'true'.

Output Filtered WebApp, Module and Product Items in this Category

You can use the Category ID {{this.id}} to filter WebApp, Module or Product Lists and display the Items with this Category assigned (and those belonging to Categories which are children of this Category).

Products

For example, the following code will output Products on the Category Detail Page, filtered by that Category:

WebApps

Change the ID to fetch different WebApps.

Modules

Module 3 refers to the Blog; you can change the ID to fetch different Modules.

WebApp and Module Layouts

To access the category which belongs to the item currently being outputted in a WebApp layout or a Module layout's item.liquid layout, access the category_array field in:

See more:

Step 1: Find the Parent Category

There are plus () icons against each parent and child category so it's important to determine where you want to add a new category and click the plus on the correct parent:

Step 2: Create New Category

Give it a name, it will create a slug/URL and you can also add an image if required:

Step 3: Add SEO data if required

The SEO Fields tab let's you add various data to help Search Engines index it correctly but also help Social Media sites display links correctly:

Step 4: Manage Items

On an existing category you might see items that are already assigned to it, this is a helpful way to get directly to an item in a specific category:

Step 5: Manage the Template and Layout

You might want to assign a Detail Page Template and Detail Layout to Categories if users are able to navigate through the file structure (useful for eCommerce etc):

Get Started with Categories:

Learn more about Categories: