$wsDirectOrder - Direct order - WEBSALE Dokumentation

With the $wsDirectOrder module, you can read the state of a direct order. Here, the customer records products by entering their item numbers in an order form, without having to search for them individually in the shop. They then transfer all recorded items to the basket in one step. The module returns the current number of input lines as well as the items recorded so far. This page covers reading the direct-order state. Adding and deleting items happens via the DirectOrderAdd / DirectOrderDelete actions.

Basic concept

The order form is a form with several input lines. In each line, the customer enters an item number and the corresponding quantity. When submitted, the DirectOrderAdd action checks whether the input can be assigned to a product and writes the line to the session’s order form list. Nothing reaches the basket at this point. Transferring to the basket is a separate, second step: using the separate form and the BasketItemAdd action, all recorded items are submitted at once. The example Transfer items to the basket shows what this looks like. $wsDirectOrder provides the current state:

currentLines: how many input lines are currently displayed. The value comes from the configuration ($wsConfig.directOrder: initialNumber to maximalNumber).
items: the items already recorded, each with id, quantity, valid, and insert.

Invalid input

An invalid input does not create a line in items. If an item number cannot be assigned to a product or the quantity is invalid, the DirectOrderAdd action reports the error via errorsByField. The example Display error messages shows how to output these messages.

Module overview

Example / excerpt of $wsDirectOrder

{{= $wsDirectOrder | json }}

JSON output

{
  "currentLines": 5,
  "items": [
    { "id": "123-45678", "quantity": 1, "valid": true, "insert": "" },
    { "id": "910-111213.blau", "quantity": 3, "valid": true, "insert": "AB" }
  ]
}

Variables overview

Variable	Type	Description
`currentLines`	int	Current number of displayed input lines.
`items`	array	Recorded order items (structure see below).

Properties of an order item (items[])

Property	Type	Description
`id`	string	Product number determined by the shop, for a variant in the form `productNumber.variant`. If the customer enters an item number, EAN, or ISBN, this contains the corresponding product number, not the original input.
`quantity`	int	Recorded quantity.
`valid`	bool	`true` if the item is valid. An invalid input does not create an item; the message comes from the `DirectOrderAdd` action.
`insert`	string	Insert code recorded for this item. Empty if no code was recorded.

Templates

By default, the order form can be found in the template modules/directOrder.htm. Link it, for example, in the footer (see example).

Variables

$wsDirectOrder.currentLines

Returns the current number of displayed input lines. The value is configured via $wsConfig.directOrder (initialNumber as the start, maximalNumber as the upper limit). Use it, for example, to generate exactly that many lines.

Current lines: {{= $wsDirectOrder.currentLines }}

$wsDirectOrder.items

Returns the recorded order items. You can use the line index to access a specific item (items[$index]).

{{ foreach $item in $wsDirectOrder.items }}
  {{= $item.id }}, Quantity: {{= $item.quantity }}
{{ /foreach }}

Properties of an order item

Property	Type	Description
`id`	string	Product number determined by the shop, for a variant in the form `productNumber.variant`. If the customer enters an item number, EAN, or ISBN, this contains the corresponding product number, not the original input.
`quantity`	int	Recorded quantity.
`valid`	bool	`true` if the item is valid. An invalid input does not create an item; the message comes from the `DirectOrderAdd` action.
`insert`	string	Insert code recorded for this item. Empty if no code was recorded.

Because id contains the determined product number, an input field pre-filled with items[…].id no longer shows the customer’s original input after submission. However, you need exactly this product number when transferring to the basket.

Methods

No methods are available for $wsDirectOrder.

Actions

$wsDirectOrder itself does not provide any actions. Adding and deleting items happens via the actions.

Examples

Order form template

This example generates an input row for every configured line (currentLines). range(0, currentLines - 1) returns the indexes 0 to currentLines - 1. For each line, the actions DirectOrderAdd and DirectOrderDelete are created with the line index as tag, so that inputs and errors are assigned to the correct line. The ifNull('') filter sets an empty value if the line has not yet been filled in.

{{ extends "layouts/layout.htm" }}
{{ block content_main }}
  <div id="wsBasketWrapper">
    <h1>Direct order</h1>
    <table class="table">
      <tbody id="wsDirectOrderTableBody">
        {{ foreach $cProduct in range(0, $wsDirectOrder.currentLines - 1) }}
          {{ var $cActionDirectOrderAdd = $wsActions.create("DirectOrderAdd", tag=string($cProduct)) }}
          {{ var $cActionDirectOrderDelete = $wsActions.create("DirectOrderDelete", tag=string($cProduct)) }}
          <tr class="wsDirectOrderRow">
            <td class="wsTableCellMin">
              <!-- Product icon (SVG) -->
            </td>
            <td>
              <form method="POST" action="{{= $wsViews.current.url() }}">
                <input type="hidden" name="wscsrf" value="{{= $cActionDirectOrderAdd.csrf }}">
                <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">
                <p>Please enter item number</p>
                <input type="text" name="id" placeholder="Item no."
                       value="{{= $wsDirectOrder.items[$cProduct].id | ifNull('') }}">
                <label>Quantity</label>
                <input type="text" name="quantity"
                       value="{{= $wsDirectOrder.items[$cProduct].quantity | ifNull('') }}">
                <button type="submit" name="wsact" value="{{= $cActionDirectOrderAdd.id }}">Search</button>
                <button type="submit" name="wsact" value="{{= $cActionDirectOrderDelete.id }}">Delete</button>

                {{ foreach $field in $wsConfig.directOrder.itemNumberFields }}
                  {{ if $field.type == "field" }}
                    <input type="text" name="{{= $field.name }}">
                  {{ elseif $field.type == "separator" }}
                    {{= $field.sign }}
                  {{ /if }}
                {{ /foreach }}
              </form>
            </td>
          </tr>
        {{ /foreach }}
      </tbody>
    </table>
  </div>
{{ /block }}

Result
An order form with as many input rows as currentLines specifies. Rows that have already been filled in are pre-populated with their item number and quantity.

Display error messages

The DirectOrderAdd action reports field-related errors via errorsByField. Not all errors are attached to the same field:

Errors relating to the item number and the product can be found under errorsByField.id.
Errors relating to the quantity are under errorsByField.quantity.
Errors of the item number fields from itemNumberFields are under the name of the respective input field, for example errorsByField.firstField. This concerns the error messages itemNumberCheckFailed and missingId for an empty required field.

Which error code is reported on which field is described under actions.directOrder. This example shows the errors for the item number (id) and the quantity (quantity) per line.

{{ foreach $cProduct in range(0, $wsDirectOrder.currentLines - 1) }}
  {{ var $cActionDirectOrderAdd = $wsActions.create("DirectOrderAdd", tag=string($cProduct)) }}

  {{ if $cActionDirectOrderAdd.errorsByField.id }}
    <div class="alert alert-danger">
      {{ foreach $err in $cActionDirectOrderAdd.errorsByField.id }}
        {{ if $err.text }}{{= $err.text }}{{ else }}{{= $err.code }}{{ /if }}
      {{ /foreach }}
    </div>
  {{ /if }}

  {{ if $cActionDirectOrderAdd.errorsByField.quantity }}
    <div class="alert alert-danger">
      {{ foreach $err in $cActionDirectOrderAdd.errorsByField.quantity }}
        {{ if $err.text }}{{= $err.text }}{{ else }}{{= $err.code }}{{ /if }}
      {{ /foreach }}
    </div>
  {{ /if }}
{{ /foreach }}

If the order form works with item number fields, add the output for each field within the same loop. The type check is necessary because itemNumberFields also contains separators, and these have no name.

{{ foreach $field in $wsConfig.directOrder.itemNumberFields }}
  {{ if $field.type == "field" and $cActionDirectOrderAdd.errorsByField[$field.name] }}
    <div class="alert alert-danger">
      {{ foreach $err in $cActionDirectOrderAdd.errorsByField[$field.name] }}
        {{ if $err.text }}{{= $err.text }}{{ else }}{{= $err.code }}{{ /if }}
      {{ /foreach }}
    </div>
  {{ /if }}
{{ /foreach }}

The output per item number field supplements the output of errorsByField.id; it does not replace it. If the composed item number cannot be assigned to a product, the action reports invalidId on the id field. This also applies if the line does not contain an id input field at all.

Result
On invalid input, for example an invalid item number or quantity, the corresponding message appears in the affected line.

Transfer items to the basket

The items recorded with DirectOrderAdd are initially only in the order form list. A separate form transfers them to the basket with the BasketItemAdd action. For each recorded item, a hidden field named multiProducts.<productNumber>.quantity is sent. If insert codes are enabled, the field multiProducts.<productNumber>.insert is also added for each item.

{{ var $cActionBasketItemAdd = $wsActions.create("BasketItemAdd", tag="directorder") }}
<form method="post" action="{{= $wsViews.current.url() }}">
  <input type="hidden" name="wsact" value="{{= $cActionBasketItemAdd.id }}">
  <input type="hidden" name="wscsrf" value="{{= $cActionBasketItemAdd.csrf }}">
  <input type="hidden" name="wstarget" value="{{= $wsViews.viewUrl('basket.htm') }}">

  {{ foreach $item in $wsDirectOrder.items }}
    <input type="hidden" name="multiProducts.{{= $item.id }}.quantity" value="{{= $item.quantity }}">
    {{ if $item.insert }}
      <input type="hidden" name="multiProducts.{{= $item.id }}.insert" value="{{= $item.insert }}">
    {{ /if }}
  {{ /foreach }}

  <button type="submit"{{ if not $wsDirectOrder.items }} disabled{{ /if }}>Add to basket</button>
</form>

Result
There is a button that adds all recorded items with their quantity and, if applicable, their insert code to the basket. As long as no items have been recorded, the button is disabled.

The field name is the determined product number from items[…].id, not the customer’s input. A variant is therefore passed via multiProducts.<productNumber>.<variant>.quantity. If one of the submitted items is invalid, the shop adds none of them to the basket.

You generate the link to the direct order with viewUrl(). Pass the path to the template as the argument.

<a href="{{= $wsViews.viewUrl('modules/directOrder.htm') }}">Direct order</a>

Result
A link that leads to the direct-order page.

$wsActions – provides the actions DirectOrderAdd / DirectOrderDelete and the error structure errorsByField.
$wsConfig.directOrder – configures the number of lines and additional item-number fields.
Online order form – detailed practical example.
checkout - Order process – configuration of the order process.
Basket: BasketItemAdd action for transferring the items to the basket.

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

$wsDirectOrder - Direct order

Basic concept

Invalid input

Module overview

Templates

Variables

$wsDirectOrder.currentLines

$wsDirectOrder.items

Properties of an order item

Methods

Actions

Examples

Order form template

Display error messages

Transfer items to the basket

Link the page in the footer

​Basic concept

​Invalid input

​Module overview

​Templates

​Variables

​$wsDirectOrder.currentLines

​$wsDirectOrder.items

​Properties of an order item

​Methods

​Actions

​Examples

​Order form template

​Display error messages

​Transfer items to the basket

​Link the page in the footer

​Related links

Basic concept

Invalid input

Module overview

Templates

Variables

$wsDirectOrder.currentLines

$wsDirectOrder.items

Properties of an order item

Methods

Actions

Examples

Order form template

Display error messages

Transfer items to the basket

Link the page in the footer

Related links