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 This is the name of the entity that needs to be used for the component retrieving function.
module <Custom 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 <Your Layout name>
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%253A%2520News%2520%2526%2520Events",
      "itemsCount": 2
    },
    {
      "id": 2,
      "name": "Blog: Special Deals",
      "fullname": "Blog: Special Deals",
      "url": "?prop_ModuleId=1534&prop_ItemCategories=Blog%253A%2520Special%2520Deals",
      "itemsCount": 1
    },
    {
      "id": 6,
      "name": "G1 Sub Cat I",
      "fullname": "Group 1/G1 Sub Cat I",
      "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%25201%252FG1%2520Sub%2520Cat%2520I",
      "itemsCount": 2
    },
    {
      "id": 7,
      "name": "G1 Sub Cat II",
      "fullname": "Group 1/G1 Sub Cat II",
      "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%25201%252FG1%2520Sub%2520Cat%2520II",
      "itemsCount": 1
    },
    {
      "id": 9,
      "name": "G2 Sub Cat II",
      "fullname": "Group 2/G2 Sub Cat II",
      "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%25202%252FG2%2520Sub%2520Cat%2520II",
      "itemsCount": 1
    },
    {
      "id": 5,
      "name": "Group 2",
      "fullname": "Group 2",
      "url": "?prop_ModuleId=1534&prop_ItemCategories=Group%25202",
      "itemsCount": 1
    }
  ]
}

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

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

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


Related Articles

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.