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

# $wsActions - Aktionen

> Frontend-Aktionen wie Login, Adresspflege oder Newsletter-Anmeldung über Links oder Formulare auslösen und Erfolgs- und Fehlerergebnisse auswerten.

Mit dem `$wsActions`-Modul können Sie Aktionen im Frontend auslösen, beispielsweise ein Produkt in den Warenkorb legen, ein Formular absenden oder einen Kunden ein- bzw. ausloggen. Anschließend werten Sie das Ergebnis (Erfolg oder Fehler) aus.

Auf dieser Seite geht es um das Auslösen und Auswerten von Aktionen über das `$wsActions`-Modul. Welche Aktionen es gibt und welche Parameter eine einzelne Aktion (z. B. `BasketItemAdd` oder `Login`) erwartet, ist in der [Aktionen-Referenz](/frontend/referenz/aktionen) beschrieben. Dort finden Sie die fachliche Bedeutung der einzelnen Aktionsnamen.

***

## Grundkonzept

Eine Aktion durchläuft immer dieselben Schritte: Aktion vorbereiten → einbinden → auslösen → Ergebnis lesen → reagieren.

Sie bereiten die Aktion im Template vor, entweder als Link mit der Funktion `url()` oder als Formularobjekt mit der Funktion `create()`. Der Kunde löst die Aktion dann durch Klicken oder Absenden aus. Der Shop führt sie aus und baut die Zielseite neu auf. Auf dieser neuen Seite finden Sie das Ergebnis unter `$wsActions.current` und können entsprechend reagieren, beispielsweise mit einer Erfolgsmeldung oder der Anzeige von Fehlern.

**Wege, eine Aktion auszulösen**\
Für einen einfachen Klick, beispielsweise auf den Button „In den Warenkorb“, erzeugen Sie mit der Funktion `url()` einen Link. Wenn der Kunde etwas eingeben soll (z. B. ein Login mit Benutzername und Passwort), erzeugen Sie mit `create()` ein Aktions-Objekt und betten es in ein Formular ein. Der Unterschied liegt also darin, ob der Kunde noch Daten eingibt oder nicht.

**Zeitpunkt der Ausführung:** Der Template-Code läuft beim Seitenaufbau. `$wsActions.current` enthält daher das Ergebnis der Aktion, die in der Anfrage ausgeführt wurde, mit der diese Seite erzeugt wurde. Wurde keine Aktion ausgeführt, ist `current` `null` – prüfen Sie deshalb immer zuerst auf Vorhandensein, bevor Sie auf Ergebnisse zugreifen.

### CSRF-Schutz (gilt für alle Aktionen)

Jede Aktion muss ein gültiges [CSRF-Schutz-Token](/frontend/referenz/aktionen#3-2-aktionen-absichern) mitschicken, sonst lehnt der Shop die Anfrage ab. Das schützt davor, dass Aktionen von fremden Seiten heraus ungewollt ausgelöst werden.

Wenn Sie Aktionen über `url()` oder `create()` erzeugen, wird das Token automatisch eingebettet. Nur wenn Sie eine Anfrage von Hand zusammenbauen, müssen Sie das Token aus [`$wsActions.csrfToken`](#wsactions-csrftoken) selbst als Parameter `wscsrf` mitgeben.

### Verfügbarkeit von `current`

`$wsActions.current` ist nur gefüllt, wenn in derselben Anfrage eine Aktion ausgeführt wurde. Auf einer normal aufgerufenen Seite ist der Wert `null`. Deshalb beginnen die Ergebnisbeispiele unten mit einer Prüfung: `{{ if $wsActions.current }}`. Ohne diese Prüfung würden Sie auf null zugreifen.

***

## Modulübersicht

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

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

**JSON-Ausgabe**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "create": "ƒ()",
  "csrfToken": "...",
  "current": {
    "csrf": "...",
    "error": false,
    "errors": [
      {
        "code": "...",
        "field": "...",
        "subCode": "...",
        "text": "..."
      }
    ],
    "errorsByField": { },
    "globalErrors": [],
    "id": "...",
    "name": "...",
    "params": { },
    "success": true,
    "successInfo": { },
    "tag": "..."
  },
  "url": "ƒ()"
}
```

Anmerkung: `"ƒ()"` kennzeichnet eine Funktion (Methode). `current` ist `null`, wenn keine Aktion ausgeführt wurde.

**Variablen und Methoden in der Übersicht**

| **Name**    | **Rückgabe-Typ** | **Beschreibung**                                                                                     |
| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `csrfToken` | string           | CSRF-Schutz-Token der aktuellen Sitzung; als Parameter `wscsrf` mitzusenden.                         |
| `current`   | map              | Ergebnis der gerade ausgeführten Aktion (Erfolg, Fehler, Meldungen). `null`, wenn keine Aktion lief. |
| `create()`  | map              | Erzeugt ein Aktions-Objekt zur Verwendung in Formularen.                                             |
| `url()`     | string           | Erzeugt eine URL, die eine bestimmte Aktion ausführt (für Links).                                    |

***

## Variablen

### \$wsActions.csrfToken

Enthält das [CSRF-Schutz-Token](/frontend/referenz/aktionen#3-2-aktionen-absichern) der aktuellen Sitzung. Sie benötigen es nur, wenn Sie eine Aktionsanfrage manuell zusammenstellen. In diesem Fall muss es als Parameter „`wscsrf`“ mitgesendet werden, damit der Shop die Anfrage akzeptiert. Bei `url()` und `create()` geschieht das automatisch.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<input type="hidden" name="wscsrf" value="{{= $wsActions.csrfToken }}">
```

### \$wsActions.current

Enthält das Ergebnis der im aktuellen Aufruf ausgeführten Aktion, also Erfolg oder Fehler samt Meldungen. Der Wert ist `null`, wenn keine Aktion ausgeführt wurde.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsActions.current }}
  <!-- Eine Aktion wurde ausgeführt -->
{{ /if }}
```

#### Eigenschaften von `$wsActions.current`

| **Eigenschaft** | **Rückgabe-Typ** | **Beschreibung**                                                                                                  |
| --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `name`          | string           | Name der ausgeführten Aktion (z. B. `"BasketItemAdd"`).                                                           |
| `id`            | string           | Eindeutige ID der Aktion. Format: `<ActionName>:<ActionTag>`, falls ein Tag vergeben wurde, sonst `<ActionName>`. |
| `csrf`          | string           | CSRF-Token der ausgeführten Aktion.                                                                               |
| `tag`           | string           | Vergebenes Tag der Aktion, falls vorhanden.                                                                       |
| `params`        | map              | Bereits übergebene Parameter-Werte der Aktion.                                                                    |
| `success`       | bool             | Ob die Aktion erfolgreich war.                                                                                    |
| `successInfo`   | map              | Zusätzliche Informationen vom Shop bei Erfolg.                                                                    |
| `error`         | bool             | Ob ein Fehler aufgetreten ist.                                                                                    |
| `errors`        | list             | Liste aller aufgetretenen Fehler (Struktur siehe unten).                                                          |
| `errorsByField` | map              | Fehler, einem Feld zugeordnet (Schlüssel = Feldname).                                                             |
| `globalErrors`  | list             | Fehler, die keinem Feld zuzuordnen sind.                                                                          |

<Info>
  Das Tag (`current.tag`) wird derzeit nicht ausgewertet. Sie können es über `create()` vergeben, um mehrere gleichartige Aktionen auf einer Seite auseinanderzuhalten.
</Info>

#### Eigenschaften eines Fehlers (`current.errors[]`)

| **Eigenschaft** | **Rückgabe-Typ** | **Beschreibung**                                                      |
| --------------- | ---------------- | --------------------------------------------------------------------- |
| `code`          | string           | Fehler-Code.                                                          |
| `subCode`       | string           | Optionaler Code zur genaueren Spezifikation von `code`.               |
| `field`         | string           | Feld, bei dem der Fehler aufgetreten ist (leer bei globalen Fehlern). |
| `text`          | string           | Fehlertext aus der Konfiguration.                                     |

**Name der Aktion auswerten**

Prüfen Sie vor der Verarbeitung des Ergebnisses, welche Aktion ausgeführt wurde. So reagieren Sie nicht versehentlich auf eine andere Aktion.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsActions.current and $wsActions.current.name == "Login" }}
  <!-- Login-Aktion wurde ausgeführt -->
{{ /if }}
```

**Erfolg auswerten**

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsActions.current.success }}
  <!-- Aktion war erfolgreich -->
{{ /if }}
```

**Fehler je Feld anzeigen**

`errorsByField` ordnet Fehler einem Eingabefeld zu. Nutzen Sie das, um eine Fehlermeldung direkt neben dem betroffenen Feld auszugeben, statt nur eine allgemeine Meldung.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsActions.current.errorsByField.zip }}
  <!-- Fehler im Feld "zip" -->
{{ /if }}
```

**Alle Fehler auflisten**

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $error in $wsActions.current.errors }}
  {{= $error.text }}
{{ /foreach }}
```

***

## Methoden

### \$wsActions.create()

Erzeugt ein Aktions-Objekt zur Verwendung in Formularen. Verwenden Sie `create()`, wenn der Kunde vor dem Auslösen noch Daten eingibt (z. B. Login-Daten). Das Objekt liefert die Werte (u. a. `id` und `csrf`), die Sie als versteckte Formularfelder einbinden können. Das Objekt hat dieselben Eigenschaften wie `$wsActions.current`.

**Signatur**\
`$wsActions.create(actionName, paramDefaults, target, tag)`

**Rückgabe**\
`map` – das Aktions-Objekt.

**Parameter**

| **Name**        | **Typ** | **Pflicht** | **Beschreibung**                                                                                 |
| --------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `actionName`    | string  | ja          | Name der auszuführenden Aktion (z. B. `"BasketItemAdd"`).                                        |
| `paramDefaults` | map     | nein        | Vorbelegte Parameter, die beim Ausführen noch geändert werden können (z. B. eine Default-Menge). |
| `target`        | string  | nein        | Zielseite nach erfolgreicher Ausführung.                                                         |
| `tag`           | string  | nein        | Frei wählbare Bezeichnung, um mehrere Aktionen zu unterscheiden.                                 |

**Beispiel**, das eine Warenkorb-Aktion erzeugt:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $action = $wsActions.create("BasketItemAdd", { productId: "12345", quantity: 1 }) }}
ID: {{= $action.id }}
CSRF: {{= $action.csrf }}
```

### \$wsActions.url()

Erzeugt eine URL, die eine bestimmte Aktion ausführt. Verwenden Sie `url()` für einen Link, bei dem der Kunde keine weiteren Daten eingibt (z. B. „In den Warenkorb“ oder „Abmelden“).

**Signatur**\
`$wsActions.url(action, target, params)`

**Rückgabe**\
`string` – die URL, die die Aktion ausführt.

**Parameter**

| **Name** | **Typ** | **Pflicht** | **Beschreibung**                          |
| -------- | ------- | ----------- | ----------------------------------------- |
| `action` | string  | ja          | Name der auszuführenden Aktion.           |
| `target` | string  | ja          | Zielseite nach erfolgreicher Ausführung.  |
| `params` | map     | ja          | Parameter der Aktion (z. B. `productId`). |

**Beispiel**, das einen Link zum Hinzufügen in den Warenkorb erzeugt:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<a href="{{= $wsActions.url('BasketItemAdd', $wsViews.current.url(), { productId: '12345', quantity: 1 }) }}">
  In den Warenkorb
</a>
```

<Info>
  Die Funktion `$wsViews.current.url()` stammt aus dem Modul [\$wsViews](/frontend/referenz/module/wsviews) und liefert die aktuelle Seite als Ziel. Dadurch bleibt der Kunde nach dem Hinzufügen auf derselben Seite.
</Info>

***

## Beispiele

### Produkt in den Warenkorb legen und Ergebnis auswerten

Dieses Beispiel zeigt den vollständigen Ablauf: Der Link löst die Aktion aus, nach dem Klick wird die Seite neu aufgebaut, und `current` wird ausgewertet.

<Note>
  `productId` ist ein Platzhalter und muss durch die ID eines existierenden Produkts ersetzt werden. Eine nicht existierende Produkt-ID führt nicht zu einem auswertbaren `current.error`, sondern kann die Anfrage serverseitig scheitern lassen.
</Note>

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<!-- 1. Auslöser: Link, der die Aktion ausführt -->
<a href="{{= $wsActions.url('BasketItemAdd', $wsViews.current.url(), { productId: '12345', quantity: 1 }) }}">
  In den Warenkorb
</a>

<!-- 2. Nach dem Klick: Ergebnis derselben Aktion auswerten -->
{{ if $wsActions.current and $wsActions.current.name == "BasketItemAdd" }}
  {{ if $wsActions.current.success }}
    Produkt wurde in den Warenkorb gelegt.
  {{ else }}
    {{ foreach $error in $wsActions.current.errors }}
      {{= $error.text }}
    {{ /foreach }}
  {{ /if }}
{{ /if }}
```

**Ergebnis** \
Der Kunde bleibt nach dem Klick auf der Seite und sieht entweder eine Bestätigung oder die konkreten Fehlermeldungen der Aktion.

### Login-Formular mit Feldfehlern

Hier gibt der Kunde Daten ein, daher wird die Aktion mit `create()` vorbereitet und in ein Formular eingebettet. Nach dem Absenden werden Fehler direkt am betroffenen Feld angezeigt.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $login = $wsActions.create("Login", { }, $wsViews.current.url()) }}

<form method="post" action="{{= $wsViews.current.url() }}">
  <input type="hidden" name="wsact" value="{{= $login.id }}">
  <input type="hidden" name="wscsrf" value="{{= $login.csrf }}">
  <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">

  <input type="text" name="username">
  {{ if $wsActions.current.errorsByField.username }}
    <span class="fehler">{{= $wsActions.current.errorsByField.username }}</span>
  {{ /if }}

  <input type="password" name="password">
  <button type="submit">Anmelden</button>
</form>
```

**Ergebnis** \
Stimmen die Daten nicht, erscheint die Fehlermeldung direkt unter dem betroffenen Feld.

***

## Weiterführende Links

* [Aktionen (Konzept und Referenz)](/frontend/referenz/aktionen) – was Aktionen sind, wie sie abgesichert werden und welche Aktionsnamen mit welchen Parametern es gibt. Diese Seite zeigt nur den Zugriff über `$wsActions`.
* [\$wsViews](/frontend/referenz/module/wsviews) – liefert mit `current.url()` und `viewUrl()` die Zielseiten, die `url()` und `create()` als `target` erwarten.