$wsActions - Aktionen - WEBSALE Dokumentation

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

{{= $wsActions | json }}

JSON-Ausgabe

{
  "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 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.

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

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

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

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.

{{ if $wsActions.current and $wsActions.current.name == "Login" }}
  <!-- Login-Aktion wurde ausgeführt -->
{{ /if }}

Erfolg auswerten

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

{{ if $wsActions.current.errorsByField.zip }}
  <!-- Fehler im Feld "zip" -->
{{ /if }}

Alle Fehler auflisten

{{ 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:

{{ 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:

<a href="{{= $wsActions.url('BasketItemAdd', $wsViews.current.url(), { productId: '12345', quantity: 1 }) }}">
  In den Warenkorb
</a>

Die Funktion $wsViews.current.url() stammt aus dem Modul $wsViews und liefert die aktuelle Seite als Ziel. Dadurch bleibt der Kunde nach dem Hinzufügen auf derselben Seite.

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.

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.

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

{{ 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) – was Aktionen sind, wie sie abgesichert werden und welche Aktionsnamen mit welchen Parametern es gibt. Diese Seite zeigt nur den Zugriff über $wsActions.
$wsViews – liefert mit current.url() und viewUrl() die Zielseiten, die url() und create() als target erwarten.

​Grundkonzept

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

​Verfügbarkeit von current

​Modulübersicht

​Variablen

​$wsActions.csrfToken

​$wsActions.current

​Eigenschaften von $wsActions.current

​Eigenschaften eines Fehlers (current.errors[])

​Methoden

​$wsActions.create()

​$wsActions.url()

​Beispiele

​Produkt in den Warenkorb legen und Ergebnis auswerten

​Login-Formular mit Feldfehlern

​Weiterführende Links

Grundkonzept

CSRF-Schutz (gilt für alle Aktionen)

Verfügbarkeit von `current`

Modulübersicht

Variablen

$wsActions.csrfToken

$wsActions.current

Eigenschaften von `$wsActions.current`

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

Methoden

$wsActions.create()

$wsActions.url()

Beispiele

Produkt in den Warenkorb legen und Ergebnis auswerten

Login-Formular mit Feldfehlern

Weiterführende Links