Change log

categories

This module component fetches all Categories available for the site instance, irrespective of categories that are in use or from a particular module.

{% component type: "categories" %}

Parameters and Options

Parameter
Values
Required
Description
type
categories

This is the name of the entity that needs to be used for the component retrieving function.

parentCategory
-1 (default)
<ID>

The ID of the parent category to start retrieving subcategories from.

Leaving out this parameter, or setting the value to -1, will result in the default of all categories being retrieved.

levelsDeep
-1 (default)
<number>

The number of levels down the category hierachy to be retrieved, starting from parentCategory.

Leaving out this parameter, or setting the value to -1, will result in the default of all levels being retrieved.

collectionVariable
<yourLiquidVariableName>

Assigns the data to a Liquid collection enabling further access to the data on the Page or Template using Liquid.

Your collectionVariable value must only contain English letters, numbers or underscores. Spaces or special characters are not supported.

Liquid Output

The below example shows the system Categories available for the site. The Liquid data output from this example would look like the following (for example, when using a collectionVariable to create the collection):

{
  "items": [
  {
    "NestingLevel": 1,
    "FullName": "Blog: News & Events",
    "Id": 1,
    "Name": "Blog: News & Events"
  },
  {
    "NestingLevel": 1,
    "FullName": "Blog: Special Deals",
    "Id": 2,
    "Name": "Blog: Special Deals"
  },
  {
    "NestingLevel": 1,
    "FullName": "Sample Category",
    "Id": 3,
    "Name": "Sample Category"
  },
  {
    "NestingLevel": 1,
    "FullName": "Group 1",
    "Id": 4,
    "Name": "Group 1"
  },
  {
    "NestingLevel": 2,
    "FullName": "Group 1/G1 Sub Cat I",
    "Id": 6,
    "Name": "----G1 Sub Cat I"
  },
  {
    "NestingLevel": 3,
    "FullName": "Group 1/G1 Sub Cat I/G1 Sub Sub Cat I",
    "Id": 10,
    "Name": "--------G1 Sub Sub Cat I"
  },
  {
    "NestingLevel": 2,
    "FullName": "Group 1/G1 Sub Cat II",
    "Id": 7,
    "Name": "----G1 Sub Cat II"
  },
  {
    "NestingLevel": 1,
    "FullName": "Group 2",
    "Id": 5,
    "Name": "Group 2"
  },
  {
    "NestingLevel": 2,
    "FullName": "Group 2/G2 Sub Cat I",
    "Id": 8,
    "Name": "----G2 Sub Cat I"
  },
  {
    "NestingLevel": 2,
    "FullName": "Group 2/G2 Sub Cat II",
    "Id": 9,
    "Name": "----G2 Sub Cat II"
  }
],
  "Params": {
  "type": "categories",
  "collectionVariable": "catCollection"
}
}

The data exposed is explained further in the table below:

Name
Description
nestinglevel
A number indicating the hierarchy of the category within a nested category structure (1 being the root/top level).
fullname
The full 'path' name of the Category. When nested sub Categories are used, the parent names are included in the naming structure (eg: 'Top Level/Sub Level/Category Name')
id
System ID of the Category.
name
The name of the Category. Nested sub Categories are preceeded with 4 dashes for each level deep (----).

Virtual Layout

Based on the above example, if not using any custom layout or collection, the default virtual layout will output as <option> elements, intended for use within a <select> form input (you'll need to add the <select> wrapper yourself), eg:

<select name="sampleCatList" id="sampleCatList">
    <option value="[FullName (URL_ENCODED)]">[Name]</option>
</select>

Rendering the form element:

Suppressing the Layout

Currently, this components layout cannot be suppressed or given a new layout reference. However, you can effectively hide the virtual layout while creating a collection variable in order to create your own layout pattern. For example:

{% capture categoriesLayout %}{% component type: "categories", collectionVariable: "catCollection" %}{% endcapture %}

Then, use your collectionVariable (in this case 'catCollection') to access the component's data - as explained further below.

Accessing the Data

This data is accessible directly on the Page or Template via a Liquid Collection if collectionVariable was added to the Component.

An example using collectionVariable with value "catCollection" for the Blog module:

{% component type: "categories", collectionVariable: "catCollection" %}

Using the following forloop directly on the page:

<ul>
    {% for category in catCollection.items %}
        <li>{{category['name']}}</li>
    {% endfor %}
</ul>

Renders all the item names in a list:

  • Blog: News & Events
  • Blog: Special Deals
  • Sample Category
  • Group 1
  • ----G1 Sub Cat I
  • --------G1 Sub Sub Cat I
  • ----G1 Sub Cat II
  • Group 2
  • ----G2 Sub Cat I
  • ----G2 Sub Cat II

Accessing a specific item within the collection. In this case the third item (zero based index), which in our example would render the value Sample Category

{{catCollection.items[2]['name']}}


Related Articles

  • module_category_list
    This module component fetches data relating to Categories allocated to a specific module. {% capture...
  • Categories
    Categories are a simple way to classify items under a common subject or even a...

External Resources

There are currently no external resources available.

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.
Visit the Treepl Forum for community support and to search previously asked questions or send us a message at support@treepl.co and we will consult you as soon as possible.