> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $wsCategories - Kategorien

> Kategoriedaten im Frontend laden und anzeigen: Eigenschaften, Unterkategorien, Pfade und Produkte für Navigation, Listen und Kategorieseiten.

Mit dem `$wsCategories`-Modul laden Sie Kategoriedaten und zeigen sie im Frontend an - einzelne Kategorien, ihre Unterkategorien, den Kategoriepfad (Breadcrumb) und die enthaltenen Produkte.

Auf dieser Seite geht es um das Laden und Anzeigen von Kategoriedaten. Produktdetails sind in der Produkt-Referenz beschrieben; die Einrichtung der Kategorie-Navigation erfolgt im Admin-Interface (siehe [Template](#template)).

***

## Grundkonzept

`$wsCategories` ist ein Lade-Modul: Es stellt nur Methoden zum Laden von Kategorien bereit und hat selbst keine „aktuelle Kategorie". Ein Aufruf wie `$wsCategories.id` existiert daher nicht.

Sie arbeiten stattdessen immer mit einer Category-Map, also einem Objekt mit den [Eigenschaften einer Kategorie](#eigenschaften-einer-kategorie). Diese Map erhalten Sie auf zwei Wegen:

* **Aus dem aktuellen Seitenkontext** - auf einer Kategorieseite liegt die aktuelle Kategorie unter `$wsViews.current.info.category`:
  ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
  {{ var $category = $wsViews.current.info.category }}
  ```
* **Aus einer Lade-Methode** - z. B. eine bestimmte Kategorie über ihre ID oder die Unterkategorien einer Kategorie:
  ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
  {{ var $category = $wsCategories.loadCategory("100-12345") }}
  ```

In beiden Fällen weisen Sie die Map einer Variablen zu und greifen anschließend auf deren Eigenschaften zu (z. B. `$category.name`). Der Variablenname ist frei wählbar, auf dieser Seite heißt er durchgängig `$category`.

***

## Modulübersicht

**Beispiel / Ausschnitt über** `$wsCategories`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsCategories | json }}
```

**JSON-Ausgabe**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "loadCategory": "ƒ()",
  "loadCategoryMembershipPaths": "ƒ()",
  "loadCategoryMemberships": "ƒ()",
  "loadChildren": "ƒ()",
  "loadPath": "ƒ()",
  "loadProducts": "ƒ()"
}
```

Anmerkung: `"ƒ()"` kennzeichnet eine Funktion.

**Methoden in der Übersicht**

| **Methode**                     | **Rückgabe-Typ** | **Beschreibung**                                                          |
| ------------------------------- | ---------------- | ------------------------------------------------------------------------- |
| `loadCategory()`                | map              | Lädt eine einzelne Kategorie anhand ihrer ID.                             |
| `loadChildren()`                | array            | Lädt die direkten Unterkategorien einer Kategorie.                        |
| `loadPath()`                    | array            | Lädt den Kategoriepfad (Breadcrumb) von der Wurzel bis zur Kategorie.     |
| `loadProducts()`                | array            | Lädt die Produkte einer Kategorie.                                        |
| `loadCategoryMemberships()`     | array            | Lädt alle Kategorien, in denen ein Produkt enthalten ist.                 |
| `loadCategoryMembershipPaths()` | array            | Lädt die vollständigen Kategoriepfade für alle Kategorien eines Produkts. |

Die Eigenschaften, die jede geladene Kategorie bereitstellt, sind unter [Eigenschaften einer Kategorie](#eigenschaften-einer-kategorie) beschrieben.

***

## Template

Im Standard erfolgt die Anzeige von Kategorien über das Template `category.htm` (im Verzeichnisbaum unter `templates/views/category.htm`).

Kategoriedaten lassen sich aber auch flexibel anderswo nutzen, beispielsweise in Blogbeiträgen oder im Warenkorb. Dafür muss das jeweilige Template bereits im Verzeichnis `views` angelegt worden sein.

***

## Eigenschaften einer Kategorie

Die folgenden Eigenschaften stehen in jeder Category-Map zur Verfügung, unabhängig davon, ob Sie sie aus dem Seitenkontext oder mithilfe einer Lade-Methode erhalten haben.

| **Eigenschaft**         | **Rückgabe-Typ** | **Beschreibung**                                                                                        |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| `id`                    | string           | Eindeutige, vom Shop vergebene ID der Kategorie.                                                        |
| `name`                  | string           | Name der Kategorie.                                                                                     |
| `descr`                 | string           | Beschreibung der Kategorie.                                                                             |
| `active`                | string           | Sichtbarkeitsstatus: `"always"` (immer sichtbar), `"test"` (nur Testmodus), `"never"` (nicht sichtbar). |
| `hidden`                | bool             | Ob die Kategorie versteckt ist (z. B. nicht in der Navigation angezeigt wird).                          |
| `productsCount`         | int              | Anzahl der Produkte in der Kategorie.                                                                   |
| `custom`                | map              | Benutzerdefinierte (freie) Felder der Kategorie, z. B. Bilder oder SEO-Texte.                           |
| `timestampCreatedAt`    | datetime         | Erstellungszeitpunkt der Kategorie.                                                                     |
| `timestampUpdatedAt`    | datetime         | Zeitpunkt der letzten Änderung.                                                                         |
| `productAssignmentType` | string           | Art der Produktzuordnung, z. B. `"manual"` (manuelle Zuordnung).                                        |
| `productRules`          | string           | Regeln für die automatische Produktzuordnung; leer bei manueller Zuordnung.                             |

### name und descr

Name und Beschreibung sind die häufigsten Anzeigewerte. Mehr zur Konfiguration dieser Felder [in der Kategorie-Konfiguration](/konfiguration/content-katalog-kategorien-produkte#2-content-categoryfield-standard-kategoriefelder).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $category = $wsViews.current.info.category }}
Kategoriename: {{= $category.name }}
Beschreibung: {{= $category.descr }}
```

### active

Werten Sie `active` aus, um nur sichtbare Kategorien anzuzeigen, beispielsweise in einer Navigation.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $category.active == "always" }}
  <!-- Kategorie ist sichtbar -->
{{ /if }}
```

### hidden

`hidden` blendet eine Kategorie gezielt aus der Navigation aus, ohne sie zu deaktivieren. Prüfen Sie es, bevor Sie einen Navigationseintrag erzeugen.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if !$category.hidden }}
  <li>{{= $category.name }}</li>
{{ /if }}
```

### custom

`custom` enthält die freien Felder der Kategorie. Anders als beim Produkt liegt das Kategoriebild unter `custom.image.category` (mit der WebP-Variante `custom.image.categoryWebp`); ein separates Navigationsbild liegt unter `custom.imageNavigation.category`. Prüfen Sie vor der Ausgabe, ob das gewünschte Feld vorhanden ist.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $category.custom.image.category }}
  <img src="{{= $category.custom.image.category }}" alt="{{= $category.name }}">
{{ /if }}
```

<Info>
  Neben den Bildern enthält `custom` unter anderem auch SEO-Felder (`metaTitle`, `metaDescription`, `seoName`) und Steuerungsfelder (`robotsNoIndex`, `robotsNoFollow`, `alternativeTemplate`).
</Info>

### timestampCreatedAt und timestampUpdatedAt

Beide liefern einen Zeitstempel als ISO-8601-String (UTC, z. B. `2026-05-07T13:09:08.000Z`).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Aktualisiert: {{= $category.timestampUpdatedAt }}
```

***

## Methoden

### \$wsCategories.loadCategory()

Lädt eine einzelne Kategorie anhand ihrer ID. Verwenden Sie die Methode, um gezielt eine bestimmte Kategorie anzuzeigen - auch außerhalb einer Kategorieseite, beispielsweise auf der Startseite oder in einem Blogbeitrag.

**Signatur**\
`$wsCategories.loadCategory(categoryId)`

**Rückgabe**\
`map` – Category-Map mit allen [Kategorie-Eigenschaften](#eigenschaften-einer-kategorie).

**Parameter**

| **Name**     | **Typ** | **Pflicht** | **Beschreibung**              |
| ------------ | ------- | ----------- | ----------------------------- |
| `categoryId` | string  | ja          | ID der zu ladenden Kategorie. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $category = $wsCategories.loadCategory("100-12345") }}
{{= $category.name }}
```

### \$wsCategories.loadChildren()

Lädt die direkten Unterkategorien einer Kategorie. Nutzen Sie die Methode, um eine mehrstufige Navigation aufzubauen.

**Signatur**\
`$wsCategories.loadChildren(parentId)`

**Rückgabe**\
`array` – Liste von Category-Maps.

**Parameter**

| **Name**   | **Typ** | **Pflicht** | **Beschreibung**                 |
| ---------- | ------- | ----------- | -------------------------------- |
| `parentId` | string  | nein        | ID der übergeordneten Kategorie. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $child in $wsCategories.loadChildren("100-12345") }}
  {{= $child.name }}
{{ /foreach }}
```

<Note>
  Ohne Angabe einer `parentId` werden die Kategorien der obersten Ebene zurückgegeben. Das ist nützlich, um die Hauptnavigation aufzubauen, ohne eine Wurzel-ID kennen zu müssen.
</Note>

### \$wsCategories.loadPath()

Lädt den Kategoriepfad (Breadcrumb) von der Wurzel bis zur angegebenen Kategorie. Verwenden Sie die Methode für eine Breadcrumb-Navigation, die dem Kunden zeigt, wo er sich befindet.

**Signatur**\
`$wsCategories.loadPath(categoryId)`

**Rückgabe**\
`array` – Liste von Category-Maps, von oben (Wurzel) nach unten (Zielkategorie).

**Parameter**

| **Name**     | **Typ** | **Pflicht** | **Beschreibung**      |
| ------------ | ------- | ----------- | --------------------- |
| `categoryId` | string  | ja          | ID der Zielkategorie. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $step in $wsCategories.loadPath($category.id) }}
  <a href="{{= $wsViews.url('Category', {id: $step.id}) }}">{{= $step.name }}</a> /
{{ /foreach }}
```

### \$wsCategories.loadProducts()

Lädt die Produkte, die in einer Kategorie enthalten sind. Nutzen Sie die Methode, um eine Produktliste außerhalb einer Kategorieseite aufzubauen (auf der Kategorieseite selbst liegen die Produkte bereits unter `$wsViews.current.info.products`).

**Signatur**\
`$wsCategories.loadProducts(categoryId)`

**Rückgabe**\
`array` – Liste von Produkt-Maps.

**Parameter**

| **Name**     | **Typ** | **Pflicht** | **Beschreibung**                                 |
| ------------ | ------- | ----------- | ------------------------------------------------ |
| `categoryId` | string  | ja          | ID der Kategorie, deren Produkte geladen werden. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $products = $wsCategories.loadProducts("100-12345") }}
{{ foreach $product in $products }}
  {{= $product.name }}
{{ /foreach }}
```

### \$wsCategories.loadCategoryMemberships()

Lädt alle Kategorien, in denen ein bestimmtes Produkt enthalten ist. Nützlich, um auf einer Produktseite anzuzeigen, welchen Kategorien das Produkt zugeordnet ist.

**Signatur**\
`$wsCategories.loadCategoryMemberships(productId)`

**Rückgabe**\
`array` – Liste von Category-Maps.

**Parameter**

| **Name**    | **Typ** | **Pflicht** | **Beschreibung**                                   |
| ----------- | ------- | ----------- | -------------------------------------------------- |
| `productId` | string  | ja          | ID des Produkts, dessen Kategorien gesucht werden. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $category in $wsCategories.loadCategoryMemberships($product.id) }}
  <span>{{= $category.name }}</span>
{{ /foreach }}
```

### \$wsCategories.loadCategoryMembershipPaths()

Lädt die vollständigen Kategoriepfade (Breadcrumbs) für alle Kategorien, in denen ein Produkt enthalten ist. Im Unterschied zu `loadCategoryMemberships()` erhalten Sie nicht nur die Zielkategorien, sondern jeweils den kompletten Pfad. Nützlich, um die vollständige Einordnung eines Produkts darzustellen.

**Signatur**\
`$wsCategories.loadCategoryMembershipPaths(productId)`

**Rückgabe**\
`array` – Liste von Pfaden, jeder Pfad ist selbst eine Liste von Category-Maps.

**Parameter**

| **Name**    | **Typ** | **Pflicht** | **Beschreibung**                                       |
| ----------- | ------- | ----------- | ------------------------------------------------------ |
| `productId` | string  | ja          | ID des Produkts, dessen Kategoriepfade gesucht werden. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $path in $wsCategories.loadCategoryMembershipPaths($product.id) }}
  {{ foreach $step in $path }}
    {{= $step.name }} >
  {{ /foreach }}
{{ /foreach }}
```

***

## Aktionen

Für `$wsCategories` stehen keine Aktionen zur Verfügung.

***

## Beispiele

Die Beispiele gehen davon aus, dass die anzuzeigende Kategorie zuvor einer Variablen zugewiesen wurde, beispielsweise auf einer Kategorieseite so:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $category = $wsViews.current.info.category }}
```

### Name und Beschreibung anzeigen

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Kategoriename: {{= $category.name }}
Kategoriebeschreibung: {{= $category.descr }}
```

**Ergebnis** \
Name und Beschreibung der aktuellen Kategorie werden ausgegeben.

### Kategoriebild anzeigen

Prüfen Sie zuerst, ob ein Bild vorhanden ist, damit Sie kein leeres `img`-Tag erzeugen.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $category.custom.image.category }}
  <img src="{{= $category.custom.image.category }}" alt="{{= $category.name }}">
{{ /if }}
```

**Ergebnis** \
Ist ein Übersichtsbild hinterlegt, wird es mit dem Kategorienamen als Alternativtext angezeigt.

### Unterkategorien anzeigen

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $child in $wsCategories.loadChildren($category.id) }}
  <p>{{= $child.name }} – {{= $child.descr }}</p>
{{ /foreach }}
```

**Ergebnis** \
Alle direkten Unterkategorien der aktuellen Kategorie werden aufgelistet.

### Produkte der aktuellen Kategorie anzeigen

Auf einer Kategorieseite liegen die Produkte der Kategorie bereits im Seitenkontext.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $product in $wsViews.current.info.products }}
  Produktname: {{= $product.name }}
{{ /foreach }}
```

**Ergebnis** \
Die Produkte der aktuellen Kategorie werden ausgegeben.

### Breadcrumb der aktuellen Kategorie

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $step in $wsCategories.loadPath($category.id) }}
  <a href="{{= $wsViews.url('Category', {id: $step.id}) }}">{{= $step.name }}</a> /
{{ /foreach }}
```

**Ergebnis** \
Der Pfad von der obersten Kategorie bis zur aktuellen wird als Folge verlinkter Namen ausgegeben.

### Eine Kategorie auf einer beliebigen Seite laden

Mit `loadCategory()` greifen Sie auch außerhalb einer Kategorieseite auf Kategoriedaten zu , beispielsweise auf der Startseite, in einem Blogbeitrag oder im Warenkorb.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $category = $wsCategories.loadCategory("101-12345") }}
Kategoriename: {{= $category.name }}
Kategoriebeschreibung: {{= $category.descr }}
```

**Ergebnis** \
Die angegebene Kategorie wird geladen und ihre Daten werden ausgegeben.

<Note>
  Die in den Beispielen verwendeten IDs (`100-12345`, `101-12345`) sind Platzhalter und durch echte Kategorie-IDs Ihres Shops zu ersetzen.
</Note>

***

## Weiterführende Links

* [\$wsViews](/frontend/referenz/module/wsviews) – liefert über `current.info.category` und `current.info.products` die Daten der aktuellen Kategorieseite und mit `url('Category', {id})` die Kategorie-Links.
* [Kategorie-Konfiguration](/konfiguration/content-katalog-kategorien-produkte#2-content-categoryfield-standard-kategoriefelder) – legt die Standard-Kategoriefelder (Name, Beschreibung, freie Felder) fest.

##

##