Skip to main content
With the $wsCategories module, you load category data and display it in the frontend - individual categories, their subcategories, the category path (breadcrumb), and the products they contain. This page is about loading and displaying category data. Product details are described in the product reference; the setup of category navigation takes place in the admin interface (see Template).

​
Basic concept

$wsCategories is a loader module: It only provides methods for loading categories and does not itself have a “current category”. A call like $wsCategories.id therefore does not exist. Instead, you always work with a Category map, i.e. an object with the properties of a category. You obtain this map in two ways:
  • From the current page context - on a category page, the current category is available under $wsViews.current.info.category: 
    {{ var $category = $wsViews.current.info.category }}
  • From a loader method - e.g. a specific category by its ID or the subcategories of a category: 
    {{ var $category = $wsCategories.loadCategory("100-12345") }}
In both cases, you assign the map to a variable and then access its properties (e.g. $category.name). The variable name is freely chosen; on this page it is consistently called $category.

​
Module overview

Example / excerpt of $wsCategories 
{{= $wsCategories | json }}
JSON output 
{
  "loadCategory": "ƒ()",
  "loadCategoryMembershipPaths": "ƒ()",
  "loadCategoryMemberships": "ƒ()",
  "loadChildren": "ƒ()",
  "loadPath": "ƒ()",
  "loadProducts": "ƒ()"
}
Note: "ƒ()" denotes a function. Methods overview
MethodReturn typeDescription
loadCategory()mapLoads a single category by its ID.
loadChildren()arrayLoads the direct subcategories of a category.
loadPath()arrayLoads the category path (breadcrumb) from the root to the category.
loadProducts()arrayLoads the products of a category.
loadCategoryMemberships()arrayLoads all categories in which a product is contained.
loadCategoryMembershipPaths()arrayLoads the complete category paths for all categories of a product.
The properties that every loaded category provides are described under Properties of a category.

​
Template

By default, the display of categories is done via the template category.htm (in the directory tree under templates/views/category.htm). However, category data can also be used flexibly elsewhere, for example in blog posts or in the basket. To do this, the respective template must already have been created in the views directory.

​
Properties of a category

The following properties are available in every Category map, regardless of whether you obtained it from the page context or with the help of a loader method.
PropertyReturn typeDescription
idstringUnique ID of the category assigned by the shop.
namestringName of the category.
descrstringDescription of the category.
activestringVisibility status: "always" (always visible), "test" (test mode only), "never" (not visible).
hiddenboolWhether the category is hidden (e.g. not displayed in the navigation).
productsCountintNumber of products in the category.
custommapUser-defined (free) fields of the category, e.g. images or SEO texts.
timestampCreatedAtdatetimeCreation time of the category.
timestampUpdatedAtdatetimeTime of the last change.
productAssignmentTypestringType of product assignment, e.g. "manual" (manual assignment).
productRulesstringRules for automatic product assignment; empty for manual assignment.

​
name and descr

Name and description are the most common display values. More on the configuration of these fields in the category configuration. 
{{ var $category = $wsViews.current.info.category }}
Category name: {{= $category.name }}
Description: {{= $category.descr }}

​
active

Evaluate active to display only visible categories, for example in a navigation. 
{{ if $category.active == "always" }}
  <!-- Category is visible -->
{{ /if }}

​
hidden

hidden specifically hides a category from the navigation without deactivating it. Check it before generating a navigation entry. 
{{ if !$category.hidden }}
  <li>{{= $category.name }}</li>
{{ /if }}

​
custom

custom contains the free fields of the category. Unlike with the product, the category image is located under custom.image.category (with the WebP variant custom.image.categoryWebp); a separate navigation image is located under custom.imageNavigation.category. Before output, check whether the desired field is present. 
{{ if $category.custom.image.category }}
  <img src="{{= $category.custom.image.category }}" alt="{{= $category.name }}">
{{ /if }}
In addition to the images, custom also contains, among other things, SEO fields (metaTitle, metaDescription, seoName) and control fields (robotsNoIndex, robotsNoFollow, alternativeTemplate).

​
timestampCreatedAt and timestampUpdatedAt

Both return a timestamp as an ISO-8601 string (UTC, e.g. 2026-05-07T13:09:08.000Z). 
Updated: {{= $category.timestampUpdatedAt }}

​
Methods

​
$wsCategories.loadCategory()

Loads a single category by its ID. Use this method to display a specific category in a targeted way - even outside a category page, for example on the home page or in a blog post. Signature
$wsCategories.loadCategory(categoryId) Return value
map – Category map with all category properties. Parameters
NameTypeRequiredDescription
categoryIdstringyesID of the category to load.
{{ var $category = $wsCategories.loadCategory("100-12345") }}
{{= $category.name }}

​
$wsCategories.loadChildren()

Loads the direct subcategories of a category. Use this method to build a multi-level navigation. Signature
$wsCategories.loadChildren(parentId) Return value
array – List of Category maps. Parameters
NameTypeRequiredDescription
parentIdstringnoID of the parent category.
{{ foreach $child in $wsCategories.loadChildren("100-12345") }}
  {{= $child.name }}
{{ /foreach }}
Without specifying a parentId, the categories of the top level are returned. This is useful for building the main navigation without having to know a root ID.

​
$wsCategories.loadPath()

Loads the category path (breadcrumb) from the root to the specified category. Use this method for a breadcrumb navigation that shows the customer where they are. Signature
$wsCategories.loadPath(categoryId) Return value
array – List of Category maps, from top (root) to bottom (target category). Parameters
NameTypeRequiredDescription
categoryIdstringyesID of the target category.
{{ foreach $step in $wsCategories.loadPath($category.id) }}
  <a href="{{= $wsViews.url('Category', {id: $step.id}) }}">{{= $step.name }}</a> /
{{ /foreach }}

​
$wsCategories.loadProducts()

Loads the products contained in a category. Use this method to build a product list outside a category page (on the category page itself, the products are already available under $wsViews.current.info.products). Signature
$wsCategories.loadProducts(categoryId) Return value
array – List of product maps. Parameters
NameTypeRequiredDescription
categoryIdstringyesID of the category whose products are to be loaded.
{{ var $products = $wsCategories.loadProducts("100-12345") }}
{{ foreach $product in $products }}
  {{= $product.name }}
{{ /foreach }}

​
$wsCategories.loadCategoryMemberships()

Loads all categories in which a specific product is contained. Useful for displaying on a product page which categories the product is assigned to. Signature
$wsCategories.loadCategoryMemberships(productId) Return value
array – List of Category maps. Parameters
NameTypeRequiredDescription
productIdstringyesID of the product whose categories are to be searched.
{{ foreach $category in $wsCategories.loadCategoryMemberships($product.id) }}
  <span>{{= $category.name }}</span>
{{ /foreach }}

​
$wsCategories.loadCategoryMembershipPaths()

Loads the complete category paths (breadcrumbs) for all categories in which a product is contained. Unlike loadCategoryMemberships(), you receive not only the target categories, but the complete path for each. Useful for displaying the full classification of a product. Signature
$wsCategories.loadCategoryMembershipPaths(productId) Return value
array – List of paths; each path is itself a list of Category maps. Parameters
NameTypeRequiredDescription
productIdstringyesID of the product whose category paths are to be searched.
{{ foreach $path in $wsCategories.loadCategoryMembershipPaths($product.id) }}
  {{ foreach $step in $path }}
    {{= $step.name }} >
  {{ /foreach }}
{{ /foreach }}

​
Actions

No actions are available for $wsCategories.

​
Examples

The examples assume that the category to be displayed has previously been assigned to a variable, for example on a category page like this: 
{{ var $category = $wsViews.current.info.category }}

​
Display name and description

Category name: {{= $category.name }}
Category description: {{= $category.descr }}
Result
The name and description of the current category are output.

​
Display category image

First check whether an image is present so that you do not generate an empty img tag. 
{{ if $category.custom.image.category }}
  <img src="{{= $category.custom.image.category }}" alt="{{= $category.name }}">
{{ /if }}
Result
If an overview image is stored, it is displayed with the category name as the alternative text.

​
Display subcategories

{{ foreach $child in $wsCategories.loadChildren($category.id) }}
  <p>{{= $child.name }} – {{= $child.descr }}</p>
{{ /foreach }}
Result
All direct subcategories of the current category are listed.

​
Display products of the current category

On a category page, the products of the category are already available in the page context. 
{{ foreach $product in $wsViews.current.info.products }}
  Product name: {{= $product.name }}
{{ /foreach }}
Result
The products of the current category are output. 
{{ foreach $step in $wsCategories.loadPath($category.id) }}
  <a href="{{= $wsViews.url('Category', {id: $step.id}) }}">{{= $step.name }}</a> /
{{ /foreach }}
Result
The path from the top category down to the current one is output as a sequence of linked names.

​
Load a category on any page

With loadCategory(), you can also access category data outside a category page, for example on the home page, in a blog post, or in the basket. 
{{ var $category = $wsCategories.loadCategory("101-12345") }}
Category name: {{= $category.name }}
Category description: {{= $category.descr }}
Result
The specified category is loaded and its data is output.
The IDs used in the examples (100-12345, 101-12345) are placeholders and must be replaced with real category IDs from your shop.
  • $wsViews – via current.info.category and current.info.products provides the data of the current category page, and with url('Category', {id}) the category links.
  • Category configuration – defines the standard category fields (name, description, free fields).