$wsDirectOrder - Direktbestellung - WEBSALE Dokumentation

Mit dem $wsDirectOrder-Modul können Sie den Zustand einer Direktbestellung ablesen. Dabei erfasst der Kunde die Produkte durch Eingabe ihrer Artikelnummern in einem Bestellschein, ohne sie einzeln im Shop suchen zu müssen. Anschließend übernimmt er alle erfassten Positionen in einem Schritt in den Warenkorb. Das Modul liefert die aktuelle Anzahl der Eingabezeilen sowie die bisher erfassten Positionen. Auf dieser Seite geht es um das Lesen des Direktbestell-Zustands. Das Hinzufügen und Löschen von Positionen erfolgt über die Aktionen DirectOrderAdd / DirectOrderDelete.

Grundkonzept

Der Bestellschein ist ein Formular mit mehreren Eingabezeilen. In jede Zeile gibt der Kunde eine Artikelnummer und die entsprechende Menge ein. Beim Absenden prüft die Aktion DirectOrderAdd, ob sich die Eingabe einem Produkt zuordnen lässt, und schreibt die Zeile in die Bestellschein-Liste der Session. In den Warenkorb gelangt dabei noch nichts. Die Übernahme in den Warenkorb ist eigener, zweiter Schritt: Mithilfe des separaten Formulars und der Aktion BasketItemAdd werden alle erfassten Positionen auf einmal abgeschickt. Wie das aussieht, zeigt das Beispiel Positionen in den Warenkorb übernehmen. $wsDirectOrder stellt den aktuellen Zustand bereit:

currentLines: wie viele Eingabezeilen aktuell angezeigt werden. Der Wert stammt aus der Konfiguration ($wsConfig.directOrder: initialNumber bis maximalNumber).
items: die bereits erfassten Positionen, jeweils mit id, quantity, valid und insert.

Ungültige Eingaben

Eine ungültige Eingabe erzeugt keine Zeile in items. Wenn sich eine Artikelnummer keinem Produkt zuordnen lässt oder die Menge ungültig ist, meldet die Aktion DirectOrderAdd den Fehler über errorsByField. Wie Sie diese Meldungen ausgeben, zeigt das Beispiel Fehlermeldungen anzeigen.

Modulübersicht

Beispiel / Ausschnitt über $wsDirectOrder

{{= $wsDirectOrder | json }}

JSON-Ausgabe

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

Variablen in der Übersicht

Variable	Typ	Beschreibung
`currentLines`	int	Aktuelle Anzahl der angezeigten Eingabezeilen.
`items`	array	Erfasste Bestellpositionen (Struktur siehe unten).

Eigenschaften einer Bestellposition (items[])

Eigenschaft	Typ	Beschreibung
`id`	string	Vom Shop ermittelte Produktnummer, bei einer Variante in der Form `Produktnummer.Variante`. Gibt der Kunde eine Artikelnummer, EAN oder ISBN ein, steht hier die zugehörige Produktnummer, nicht die ursprüngliche Eingabe.
`quantity`	int	Erfasste Menge.
`valid`	bool	`true`, wenn die Position gültig ist. Eine ungültige Eingabe erzeugt keine Position, die Meldung kommt von der Aktion `DirectOrderAdd`.
`insert`	string	Für diese Position erfasstes Werbemittelkennzeichen. Leer, wenn kein Code erfasst wurde.

Templates

Der Bestellschein ist standardmäßig im Template modules/directOrder.htm zu finden. Verlinken Sie ihn beispielsweise im Footer (siehe Beispiel).

Variablen

$wsDirectOrder.currentLines

Gibt die aktuelle Anzahl der angezeigten Eingabezeilen aus. Der Wert wird über $wsConfig.directOrder konfiguriert (initialNumber als Start, maximalNumber als Obergrenze). Nutzen Sie ihn beispielsweise, um genau so viele Zeilen zu erzeugen.

Aktuelle Zeilen: {{= $wsDirectOrder.currentLines }}

$wsDirectOrder.items

Gibt die erfassten Bestellpositionen aus. Über den Zeilenindex können Sie auf eine bestimmte Position zugreifen (items[$index]).

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

Eigenschaften einer Bestellposition

Eigenschaft	Typ	Beschreibung
`id`	string	Vom Shop ermittelte Produktnummer, bei einer Variante in der Form `Produktnummer.Variante`. Gibt der Kunde eine Artikelnummer, EAN oder ISBN ein, steht hier die zugehörige Produktnummer, nicht die ursprüngliche Eingabe.
`quantity`	int	Erfasste Menge.
`valid`	bool	`true`, wenn die Position gültig ist. Eine ungültige Eingabe erzeugt keine Position, die Meldung kommt von der Aktion `DirectOrderAdd`.
`insert`	string	Für diese Position erfasstes Werbemittelkennzeichen. Leer, wenn kein Code erfasst wurde.

Weil id die ermittelte Produktnummer enthält, zeigt ein mit items[…].id vorbelegtes Eingabefeld nach dem Absenden nicht mehr die ursprüngliche Eingabe des Kunden. Genau diese Produktnummer benötigen Sie jedoch beim Übernehmen in den Warenkorb.

Methoden

Für $wsDirectOrder stehen keine Methoden zur Verfügung.

Aktionen

$wsDirectOrder selbst stellt keine Aktionen bereit. Das Hinzufügen und Löschen von Positionen erfolgt über die Aktionen.

Beispiele

Bestellschein-Template

Dieses Beispiel erzeugt für jede konfigurierte Zeile (currentLines) eine Eingabereihe. range(0, currentLines - 1) liefert die Indizes 0 bis currentLines - 1. Pro Zeile werden die Aktionen DirectOrderAdd und DirectOrderDelete mit dem Zeilenindex als tag erzeugt, damit Eingaben und Fehler der richtigen Zeile zugeordnet werden. Der Filter ifNull('') setzt einen leeren Wert, falls die Zeile noch nicht erfasst wurde.

{{ extends "layouts/layout.htm" }}
{{ block content_main }}
  <div id="wsBasketWrapper">
    <h1>Direktbestellung</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">
              <!-- Produktsymbol (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>Bitte Artikelnummer eingeben</p>
                <input type="text" name="id" placeholder="Art.-Nr."
                       value="{{= $wsDirectOrder.items[$cProduct].id | ifNull('') }}">
                <label>Menge</label>
                <input type="text" name="quantity"
                       value="{{= $wsDirectOrder.items[$cProduct].quantity | ifNull('') }}">
                <button type="submit" name="wsact" value="{{= $cActionDirectOrderAdd.id }}">Suchen</button>
                <button type="submit" name="wsact" value="{{= $cActionDirectOrderDelete.id }}">Löschen</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 }}

Ergebnis
Ein Bestellschein mit so vielen Eingabereihen, wie currentLines vorgibt. Bereits erfasste Zeilen haben ihre Artikelnummer und Menge vorbelegt.

Fehlermeldungen anzeigen

Die Aktion DirectOrderAdd meldet feldbezogene Fehler über errorsByField. Dabei hängen nicht alle Fehler am selben Feld:

Fehler zur Artikelnummer und zum Produkt finden Sie unter errorsByField.id.
Fehler zur Menge stehen unter errorsByField.quantity.
Fehler der Artikelnummern-Felder aus itemNumberFields stehen unter dem Namen des jeweiligen Eingabefeldes, beispielsweise errorsByField.firstField. Dies betrifft die Fehlermeldungen itemNumberCheckFailed und missingId bei einem leeren Pflichtfeld.

Welcher Fehlercode an welchem Feld gemeldet wird, steht unter actions.directOrder. Dieses Beispiel zeigt die Fehler zur Artikelnummer (id) und zur Menge (quantity) je Zeile.

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

Wenn der Bestellschein mit Artikelnummern-Feldern arbeitet, ergänzen Sie innerhalb derselben Schleife die Ausgabe für jedes Feld. Die Typprüfung ist nötig, weil itemNumberFields auch Trennzeichen enthält und diese keinen Namen haben.

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

Die Ausgabe je Artikelnummern-Feld ergänzt die Ausgabe von errorsByField.id, sie ersetzt diese nicht. Wenn sich die zusammengesetzte Artikelnummer keinem Produkt zuordnen lässt, meldet die Aktion invalidId am Feld id . Das gilt auch, wenn die Zeile gar kein Eingabefeld id enthält.

Ergebnis
Bei einer fehlerhaften Eingabe - beispielsweise einer ungültigen Artikelnummer oder Menge - erscheint die entsprechende Meldung in der betreffenden Zeile.

Positionen in den Warenkorb übernehmen

Die mit DirectOrderAdd erfassten Positionen liegen zunächst nur in der Liste des Bestellscheins. Ein eigenes Formular übernimmt sie mit der Aktion BasketItemAdd in den Warenkorb. Dabei wird pro erfasster Position ein verstecktes Feld namens multiProducts.<Produktnummer>.quantity mitgeschickt. Bei aktivierter Werbemittelkennzeichnung kommt pro Position zusätzlich das Feld multiProducts.<Produktnummer>.insert hinzu.

{{ 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 }}>In den Warenkorb</button>
</form>

Ergebnis
Es gibt einen Button, der alle erfassten Positionen mit ihrer Menge und gegebenfalls ihrem Werbemittelkennzeichen in den Warenkorb legt. Solange keine Positionen erfasst sind, ist der Button deaktiviert.

Als Feldname dient die ermittelte Produktnummer aus items[…].id, nicht die Eingabe des Kunden. Eine Variante wird so über multiProducts.<Produktnummer>.<Variante>.quantity übergeben. Ist eine der übergebenen Positionen ungültig, legt der Shop keine davon in den Warenkorb.

Den Link zur Direktbestellung erzeugen Sie mit viewUrl(). Den Pfad zum Template als Argument übergeben.

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

Ergebnis
Ein Link, der zur Direktbestell-Seite führt.

Weiterführende Links

$wsActions – stellt die Aktionen DirectOrderAdd / DirectOrderDelete und die Fehlerstruktur errorsByField bereit.
$wsConfig.directOrder – konfiguriert Zeilenanzahl und zusätzliche Artikelnummer-Felder.
Online-Bestellschein – ausführliches Praxisbeispiel.
checkout - Bestellablauf – Konfiguration des Bestellablaufs.
Basket: Aktion BasketItemAdd zum Übernehmen der Positionen in den Warenkorb.

WEBSALE

Frontend

Die Basics

Getting Started

Referenz – Aktionen

Referenz – Sprache

Referenz – Module

Integrationsanleitung

Praxisbeispiele

$wsDirectOrder - Direktbestellung

Grundkonzept

Ungültige Eingaben

Modulübersicht

Templates

Variablen

$wsDirectOrder.currentLines

$wsDirectOrder.items

Eigenschaften einer Bestellposition

Methoden

Aktionen

Beispiele

Bestellschein-Template

Fehlermeldungen anzeigen

Positionen in den Warenkorb übernehmen

Seite im Footer verlinken

Weiterführende Links

​Grundkonzept

​Ungültige Eingaben

​Modulübersicht

​Templates

​Variablen

​$wsDirectOrder.currentLines

​$wsDirectOrder.items

​Eigenschaften einer Bestellposition

​Methoden

​Aktionen

​Beispiele

​Bestellschein-Template

​Fehlermeldungen anzeigen

​Positionen in den Warenkorb übernehmen

​Seite im Footer verlinken

​Weiterführende Links

Grundkonzept

Ungültige Eingaben

Modulübersicht

Templates

Variablen

$wsDirectOrder.currentLines

$wsDirectOrder.items

Eigenschaften einer Bestellposition

Methoden

Aktionen

Beispiele

Bestellschein-Template

Fehlermeldungen anzeigen

Positionen in den Warenkorb übernehmen

Seite im Footer verlinken

Weiterführende Links