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

# $wsStore - Datenspeicherung

> Modul $wsStore als Key-Value-Speicher im Frontend: beliebige Daten unter frei wählbaren Schlüsseln ablegen, auslesen und gezielt löschen.

Das `$wsStore`-Modul ist ein Key-Value-Store (Schlüssel-Wert-Speicher) für das Frontend. Darüber lassen sich beliebige Daten unter einem frei wählbaren Schlüssel ablegen, später wieder auslesen oder gezielt löschen.

Es ist das passende Werkzeug überall dort, wo Informationen benötigt werden, die das Shopsystem im Standard nicht vorhält.

***

## Modulübersicht

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

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

**JSON-Ausgabe**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "set": "ƒ()",
  "get": "ƒ()",
  "delete": "ƒ()",
  "increment": "ƒ()"
}
```

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

**Methoden in der Übersicht**

| **Name**      | **Rückgabe-Typ** | **Beschreibung**                                                       |
| ------------- | ---------------- | ---------------------------------------------------------------------- |
| `set()`       | -                | Speichert einen Wert unter dem angegebenen Schlüssel.                  |
| `get()`       | any / null       | Gibt den gespeicherten Wert für den angegebenen<br />Schlüssel zurück. |
| `delete()`    | -                | Löscht den Eintrag für den angegebenen Schlüssel.                      |
| `increment()` | -                | Erhöht einen Zählerwert unter dem angegebenen Schlüssel.               |

***

## Methoden

### \$wsStore.set()

Speichert einen beliebigen Wert unter einem Schlüssel. Der Wert kann später über [<u>get()</u>](#\$wsstore-get "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%24wsStore.get()")<u> </u>wieder abgerufen werden. Optional kann eine Gültigkeitsdauer (`ttl`) in Sekunden angegeben werden, nach der der Eintrag automatisch entfernt wird. Ohne `ttl` gilt ein Standardwert von 365 Tagen.

**Signatur**\
`$wsStore.set(key, value, ttl)`

## **Rückgabe**

**Parameter**

| **Name** | **Typ** | **Pflicht** | **Beschreibung**                                                                                                                                                                                                                                     |
| -------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`    | string  | ja          | Der Schlüssel, unter dem der Wert gespeichert wird.<br />Frei wählbar.<br />Empfehlung:<br />sprechende, eindeutige Namen mit Präfix verwenden<br />(z.B. `'productViews-' + $cProduct.id`), um Kollisionen<br />mit anderen Modulen auszuschließen. |
| `value`  | any     | ja          | Der zu speichernde Wert. (Integer, String, Boolean, Objekt,<br />Array)                                                                                                                                                                              |
| `ttl`    | int     | nein        | Gültigkeitsdauer in Sekunden. Nach Ablauf wird der Eintrag <br />automatisch entfernt. Ohne Angabe gilt ein Standardwert <br />von 365 Tagen.                                                                                                        |

**Beispiel - Session-Marker setzen, damit ein Produktaufruf nur einmal pro Besucher gezählt wird**

Um auf der Produktseite die Anzeige “X mal in den letzten 24 Stunden angesehen” zu realisieren, muss verhindert werden, dass derselbe Besucher den Zähler durch mehrfaches Neuladen der Seite verfälscht. Dafür wird pro Besucher ein Marker gesetzt - solange dieser Marker existiert, wird der Produktaufruf für diesen Besucher nicht erneut gezählt.

[<u>\$</u>](/frontend/referenz/module/wssession#\$wssession-id "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3046572054/wsSession#%24wsSession.id")<u>wsSession.id</u> ist die eindeutige Session-ID des aktuellen Besuchers. Sie wird automatisch vom Shopsystem bereitgestellt und muss nicht selbst vergeben werden. `14400` Sekunden entsprechen 4 Stunden – so lange gilt der Marker.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ $wsStore.set('productViewSession-' + $cProduct.id + $wsSession.id, true, 14400) }}
```

**Ergebnis**\
Ab dem Setzen liefert `$wsStore.get('productViewSession-<ProduktID><SessionID>')` für 4 Stunden den Wert `true` zurück. Der eigentliche Zähler, der dem Besucher die Anzeige *"X mal in den letzten 24 Stunden angesehen"* ausgibt, wird über [<u>increment()</u>](#\$wsstore-increment "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%24wsStore.increment()") gepflegt. Erst nach Ablauf der 4 Stunden darf der Produktaufruf desselben Besuchers erneut in den Zähler einfließen.

***

### \$wsStore.get()

Gibt den Wert zurück, der zuvor mit [<u>set()</u>](#\$wsstore-set "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%5BhardBreak%5D%24wsStore.set()") unter dem angegebenen Schlüssel gespeichert wurde. Ist kein Eintrag vorhanden oder ist der Eintrag abgelaufen, wird `null` zurückgegeben.

**Signatur**\
`$wsStore.get(key)`

**Rückgabe**\
`any` - Der gespeicherte Wert, oder `null` , wenn kein Eintrag vorhanden ist oder der Eintrag abgelaufen ist.

**Parameter**

| **Name** | **Typ** | **Pflicht** | **Beschreibung**                                  |
| -------- | ------- | ----------- | ------------------------------------------------- |
| `key`    | string  | ja          | Der Schlüssel, dessen Wert abgerufen werden soll. |

**Beispiel - Anzeige “X mal in den letzten 24 Stunden angesehen” auf der Produktseite**

Um dem Besucher auf einer Produktdetailseite eine Anzeige wie “X mal in den letzten 24 Stunden angesehen” auszugeben, wird der zuvor mit [<u>increment()</u>](#\$wsstore-increment "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%24wsStore.increment()") hochgezählte Wert ausgelesen. Existiert noch kein Eintrag (weil das Produkt in den letzten 24 Stunden noch nicht aufgerufen wurde), liefert [get()](#\$wsstore-get) null und die Anzeige wird übersprungen.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $productViews = $wsStore.get('productViews-' + $cProduct.id) }}
{{ if $productViews }}
    {{= $productViews }} mal in den letzten 24 Stunden angesehen
{{ /if }}
```

**Ergebnis, wenn \$productViews den Wert 10 enthält**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
10 mal in den letzten 24 Stunden angesehen
```

***

### \$wsStore.delete()

Löscht den Eintrag für den angegebenen Schlüssel aus dem Store. Nach dem Löschen gibt [<u>get()</u>](#\$wsstore-get "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%24wsStore.get()") für diesen Schlüssel `null` zurück.

**Signatur**\
`$wsStore.delete(key)`

## **Rückgabe**\\

**Parameter**

| **Name** | **Typ** | **Pflicht** | **Beschreibung**                                    |
| -------- | ------- | ----------- | --------------------------------------------------- |
| `key`    | string  | ja          | Der Schlüssel, dessen Eintrag gelöscht werden soll. |

***

### \$wsStore.increment()

Erhöht einen Zählerwert unter dem angegebenen Schlüssel um den angegebenen Wert. Existiert der Schlüssel noch nicht, wird er mit dem Wert von `amount` angelegt.

Diese Methode sollte bevorzugt gegenüber einer Kombination aus [<u>get()</u>](#\$wsstore-get "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%24wsStore.get()") und [<u>set()</u>](#\$wsstore-set "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%5BhardBreak%5D%24wsStore.set()") verwendet werden, wenn ein Zähler erhöht werden soll.\
\
Das liegt daran, dass [<u>get()</u>](#\$wsstore-get "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%24wsStore.get()") und [<u>set()</u>](#\$wsstore-set "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%5BhardBreak%5D%24wsStore.set()") das Hochzählen in zwei Schritten durchführen - erst den aktuellen Wert lesen, dann den erhöhten Wert speichern. Rufen zwei Besucher die Seite gleichzeitig auf, lesen beide in Schritt 1 denselben Wert, beispielsweise 5. Beide speichern anschließend 6. Der Zähler steht am Ende auf 6, obwohl er auf 7 stehen müsste.

Mit `increment()` passiert das Lesen und erhöhen in einem einzigen Schritt, sodass beide Aufrufe korrekt gezählt werden.

**Signatur**\
`$wsStore.increment(key, amount, ttl)`

**Parameter**

| **Name** | **Typ** | **Pflicht** | **Beschreibung**                                                                                                                                                |
| -------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`    | string  | ja          | Der Schlüssel, dessen Zählerwert erhöht werden soll.                                                                                                            |
| `amount` | int     | nein        | Der Wert, um den der Zähler erhöht wird. <br />Standardmäßig `1`.                                                                                               |
| `ttl`    | int     | nein        | Gültigkeitsdauer in Sekunden. Nach Ablauf wird <br />der Eintrag automatisch entfernt. <br />Wird `ttl` weggelassen, gilt ein Standardwert <br />von 365 Tagen. |

**Beispiel - Produktaufrufe zählen, einmal pro Session**

Ziel ist die Anzeige “X mal in den letzten 24 Stunden angesehen” auf der Produktseite. Damit derselbe Besucher den Zähler nicht durch mehrfaches Neuladen verfälscht, wird pro Session zusätzlich ein Marker gesetzt, der verhindert, dass derselbe Besucher das Produkt mehrfach zählt.

[\$wsSession.id](/frontend/referenz/module/wssession) ist die eindeutige Session-ID des aktuellen Besuchers. Sie wird automatisch vom Shopsystem bereitgestellt und muss nicht selbst vergeben werden.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myViewKey = 'productViews-' + $cProduct.id }}
{{ var $mySessionKey = 'productViewSession-' + $cProduct.id + $wsSession.id }}

{{ if not $wsStore.get($mySessionKey) }}
    {{ $wsStore.increment($myViewKey, 1, 86400) }}
    {{ $wsStore.set($mySessionKey, true, 14400) }}
{{ /if }}
```

**Ergebnis**\
Der Zähler `productViews-<ProduktID>` wird pro Besucher höchstens einmal alle 4 Stunden erhöht. Die anschließende Anzeige mit [<u>get()</u>](#\$wsstore-get "https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3987013651/wsStore#%24wsStore.get()") zeigt dem Besucher z.B.: “7 mal in den letzten 24 Stunden angesehen”. Nach Ablauf von 24 Stunden startet der Zähler automatisch wieder bei null.