Change log

module_category_list

This module component fetches data relating to Categories allocated to a specific module.

{% component type: "module_category_list", module: "<Module name/ID>" %}

Only Categories that are assigned to items within the specified module are returned. In other words, Categories with an item count of 0 won't be returned.

Parameters and Options

Parameter
Values
Required
Description
type
module_category_list

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

module
<Module name/ID>
The entity/alias name or ID that the data is to be sourced from.
parentItemId
<Parent ID>

The module group ID the data is to be sourced from.
layout
<path/to/layout>

Path to file that will contain the Liquid layout content to be parsed.

If an empty string, nothing will be rendered.
If paramater is not included, the default virtual layout will be rendered (see below).

sortBy
id
name
fullname
url
itemsCount

The name of the property to sort by. If empty or not present, alpha/numeric sorting will be used based on the item's name.
sortOrder
ASC (default)
DESC

ASC sorts the items in ascending order while DESC sorts in descending order (based on alpha/numeric or date sorting).
If empty or not present, alpha/numeric sorting will be used.
limit
<number>

Maximum number of Categories to be rendered (unspecified parameter will show ALL items)
object
item
collection (default)

Determines the method for Liquid rendering.
item returns each item iteratively, one after another, for output (generally, output to a container element with no need for looping through the data).
collection returns all items as one collection for output (your container element and looping logic would be handled in the Components Layout).
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 associated with the Blog module. The Liquid data output from this example would look like the following (for example, when using a collectionVariable to create the collection):

{
  "items": [
  {
    "id": 1,
    "name": "Blog: News & Events",
    "fullname": "Blog: News & Events",
    "url": "?prop_ModuleId=1534&prop_ItemCategories=Blog%3A%20News%20%26%20Events",
    "itemsCount": 2
  },
  {
    "id": 6,
    "name": "G1 Sub Cat I",
    "fullname": "Group 1/G1 Sub Cat I",
    "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%201%2FG1%20Sub%20Cat%20I",
    "itemsCount": 2
  },
  {
    "id": 2,
    "name": "Blog: Special Deals",
    "fullname": "Blog: Special Deals",
    "url": "?prop_ModuleId=1534&prop_ItemCategories=Blog%3A%20Special%20Deals",
    "itemsCount": 1
  },
  {
    "id": 7,
    "name": "G1 Sub Cat II",
    "fullname": "Group 1/G1 Sub Cat II",
    "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%201%2FG1%20Sub%20Cat%20II",
    "itemsCount": 1
  },
  {
    "id": 5,
    "name": "Group 2",
    "fullname": "Group 2",
    "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%202",
    "itemsCount": 1
  },
  {
    "id": 9,
    "name": "G2 Sub Cat II",
    "fullname": "Group 2/G2 Sub Cat II",
    "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%202%2FG2%20Sub%20Cat%20II",
    "itemsCount": 1
  },
  {
    "id": 3,
    "name": "Sample Category",
    "fullname": "Sample Category",
    "url": "?prop_ModuleId=1534&prop_ItemCategories=Sample%20Category",
    "itemsCount": 1
  }
],
  "Params": {
  "type": "module_category_list",
  "module": "Blog Post",
  "layout": "",
  "collectionVariable": "catCollection"
}
}

The data exposed is explained further in the table below:

Name
Description
id
System ID of the Category.
name
The name of the Category.
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')
url

A formatted URL with parameter string that can be used, along with your module component configured with the isSearchResults: "true" parameter, to display all module items using the Category.

See the 'Liquid Components' documentation for the module you are working with for more info on using the isSearchResults parameter.

The pattern used to format this URL is as follows:
[[parentItemUrl]]?prop_ModuleId=[[moduleId]]&prop_ParentId=[[parentItemId]]&prop_ItemCategories=[[categoryName (UrlEncoded) ]]

For example, using the component to reference a top level module (let's use the Blog module), ie:
{% component type:"module_category_list", module:"Blog Post" %}

The URL output would be:
?prop_ModuleId=1534&prop_ItemCategories=My%20Category

Additionally, if using the component to reference a parent group via the parentItemId parameter (let's use a specific Blog within the Blog module), ie:
{% component type:"module_category_list", module:"Blog Post", parentItemId:"1234" %}
where '1234' is the ID of your specific blog parent/group item.

The URL output would be:
/my-blog?prop_ModuleId=1534&prop_ParentId=1234&prop_ItemCategories=My%20Category

itemsCount

The number of items, within the specified module, that have this Category assigned.

Virtual Layout

Based on the above example, if not using any custom layout or collection, the default virtual layout will output as a list with name, link and item count:

Accessing the Data

This data is accessible in two main ways:

1. Using Liquid in a custom defined Layout via the this.items object and a forloop (since the default object type is a collection).

{% component type: "module_category_list", layout: "/snippets/sample-category-layout.inc", module: "Blog Post" %}

Example of a forloop in the custom layout file sample-category-layout.inc

{% for category in this.items %}
{{category.name}}<br>
{% endfor %}

2. 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: "module_category_list", collectionVariable: "catCollection", module: "Blog Post" %}

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
  • G1 Sub Cat I
  • Blog: Special Deals
  • G1 Sub Cat II
  • Group 2
  • G2 Sub Cat II
  • Sample Category

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

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


Related Articles

  • categories
    This module component fetches all Categories available for the site instance, irrespective of categories that...
  • Categories
    Categories are a simple way to classify items under a common subject or even a...

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.
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.