Mit Hilfe von Aktionen (Action-Objekten) werden Benutzerinteraktionen mit dem Shop abgebildet, wie z. B. das Legen eines Produkts in den Warenkorb.

Aktionen können von jedem Template aus ausgeführt werden. Sie werden in der Regel in Kombination mit HTML-Formularen benutzt.

Um eine Aktion auszuführen, benötigt man in einem Template ein Action-Objekt. Ein Action-Objekt wird mit Hilfe der Funktion create() des Moduls $wsActions erstellt.

In den Klammern schreiben wir den Namen der Aktionsart, in diesem Fall BasketItemAdd.

Die Liste der möglichen Aktionsarten ist von WEBSALE vorgegeben.

{{ $basketAdd = $wsAction.create("BasketItemAdd") }}

Überblick

Aktionen erlauben es dem Benutzer mit dem Shopsystem zu interagieren und die Daten seiner Session zu verändern. Wenn der Benutzer beispielsweise einen Artikel in den Warenkorb legt oder ein Kontaktformular absendet, wird dies mit Hilfe von Aktionen abgebildet.

Aktionen werden in der Regel durch HTML-Formulare oder Ajax-Anfragen ausgeführt.

Das Modul $wsActions bietet Zugriff auf das Aktionssystem des Shops.

CSRF-Prevention

Alle Aktionen in der V9 sind gegen Cross-Site-Request-Forgery (CSRF) geschützt.

Dazu wird für jede Benutzersitzung ein einmaliger CSRF-Token generiert.

Dieser muss in jedem Formular und bei jedem AJAX-Request in einem Parameter "wscsrf" mitgegeben werden.

Der atkuelle CSRF-Token lässt sich über das Module $wsActions abfragen.

$wsActions.csrfToken

Aktionen erstellen

Aktionsobjekte werden mithilfe der Funktion $wsActions.create() erstellt.

Mithilfe von Aktionsobjekten kann man prüfen, ob eine Aktion erfolgreich ausgeführt wurde oder ob Fehler aufgetreten sind.

Man kann außerdem auf die Liste der aufgetretenen Fehler zugreifen und bekommt durch die Eigenschaft params Zugriff auf die zuletzt gesendeten Eingabeparameter.

Code Auszug von http://dokuv9.office.websale.net/ref_actions.html

…

Aktions-IDs

Die ID einer Aktion setzt sich zusammen aus dem Namen der Aktion (z. B. BasketItemAdd) und einem optional frei wählbarem Tag, getrennt durch einen Doppelpunkt.

Der Aufruf $wsActions.create("BasketItemAdd", tag="productDetail") erstellt ein Aktionsobjekt mit der ID BasketItemAdd:productDetail.

Diese ID muss an den Shop in dem Request-Parameter wsact übermittelt werden, wenn diese Aktion ausgeführt werden soll.

Wenn kein Tag benötigt wird, kann der Aktionsname für sich alleine als ID benutzt werden. Also z. B. einfach nur BasketItemAdd.

Zugriff auf Informationen zu einer ausgeführten Aktion

Der Zugriff auf alle Informationen zu einer ausgeführten Aktion geschieht mithilfe der Aktionsobjekte.

Ein Aktionsobjekt, dass mithilfe von $wsActions.create() erstellt wird, enthält alle Informationen der in diesem Request ausgeführten Aktion, wenn die ID des erstellten Aktionsobjekts identisch mit der im Request übermittelten Aktions-ID ist.

Zusätzlich kann mittels $wsActions.current immer auf ein Aktionsobjekt zugegriffen werden, das alle Informationen zu der in diesem Request ausgeführten Aktion enthält.

Aktionen taggen

Wenn man mehrere Aktionsobjekte der gleichen Art in derselben View verwendet, würde dies standardmäßig zu einem Problem führen: Da alle diese Aktionsobjekte dieselbe ID haben, würde alle auch dieselben Erfolgs-/Fehlerinformationen teilen.

Um dieses Problem zu umgehen, kann man Aktionen sogenannte Tags zuweisen, mit denen diese unterscheidbar werden.

Wenn man beispielweise auf einer Kategorieseite pro Produktbox ein Formular einfügt, um das Produkt direkt von der Kategorieseite aus in den Warenkorb legen zu können, würden mehrere Aktionsobjekte mit der Aktion BasketItemAdd existieren. Damit würden sich alle diese Aktionsobjekte die Erfolgs-/Fehlerinformationen sowie die zuletzt übermittelten Eingabeparameter teilen.

Würde man allerdings die ID des Produkts als Tag an die Aktion anhängen, haben wir für jedes Produkt ein isoliertes Aktionsobjekt.

{{ var $action = $wsActions.create('BasketItemAdd', tag=$product.id) }}

Eine andere Möglichkeit, dieses Problem zu umgehen, besteht in der Benutzung von Javascript mit Ajax. Dadurch hat man die Möglichkeit, über Javascript zu entscheiden, in welchem Formular die Fehlerinformationen angezeigt werden oder man kann ein Modales Fenster einblenden.

PRG: Weiterleitung nach einer Aktion

WEBSALE V9 bietet für alle Aktionen das Post/Redirect/Get-Verhaltensmuster (PRG).

Im Optimalfall sollte nach jeder erfolgreich ausgeführten Aktion ein Redirect auf eine Zielseite erfolgen.

Durch diesen Redirect landet der Benutzer auf einer Zielseite, auf der er den Refresh-Button (bzw. F5) drücken kann, ohne, dass die Aktion dadurch erneut ausgeführt wird.

Um PRG zu nutzen, muss in das Formular ein zusätzliches Hidden-Feld wstarget eingefügt werden, in dessen value die URL der Zielseite eingetragen wird.

Durch Hinzufügen der nachfolgenden Zeile in das Formular kann man beispielweise erreichen, dass nach dem erfolgreichen Legen eines Produkts in den Warenkorb direkt auf die Warenkorb-View (basket.htm) weitergeleitet wird:

<input type="hidden" name="wstarget" value="{{= $wsViews.viewUrl('basket.htm') }}">

Aktionen mit AJAX ausführen

Aktionen können natürlich nicht nur über HTML-Formulare sondern auch über AJAX mithilfe von Javascript ausgeführt werden.

Das nachfolgende Beispiel zeigt, wie man eine Aktion über AJAX mithilfe des Javascript-Frameworks jQuery absendet:

$.post("{{= $wsViews.viewUrl('ajax/actionResponse.json') }}", {
    "wscsrf": "{{= $wsActions.csrfToken }}",
    "wsact": "BasketItemAdd",
    "productId": "12345",
    "quantity": 2
}, function(data) {
    if (data.success) {
        // action successfull, show modal
    } else {
        // handle data.errors
    }
});

ajax/actionResponse.json:

{{= $wsActions.current|json }}

Die View ajax/actionResponse.json gibt einfach nur die Informationen über die ausgeführte Aktion als JSON zurück.

Session

SessionUpdate

Diese Aktion wird genutzt um Session-Variablen zu schreiben.

Parameter

Name	Beschreibung
session.(variableName)	Erlaubt das Setzen von beliebigen Session-Variablen.

Fehler

keine -

SessionUnlock

Dient zum Entsperren der Session, wenn bei einem online-Bezahlvorgang etwas schiefgelaufen ist.

Hintergrund: Wenn der Shop zu einem Online-Zahlungsanbieter weiterleitet, dann wird die Session gesperrt, so dass nichts mehr am Warenkorb verändert werden kann. Nur in dem Fall, dass der Shop bereits die Session gesperrt hat, aber der Zahlungsanbieter nicht erreichbar ist, sollte diese Aktion verwendet werden.

Parameter

keine -

Fehler

keine -

ConsentChange

Wird verwendet, um die Zustimmung zu nicht essentiellen/zur Funktion nötigen Cookies zu geben. Mit dieser Aktion kann mehrmals geändert werden, welche Cookies erlaubt werden.

Parameter

Name	Beschreibung
consent	Zustimmung zu allen Cookies. Der Wert "on" bedeutet Zustimmung (= das ist der Wert, der automatisch von einer Checkbox gesendet wird)
groups.<groupName>	Zustimmung zu einer gesamten Gruppe. Gruppen können in der Konfiguration gesteuert werden - hier wird auch der `groupName` vergeben. Im Template über `$wsConsent` erreichbar.
groups.<groupName>.services.<serviceName>	Zustimmung zu einem einzelnen Service innerhalb einer Gruppe. Services werden in der Konfiguration gepflegt - hier wird auch der `serviceName` vergeben. Im Template über `$wsConsent` erreichbar.

Fehler

Code	Beschreibung	Parameter
invalidGroup	Gruppe existiert nicht	groups.<groupName>
invalidService	Service existiert nicht	groups.<groupName>.services.<serviceName>

InquirySend

Aktion zum Absenden eines Inquirys

Parameter

Name

Beschreibung

email

E-Mail des Anfragenden

formId

Id des zu verwendenden Formulars

(Formulare existieren unabhängig von Inquiries. Hier wird die Verknüpfung hergestellt. Somit kann mit dem gleichen Formular (z. B. bestehend aus name und Kommentar) verschiedene Inquiries abgesendet werden (z. B. "allgemeine Anfrage", "Partner werden"))

Fehler

Code	Beschreibung	Parameter
missingEmail	Parameter `email` fehlt	email
emailCheckFailed	Parameter `email` enthält keine gültige E-Mail-Adresse	email
emptyForm	Das Formular ist leer	formId
missingFormId	Parameter `formId` ist leer	formId
invalidFormId	Parameter `formId` enthält keine gültige ID eines Formulars (wird in Konfiguration vergeben)	formId
formCheckFailed	Ein Check, der in der Konfiguration bei dem Formular hinterlegt ist, ist fehlgeschlagen. Genauer durch `SubCode` konkretisiert
createInquiryFailed	Inquiry konnte nicht erzeugt werden

WatchListItemAdd

Fügt ein oder mehrere Produkte der Merkliste hinzu.

Parameter

Name	Beschreibung
productId	ID des Produkts, das in den Warenkorb gelegt werden soll. Wenn das Produkt Varianten hat, muss hier die gewünschte Varianten-ID durch einen Punkt (.) getrennt an die Produkt-ID angehängt werden. Also: `<Produkt-ID>.<Varianten-ID>`
freeFields.<identifier>	optionaler Parameter. Inhalt wird in Bestellung mit übernommen. Nutzung: wenn Produkt beschriftet/bedruckt werden soll
multiProducts.<productId>.<quantitiy>	Alternativ zu `productId` und `quantity`, wenn mehrere Producte gleichzeitig in den Warenkorb gelegt werden sollen.

Fehler

Code	Beschreibung	Parameter
missingProductId	Parameter `productId` ist leer.	productId
invalidProductId	Produkt mit der angegebenen Produkt-ID existiert nicht.	productId
invalidVariantId	Eine Variante mit der angegebenen Varianten-ID existiert nicht.	productId

WatchListItemDelete

Entfernt ein Produkt von der Merkliste

Parameter

Name	Beschreibung
watchListItemId	Id der zu entfernenden Position der Merkliste

Fehler

Code	Beschreibung	Parameter
missingWatchListItemId	Parameter `watchListItemId` fehlt	watchListItemId