Skip to main content
With the $wsActions module you can trigger actions in the frontend, for example adding a product to the basket, submitting a form, or logging a customer in or out. Afterwards you evaluate the result (success or error). This page is about triggering and evaluating actions via the $wsActions module. Which actions exist and which parameters a single action (e.g. BasketItemAdd or Login) expects is described in the actions reference. There you will find the functional meaning of the individual action names.

​
Basic concept

An action always goes through the same steps: prepare the action → embed → trigger → read the result → react. You prepare the action in the template, either as a link with the url() function or as a form object with the create() function. The customer then triggers the action by clicking or submitting. The shop executes it and rebuilds the target page. On this new page you find the result under $wsActions.current and can react accordingly, for example with a success message or by displaying errors. Ways to trigger an action
For a simple click, for example on the “Add to basket” button, you create a link with the url() function. If the customer should enter something (e.g. a login with username and password), you create an action object with create() and embed it in a form. The difference therefore lies in whether the customer still enters data or not. Execution time: The template code runs during page rendering. $wsActions.current therefore contains the result of the action that was executed in the request with which this page was generated. If no action was executed, current is null – always check for existence first before accessing results.

​
CSRF protection (applies to all actions)

Every action must send a valid CSRF protection token, otherwise the shop rejects the request. This protects against actions being triggered unintentionally from external pages. When you create actions via url() or create(), the token is embedded automatically. Only if you assemble a request by hand do you have to pass the token from $wsActions.csrfToken yourself as the wscsrf parameter.

​
Availability of current

$wsActions.current is only filled if an action was executed in the same request. On a normally called page, the value is null. That is why the result examples below start with a check: {{ if $wsActions.current }}. Without this check, you would be accessing null.

​
Module overview

Example / excerpt of $wsActions 
{{= $wsActions | json }}
JSON output 
{
  "create": "ƒ()",
  "csrfToken": "...",
  "current": {
    "csrf": "...",
    "error": false,
    "errors": [
      {
        "code": "...",
        "field": "...",
        "subCode": "...",
        "text": "..."
      }
    ],
    "errorsByField": { },
    "globalErrors": [],
    "id": "...",
    "name": "...",
    "params": { },
    "success": true,
    "successInfo": { },
    "tag": "..."
  },
  "url": "ƒ()"
}
Note: "ƒ()" denotes a function (method). current is null if no action was executed. Variables and methods overview
NameReturn typeDescription
csrfTokenstringCSRF protection token of the current session; to be sent as the wscsrf parameter.
currentmapResult of the action that was just executed (success, errors, messages). null if no action ran.
create()mapCreates an action object for use in forms.
url()stringCreates a URL that executes a specific action (for links).

​
Variables

​
$wsActions.csrfToken

Contains the CSRF protection token of the current session. You only need it if you assemble an action request manually. In that case it must be sent as the “wscsrf” parameter so that the shop accepts the request. With url() and create() this happens automatically. 
<input type="hidden" name="wscsrf" value="{{= $wsActions.csrfToken }}">

​
$wsActions.current

Contains the result of the action executed in the current call, i.e. success or error together with messages. The value is null if no action was executed. 
{{ if $wsActions.current }}
  <!-- An action was executed -->
{{ /if }}

​
Properties of $wsActions.current

PropertyReturn typeDescription
namestringName of the executed action (e.g. "BasketItemAdd").
idstringUnique ID of the action. Format: <ActionName>:<ActionTag> if a tag was assigned, otherwise <ActionName>.
csrfstringCSRF token of the executed action.
tagstringAssigned tag of the action, if available.
paramsmapParameter values already passed to the action.
successboolWhether the action was successful.
successInfomapAdditional information from the shop on success.
errorboolWhether an error occurred.
errorslistList of all errors that occurred (structure see below).
errorsByFieldmapErrors assigned to a field (key = field name).
globalErrorslistErrors that cannot be assigned to a field.
The tag (current.tag) is currently not evaluated. You can assign it via create() to distinguish between several similar actions on the same page.

​
Properties of an error (current.errors[])

PropertyReturn typeDescription
codestringError code.
subCodestringOptional code for more precise specification of code.
fieldstringField where the error occurred (empty for global errors).
textstringError text from the configuration.
Evaluate the name of the action Before processing the result, check which action was executed. That way you do not accidentally react to a different action. 
{{ if $wsActions.current and $wsActions.current.name == "Login" }}
  <!-- Login action was executed -->
{{ /if }}
Evaluate success 
{{ if $wsActions.current.success }}
  <!-- Action was successful -->
{{ /if }}
Display errors per field errorsByField assigns errors to an input field. Use this to output an error message directly next to the affected field instead of only a general message. 
{{ if $wsActions.current.errorsByField.zip }}
  <!-- Error in the "zip" field -->
{{ /if }}
List all errors 
{{ foreach $error in $wsActions.current.errors }}
  {{= $error.text }}
{{ /foreach }}

​
Methods

​
$wsActions.create()

Creates an action object for use in forms. Use create() when the customer still enters data before triggering (e.g. login data). The object provides the values (among others id and csrf) that you can embed as hidden form fields. The object has the same properties as $wsActions.current. Signature
$wsActions.create(actionName, paramDefaults, target, tag) Return value
map – the action object. Parameters
NameTypeRequiredDescription
actionNamestringyesName of the action to be executed (e.g. "BasketItemAdd").
paramDefaultsmapnoPreset parameters that can still be changed when the action is executed (e.g. a default quantity).
targetstringnoTarget page after successful execution.
tagstringnoFreely chosen label to distinguish between multiple actions.
Example that creates a basket action: 
{{ var $action = $wsActions.create("BasketItemAdd", { productId: "12345", quantity: 1 }) }}
ID: {{= $action.id }}
CSRF: {{= $action.csrf }}

​
$wsActions.url()

Creates a URL that executes a specific action. Use url() for a link where the customer does not enter any further data (e.g. “Add to basket” or “Log out”). Signature
$wsActions.url(action, target, params) Return value
string – the URL that executes the action. Parameters
NameTypeRequiredDescription
actionstringyesName of the action to be executed.
targetstringyesTarget page after successful execution.
paramsmapyesParameters of the action (e.g. productId).
Example that creates a link for adding to the basket: 
<a href="{{= $wsActions.url('BasketItemAdd', $wsViews.current.url(), { productId: '12345', quantity: 1 }) }}">
  Add to basket
</a>
The function $wsViews.current.url() comes from the $wsViews module and returns the current page as the target. This keeps the customer on the same page after adding.

​
Examples

​
Add a product to the basket and evaluate the result

This example shows the complete flow: the link triggers the action, after the click the page is rebuilt, and current is evaluated.
productId is a placeholder and must be replaced with the ID of an existing product. A non-existent product ID does not result in an evaluable current.error; it may cause the request to fail on the server side.
<!-- 1. Trigger: link that executes the action -->
<a href="{{= $wsActions.url('BasketItemAdd', $wsViews.current.url(), { productId: '12345', quantity: 1 }) }}">
  Add to basket
</a>

<!-- 2. After the click: evaluate the result of the same action -->
{{ if $wsActions.current and $wsActions.current.name == "BasketItemAdd" }}
  {{ if $wsActions.current.success }}
    Product was added to the basket.
  {{ else }}
    {{ foreach $error in $wsActions.current.errors }}
      {{= $error.text }}
    {{ /foreach }}
  {{ /if }}
{{ /if }}
Result
After the click the customer stays on the page and sees either a confirmation or the concrete error messages from the action.

​
Login form with field errors

Here the customer enters data, so the action is prepared with create() and embedded in a form. After submitting, errors are displayed directly at the affected field. 
{{ 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">Log in</button>
</form>
Result
If the data is incorrect, the error message appears directly below the affected field.
  • Actions (concept and reference) – what actions are, how they are secured, and which action names exist with which parameters. This page only shows access via $wsActions.
  • $wsViews – with current.url() and viewUrl() it provides the target pages that url() and create() expect as target.
With the $wsActions module you can trigger actions in the frontend, for example adding a product to the basket, submitting a form, or logging a customer in or out. Afterwards you evaluate the result (success or error). This page is about triggering and evaluating actions via the $wsActions module. Which actions exist and which parameters a single action (e.g. BasketItemAdd or Login) expects is described in the actions reference. There you will find the functional meaning of the individual action names.

​
Basic concept

An action always goes through the same steps: prepare the action → embed → trigger → read the result → react. You prepare the action in the template, either as a link with the url() function or as a form object with the create() function. The customer then triggers the action by clicking or submitting. The shop executes it and rebuilds the target page. On this new page you find the result under $wsActions.current and can react accordingly, for example with a success message or by displaying errors. Ways to trigger an action
For a simple click, for example on the “Add to basket” button, you create a link with the url() function. If the customer should enter something (e.g. a login with username and password), you create an action object with create() and embed it in a form. The difference therefore lies in whether the customer still enters data or not. Execution time: The template code runs during page rendering. $wsActions.current therefore contains the result of the action that was executed in the request with which this page was generated. If no action was executed, current is null – always check for existence first before accessing results.

​
CSRF protection (applies to all actions)

Every action must send a valid CSRF protection token, otherwise the shop rejects the request. This protects against actions being triggered unintentionally from external pages. When you create actions via url() or create(), the token is embedded automatically. Only if you assemble a request by hand do you have to pass the token from $wsActions.csrfToken yourself as the wscsrf parameter.

​
Availability of current

$wsActions.current is only filled if an action was executed in the same request. On a normally called page, the value is null. That is why the result examples below start with a check: {{ if $wsActions.current }}. Without this check, you would be accessing null. 
{
  "create": "ƒ()",
  "csrfToken": "...",
  "current": {
    "csrf": "...",
    "error": false,
    "errors": [
      {
        "code": "...",
        "field": "...",
        "subCode": "...",
        "text": "..."
      }
    ],
    "errorsByField": { },
    "globalErrors": [],
    "id": "...",
    "name": "...",
    "params": { },
    "success": true,
    "successInfo": { },
    "tag": "..."
  },
  "url": "ƒ()"
}
Note: "ƒ()" denotes a function (method). current is null if no action was executed.
NameReturn typeDescription
csrfTokenstringCSRF protection token of the current session; to be sent as the wscsrf parameter.
currentmapResult of the action that was just executed (success, errors, messages). null if no action ran.
create()mapCreates an action object for use in forms.
url()stringCreates a URL that executes a specific action (for links).
Contains the CSRF protection token of the current session. You only need it if you assemble an action request manually. In that case it must be sent as the “wscsrf” parameter so that the shop accepts the request. With url() and create() this happens automatically. 
<input type="hidden" name="wscsrf" value="{{= $wsActions.csrfToken }}">
Contains the result of the action executed in the current call, i.e. success or error together with messages. The value is null if no action was executed. 
{{ if $wsActions.current }}
  <!-- An action was executed -->
{{ /if }}

​
Properties of $wsActions.current

PropertyReturn typeDescription
namestringName of the executed action (e.g. "BasketItemAdd").
idstringUnique ID of the action. Format: <ActionName>:<ActionTag> if a tag was assigned, otherwise <ActionName>.
csrfstringCSRF token of the executed action.
tagstringAssigned tag of the action, if available.
paramsmapParameter values already passed to the action.
successboolWhether the action was successful.
successInfomapAdditional information from the shop on success.
errorboolWhether an error occurred.
errorslistList of all errors that occurred (structure see below).
errorsByFieldmapErrors assigned to a field (key = field name).
globalErrorslistErrors that cannot be assigned to a field.
The tag (current.tag) is currently not evaluated. You can assign it via create() to distinguish between several similar actions on the same page.

​
Properties of an error (current.errors[])

PropertyReturn typeDescription
codestringError code.
subCodestringOptional code for more precise specification of code.
fieldstringField where the error occurred (empty for global errors).
textstringError text from the configuration.
Evaluate the name of the action Before processing the result, check which action was executed. That way you do not accidentally react to a different action. 
{{ if $wsActions.current and $wsActions.current.name == "Login" }}
  <!-- Login action was executed -->
{{ /if }}
Evaluate success 
{{ if $wsActions.current.success }}
  <!-- Action was successful -->
{{ /if }}
Display errors per field errorsByField assigns errors to an input field. Use this to output an error message directly next to the affected field instead of only a general message. 
{{ if $wsActions.current.errorsByField.zip }}
  <!-- Error in the "zip" field -->
{{ /if }}
List all errors 
{{ foreach $error in $wsActions.current.errors }}
  {{= $error.text }}
{{ /foreach }}

​
Methods

​
$wsActions.create()

Creates an action object for use in forms. Use create() when the customer still enters data before triggering (e.g. login data). The object provides the values (among others id and csrf) that you can embed as hidden form fields. The object has the same properties as $wsActions.current. Signature
$wsActions.create(actionName, paramDefaults, target, tag) Return value
map – the action object. Parameters
NameTypeRequiredDescription
actionNamestringyesName of the action to be executed (e.g. "BasketItemAdd").
paramDefaultsmapnoPreset parameters that can still be changed when the action is executed (e.g. a default quantity).
targetstringnoTarget page after successful execution.
tagstringnoFreely chosen label to distinguish between multiple actions.
Example that creates a basket action: 
{{ var $action = $wsActions.create("BasketItemAdd", { productId: "12345", quantity: 1 }) }}
ID: {{= $action.id }}
CSRF: {{= $action.csrf }}

​
$wsActions.url()

Creates a URL that executes a specific action. Use url() for a link where the customer does not enter any further data (e.g. “Add to basket” or “Log out”). Signature
$wsActions.url(action, target, params) Return value
string – the URL that executes the action. Parameters
NameTypeRequiredDescription
actionstringyesName of the action to be executed.
targetstringyesTarget page after successful execution.
paramsmapyesParameters of the action (e.g. productId).
Example that creates a link for adding to the basket: 
<a href="{{= $wsActions.url('BasketItemAdd', $wsViews.current.url(), { productId: '12345', quantity: 1 }) }}">
  Add to basket
</a>
The function $wsViews.current.url()comes from the $wsViews module and returns the current page as the target. This keeps the customer on the same page after adding.

​
Examples

​
Add a product to the basket and evaluate the result

This example shows the complete flow: the link triggers the action, after the click the page is rebuilt, and current is evaluated.
productId is a placeholder and must be replaced with the ID of an existing product. A non-existent product ID does not result in an evaluable current.error; it may cause the request to fail on the server side.
<!-- 1. Trigger: link that executes the action -->
<a href="{{= $wsActions.url('BasketItemAdd', $wsViews.current.url(), { productId: '12345', quantity: 1 }) }}">
  Add to basket
</a>

<!-- 2. After the click: evaluate the result of the same action -->
{{ if $wsActions.current and $wsActions.current.name == "BasketItemAdd" }}
  {{ if $wsActions.current.success }}
    Product was added to the basket.
  {{ else }}
    {{ foreach $error in $wsActions.current.errors }}
      {{= $error.text }}
    {{ /foreach }}
  {{ /if }}
{{ /if }}
Result
After the click the customer stays on the page and sees either a confirmation or the concrete error messages from the action.

​
Login form with field errors

Here the customer enters data, so the action is prepared with create() and embedded in a form. After submitting, errors are displayed directly at the affected field. 
{{ 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">Log in</button>
</form>
Result
If the data is incorrect, the error message appears directly below the affected field.
  • Actions (concept and reference) – what actions are, how they are secured, and which action names exist with which parameters. This page only shows access via $wsActions.
  • $wsViews – with current.url() and viewUrl() it provides the target pages that url() and create() expect as target.