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

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",
      "Name": "Blog: News & Events",
      "Id": "1344",
      "Params": {}
    },
    {
      "NestingLevel": 1,
      "FullName": "Blog: Special Deals",
      "Name": "Blog: Special Deals",
      "Id": "1345",
      "Params": {}
    },
    {
      "NestingLevel": 1,
      "FullName": "Sample Category",
      "Name": "Sample Category",
      "Id": "1346",
      "Params": {}
    },
    {
      "NestingLevel": 1,
      "FullName": "Group 1",
      "Name": "Group 1",
      "Id": "1347",
      "Params": {}
    },
    {
      "NestingLevel": 2,
      "FullName": "Group 1/G1 Sub Cat I",
      "Name": "----G1 Sub Cat I",
      "Id": "1349",
      "Params": {}
    },
    {
      "NestingLevel": 3,
      "FullName": "Group 1/G1 Sub Cat I/G1 Sub Sub Cat I",
      "Name": "--------G1 Sub Sub Cat I",
      "Id": "1353",
      "Params": {}
    },
    {
      "NestingLevel": 2,
      "FullName": "Group 1/G1 Sub Cat II",
      "Name": "----G1 Sub Cat II",
      "Id": "1350",
      "Params": {}
    },
    {
      "NestingLevel": 1,
      "FullName": "Group 2",
      "Name": "Group 2",
      "Id": "1348",
      "Params": {}
    },
    {
      "NestingLevel": 2,
      "FullName": "Group 2/G2 Sub Cat I",
      "Name": "----G2 Sub Cat I",
      "Id": "1351",
      "Params": {}
    },
    {
      "NestingLevel": 2,
      "FullName": "Group 2/G2 Sub Cat II",
      "Name": "----G2 Sub Cat II",
      "Id": "1352",
      "Params": {}
    }
  ],
  "Params": {
    "type": "categories",
    "collectionvariable": "catCollection"
  }
}

The data exposed is explained further in the table below:

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')

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):

{% for category in this.items %}
    <option Id="{{category.id}}" value="{{category.fullname | url_encode}}">{{category.name}}</option>
{% endfor %}

An example adding your own <select> element wrapping this component:

<select name="sampleCatList" id="sampleCatList">
    {% component type: "categories" ... %}
</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

JSON Output

You can output the full JSON for your component data by referencing the root Liquid object {{this}} in your module’s layouts, or directly on your page, if using the collectionVariable parameter in your component tag.

For example:

{% component type: ... collectionVariable: "myData" %}

You can then render the JSON like so:

{{myData}}

For more details on using this approach, see Part 2 of the free ‘Learning Liquid Course’.

Rendering Property Values

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']}}

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.

Going Live

Change Log