SUBS- (Abos verwalten) - WEBSALE Dokumentation

Hat ein Kunde Produkte abonniert, will er sie auch wieder im Griff haben: nachsehen, wann die nächste Lieferung kommt, die Menge ändern, ein Abo für den Sommer pausieren oder ganz beenden. Dafür gibt es eine eigene Seite im Shop, und die Tags dieser Seite bauen sie auf. Alles dreht sich dabei um eine Schleife. SUBS-Data läuft über die Abos des angemeldeten Kunden, und innerhalb dieser Schleife liefern alle weiteren Tags die Angaben zum jeweiligen Abo.

Wegweiser: Abo-Modul
Referenz: SUBS- (Abo abschließen)

Die Schleife über die Abos

SUBS-Data kann drei Dinge: als Einzel-Tag die Anzahl der Abos ausgeben, als Klammerung prüfen ob es überhaupt welche gibt, und als Schleife über sie laufen.

{SUBS-Data}
   <p>Sie haben ~SUBS-Data~ Abos abgeschlossen.</p>

   <form action="~FORM-Subscription~" method="post">
      {@SUBS-Data}
         ...
      {/@SUBS-Data}
   </form>
{/SUBS-Data}

{!SUBS-Data}
   <p>Sie haben derzeit keine Produkte abonniert.</p>
{/!SUBS-Data}

Alle übrigen Tags dieser Seite sind außerhalb der SUBS-Data-Schleife ungültige Tags. Das gilt auch innerhalb der Klammerung {SUBS-Data}, denn erst die Schleife legt fest, um welches Abo es geht. Die Ausnahme sind die beiden Tags für den Knopf, mit dem neue Abos angestoßen werden.

SUBS-Data gibt es nicht nur auf der Verwaltungsseite. Die Schleife arbeitet auf allen Templates, solange ein Käufer angemeldet ist. Auf einer Übersichtsseite lässt sich damit beispielsweise die Zahl der laufenden Abos anzeigen.

Das abonnierte Produkt

Tag	Liefert
`SUBS-Data_Index`	die technische Kennung des Abos
`SUBS-Data_PR_Index`	den Produktindex
`SUBS-Data_PR_Number`	die Produktnummer
`SUBS-Data_PR_Name`	den Produktnamen
`SUBS-Data_PR_Price`	den Preis
`SUBS-Data_PR_CurrencyCode`	den Währungscode
`SUBS-Data_PR_Quantity`	die abonnierte Menge
`SUBS-Data_PR_Quantity_input`	den HTML-Namen des Mengenfelds
`SUBS-Data_SubShop()`	die Kennung des Subshops, in dem abonniert wurde

{@SUBS-Data}
   <h3>~SUBS-Data_PR_Name~</h3>
   {SUBS-Data_PR_Number}<p>Artikelnummer ~SUBS-Data_PR_Number~</p>{/SUBS-Data_PR_Number}
   <p>~SUBS-Data_PR_Price~ ~SUBS-Data_PR_CurrencyCode~</p>

   <label>
      Menge
      <input name="~SUBS-Data_PR_Quantity_input~" value="~SUBS-Data_PR_Quantity~">
   </label>
{/@SUBS-Data}

Produktname, Preis und Währungscode sind am Abo gespeichert und stammen aus dem Zeitpunkt der letzten Bestellung oder der letzten Änderung des Abos. Sie sind damit eine Momentaufnahme und nicht der heutige Stand des Produkts. Soll der aktuelle Preis erscheinen, lesen Sie das Produkt über seinen Index neu ein.

SUBS-Data_Index ist die Kennung, mit der das Shopsystem dieses eine Abo anspricht. Sie steckt in allen Feldnamen innerhalb der Schleife und sorgt dafür, dass eine Formularseite mit mehreren Abos eindeutig bleibt. SUBS-Data_SubShop() nimmt wahlweise Subshop-Kennungen als Parameter entgegen und greift dann als Klammerung nur für diese. Ohne Parameter gibt es die Kennung aus, in der das Produkt abonniert wurde.

Das Lieferintervall

Tag	Liefert
`SUBS-Data_Cycle_count`	die Anzahl der Einheiten
`SUBS-Data_Cycle_unit_code`	den technischen Code der Einheit
`SUBS-Data_Cycle_unit_isday`	Klammerung: die Einheit ist Tag, Code 0
`SUBS-Data_Cycle_unit_ismonth`	Klammerung: die Einheit ist Monat, Code 1
`SUBS-Data_Cycle_unit_isyear`	Klammerung: die Einheit ist Jahr, Code 2
`SUBS-Data_Cycle_unit_isweek`	Klammerung: die Einheit ist Woche, Code 3

{@SUBS-Data}
   {SUBS-Data_Cycle_count}
      <p>
         Lieferung alle ~SUBS-Data_Cycle_count~
         {SUBS-Data_Cycle_unit_isday}Tage{/SUBS-Data_Cycle_unit_isday}
         {SUBS-Data_Cycle_unit_isweek}Wochen{/SUBS-Data_Cycle_unit_isweek}
         {SUBS-Data_Cycle_unit_ismonth}Monate{/SUBS-Data_Cycle_unit_ismonth}
         {SUBS-Data_Cycle_unit_isyear}Jahre{/SUBS-Data_Cycle_unit_isyear}
      </p>
   {/SUBS-Data_Cycle_count}
{/@SUBS-Data}

Auch hier folgen die Codes nicht der Länge der Zeiträume. Die Woche hat den Code 3 und steht hinter dem Jahr. Werten Sie _unit_code deshalb nie mit einem Größenvergleich aus.

Das Intervall ändern lassen

Soll der Kunde das Intervall umstellen, bauen Sie innerhalb der Schleife dieselbe Auswahl wie auf der Produktseite auf. SUBS-CycleSelection_input liefert dort automatisch den auf dieses Abo bezogenen Feldnamen, und SUBS-CycleSelection_data_selected vergleicht gegen das gespeicherte Intervall statt gegen eine Formulareingabe.

{@SUBS-Data}
   <select name="~SUBS-CycleSelection_input~">
      {@SUBS-CycleSelection_data}
         <option value="~SUBS-CycleSelection_data_value~" ~SUBS-CycleSelection_data_selected~>~SUBS-CycleSelection_data_descr~</option>
      {/@SUBS-CycleSelection_data}
   </select>
{/@SUBS-Data}

Referenz: Die Zyklusauswahl auf der Seite SUBS- (Abo abschließen)

Zeitpunkte und Zähler

Alle vier Zeitangaben kommen als Unix-Zeitstempel und werden über die Datums-Tags in eine lesbare Form gebracht.

Tag	Liefert
`SUBS-Data_created_unixtimestamp`	wann das Abo angelegt wurde
`SUBS-Data_lastchange_unixtimestamp`	wann es zuletzt geändert wurde
`SUBS-Data_lastorder_unixtimestamp`	wann zuletzt bestellt wurde
`SUBS-Data_nextorder_unixtimestamp`	wann die nächste Bestellung angestoßen wird
`SUBS-Data_counter_orderedviasubscription`	wie oft über dieses Abo bestellt wurde

{@SUBS-Data}
   {SUBS-Data_nextorder_unixtimestamp}
      ~DC-DateTime_setunixtimestamp($SUBS-Data_nextorder_unixtimestamp$)~
      <p>Nächste Lieferung am ~DC-DateTime_day~.~DC-DateTime_month~.~DC-DateTime_year~</p>
   {/SUBS-Data_nextorder_unixtimestamp}
{/@SUBS-Data}

Bei SUBS-Data_nextorder_unixtimestamp ist nur der Datumsanteil belastbar. Die Uhrzeit darin sagt nichts darüber aus, wann an diesem Tag tatsächlich bestellt wird. Alle fünf Tags greifen als Klammerung dann, wenn ein Wert vorliegt. Bei einem frisch angelegten Abo sind der Zeitpunkt der letzten Bestellung und der Zähler noch leer. Klammern Sie die Ausgabe deshalb, statt eine 0 oder den 1.1.1970 anzuzeigen. Referenz: DC- (Datum und Uhrzeit)

Der Zustand des Abos

SUBS-Data_state_code gibt den technischen Code aus, vier Klammerungen fragen ihn ab.

Code	Zustand	Klammerung
0	aktiv	`SUBS-Data_state_isactive`
1	neu und aktiv	`SUBS-Data_state_isnew`
2	neu, aktiv und angestoßen	`SUBS-Data_state_istriggered`
3	pausiert	`SUBS-Data_state_ispaused`

{@SUBS-Data}
   {SUBS-Data_state_ispaused}<span class="pausiert">pausiert</span>{/SUBS-Data_state_ispaused}
   {SUBS-Data_state_isactive}<span class="aktiv">läuft</span>{/SUBS-Data_state_isactive}
{/@SUBS-Data}

Die vier Zustände schließen sich gegenseitig aus. SUBS-Data_state_isactive greift ausschließlich beim Code 0 und damit gerade nicht bei einem neuen Abo, obwohl dieses ebenfalls läuft. Wollen Sie “läuft” im Sinne von “nicht pausiert” ausdrücken, nehmen Sie die negative Klammerung von SUBS-Data_state_ispaused.

Die Zustände 1 und 2 betreffen den Übergang vom Abschluss zur ersten Lieferung. Ein Abo ist zunächst neu, und sobald die erste Bestellung angestoßen wurde, gilt es als angestoßen. Danach wechselt es auf aktiv. SUBS-Data_state_code ist ausschließlich ein Einzel-Tag. Für Fallunterscheidungen nehmen Sie die vier Klammerungen.

Pausieren, fortsetzen und löschen

Die Aktionen laufen über je einen Knopf. SUBS-Data_Buttonname liefert den Namen, die drei Buttonvalue-Tags den Wert.

Tag	Aktion
`SUBS-Data_Buttonvalue_pause`	das Abo pausieren
`SUBS-Data_Buttonvalue_resume`	das Abo fortsetzen
`SUBS-Data_Buttonvalue_delete`	das Abo löschen

{@SUBS-Data}
   {SUBS-Data_Buttonvalue_pause}
      <button type="submit" name="~SUBS-Data_Buttonname~" value="~SUBS-Data_Buttonvalue_pause~">pausieren</button>
   {/SUBS-Data_Buttonvalue_pause}

   {SUBS-Data_Buttonvalue_resume}
      <button type="submit" name="~SUBS-Data_Buttonname~" value="~SUBS-Data_Buttonvalue_resume~">fortsetzen</button>
   {/SUBS-Data_Buttonvalue_resume}

   <button type="submit" name="~SUBS-Data_Buttonname~" value="~SUBS-Data_Buttonvalue_delete~">löschen</button>
{/@SUBS-Data}

Pausieren und Fortsetzen sind nur im jeweils passenden Zustand verfügbar. SUBS-Data_Buttonvalue_pause liefert bei einem bereits pausierten Abo nichts und greift dort auch als Klammerung nicht, SUBS-Data_Buttonvalue_resume umgekehrt nur bei einem pausierten Abo. Klammern Sie die beiden Knöpfe deshalb mit ihrem eigenen Tag, dann erscheint jeweils nur der sinnvolle. Löschen ist immer verfügbar. Die Klammerung von SUBS-Data_Buttonvalue_delete greift in jedem Zustand und dient eher der Einheitlichkeit des Templates als einer Fallunterscheidung.

Das Löschen geschieht ohne Rückfrage des Shopsystems. Bauen Sie eine Sicherheitsabfrage in das Template ein, denn ein versehentlich gelöschtes Abo lässt sich vom Kunden nicht wiederherstellen.

Die Rückmeldung nach einer Aktion

Nach dem Absenden sagen fünf Tags je Abo, was mit ihm geschehen ist.

Tag	Greift
`SUBS-Data_affected`	wenn dieses Abo von der letzten Aktion betroffen war
`SUBS-Data_affected_changed`	wenn Menge oder Lieferintervall geändert wurden, Code 1
`SUBS-Data_affected_paused`	wenn es pausiert wurde, Code 2
`SUBS-Data_affected_resumed`	wenn es fortgesetzt wurde, Code 3
`SUBS-Data_affected_code`	gibt den Code aus und greift, wenn einer vorliegt

{@SUBS-Data}
   {SUBS-Data_affected}
      {SUBS-Data_affected_changed}<p class="hinweis">Ihre Änderung wurde übernommen.</p>{/SUBS-Data_affected_changed}
      {SUBS-Data_affected_paused}<p class="hinweis">Dieses Abo ist jetzt pausiert.</p>{/SUBS-Data_affected_paused}
      {SUBS-Data_affected_resumed}<p class="hinweis">Dieses Abo läuft wieder.</p>{/SUBS-Data_affected_resumed}
   {/SUBS-Data_affected}
{/@SUBS-Data}

Der Code 0 bedeutet “nicht betroffen”. Er wird nie ausgegeben, denn in diesem Fall greift bereits SUBS-Data_affected nicht. Die vier Codes sind damit: 0 nicht betroffen, 1 geändert, 2 pausiert, 3 fortgesetzt.

Für ein gelöschtes Abo gibt es keine Rückmeldung. Es steht nach der Aktion nicht mehr in der Liste, und die Schleife läuft nicht darüber. Eine Erfolgsmeldung zum Löschen gehört deshalb außerhalb der Schleife, nicht hinein.

Die Rückmeldung gilt für den Aufruf unmittelbar nach dem Absenden. Lädt der Kunde die Seite neu, ist sie weg.

Zahlungsart, Bankverbindung und Lieferadresse je Abo

Diese drei Angaben sind am einzelnen Abo gespeichert. Alle drei Tags geben den Wert als Einzel-Tag aus und greifen als Klammerung, wenn er gesetzt ist. Mit einem Parameter prüfen sie stattdessen auf Gleichheit.

Tag	Liefert
`SUBS-Data_PaymentCode()`	den Zahlungsartencode des Abos
`SUBS-Data_BankIndex()`	die Kennung der Bankverbindung
`SUBS-Data_DelivAddress()`	den Index der Lieferadresse

{@SUBS-Data}
   {SUBS-Data_DelivAddress}
      <p>Lieferung an Adresse ~SUBS-Data_DelivAddress~</p>
   {/SUBS-Data_DelivAddress}

   {!SUBS-Data_DelivAddress}
      <p>Lieferung an die Rechnungsadresse</p>
   {/!SUBS-Data_DelivAddress}
{/@SUBS-Data}

Beim Index 0 greift die Klammerung nicht. Das ist hier kein fehlender Wert, sondern eine Aussage: 0 bedeutet bei SUBS-Data_DelivAddress(), dass keine abweichende Lieferadresse hinterlegt ist, und bei SUBS-Data_BankIndex(), dass keine Bankverbindung am Abo hängt. Fangen Sie diesen Fall mit der negativen Klammerung ab.

Das ist ein Fehler in der Vorlage. Hier steht der berichtigte Vergleich.

{@SUBS-Data}
   {SUBS-Data_BankIndex(1)}
      <p>Dieses Abo wird über die erste Bankverbindung abgebucht.</p>
   {/SUBS-Data_BankIndex(1)}
{/@SUBS-Data}

Der Bankindex ist nur bei Lastschrift von Belang. Bei anderen Zahlungsarten steht dort in aller Regel die 0.

Die Auswahl zum Ändern aufbauen

Soll der Kunde diese drei Angaben umstellen, nehmen Sie dieselben _input und _selected-Tags wie auf der Produktseite. Innerhalb der Schleife hängen die _input-Tags die Abo-Kennung an den Feldnamen an, sodass auch eine Seite mit mehreren Abos eindeutig bleibt.

Tag	HTML-Name innerhalb der Schleife
`SUBS-CycleSelection_input`	`ws_subscription_cycle_<Kennung>`
`SUBS-Data_PR_Quantity_input`	`ws_subscription_qty_<Kennung>`
`SUBS-PaymentMethod_input`	`ws_subscription_payment_<Kennung>`
`SUBS-BankIndex_input`	`ws_subscription_bank_<Kennung>`
`SUBS-DelivAddress_input`	`ws_subscription_deliv_<Kennung>`

Die _selected-Tags vergleichen gegen die zuletzt abgeschickte Formulareingabe, nicht gegen den am Abo gespeicherten Wert. Für den gespeicherten Stand nehmen Sie SUBS-Data_PaymentCode(), SUBS-Data_BankIndex() und SUBS-Data_DelivAddress() mit Parameter. Die Ausnahme ist SUBS-CycleSelection_data_selected, das innerhalb der Schleife von sich aus gegen das gespeicherte Intervall prüft.

{@SUBS-Data}
   <select name="~SUBS-DelivAddress_input~">
      <option value="0" {SUBS-Data_DelivAddress(0)}selected{/SUBS-Data_DelivAddress(0)}>Rechnungsadresse verwenden</option>
      {D-DeliverySelection}
         {@D-Data}
            <option value="~D-DeliverySelection_value~"
                    {SUBS-Data_DelivAddress($D-DeliverySelection_value$)}selected{/SUBS-Data_DelivAddress($D-DeliverySelection_value$)}>
               ~D-FirstName~ ~D-LastName~, ~D-Zip~ ~D-City~
            </option>
         {/@D-Data}
      {/D-DeliverySelection}
   </select>
{/@SUBS-Data}

Neue Abos anstoßen

Hat der Kunde ein Abo frisch abgeschlossen, steht es zunächst als neu in der Liste, ohne dass schon bestellt wurde. Ein eigener Knopf stößt die erste Bestellung an.

Tag	Liefert
`SUBS-Buttonname`	den HTML-Namen des Knopfes, fest `button_subscription_global`
`SUBS-Buttonvalue_triggernewsubscriptions`	den Wert, und als Klammerung ob es überhaupt neue Abos gibt

{SUBS-Buttonvalue_triggernewsubscriptions}
   <button type="submit" name="~SUBS-Buttonname~" value="~SUBS-Buttonvalue_triggernewsubscriptions~">
      Neue Abos jetzt starten
   </button>
{/SUBS-Buttonvalue_triggernewsubscriptions}

Beide Tags gehören außerhalb der SUBS-Data-Schleife, denn sie beziehen sich auf alle neuen Abos zugleich und nicht auf ein einzelnes. Sie stehen damit auch als einzige Tags dieser Seite außerhalb der Schleife zur Verfügung. Die Klammerung greift, solange mindestens ein Abo im Zustand “neu und aktiv” ist, also Code 1. Ein bereits angestoßenes Abo mit Code 2 zählt nicht mehr dazu.

Die Tags im Überblick

Tag	Einzel-Tag	Bereichs-Tag	negatives Bereichs-Tag	Schleifen-Tag
`SUBS-Data`	ja	ja	ja	ja
`SUBS-Data_Index`	ja	ja	ja	–
`SUBS-Data_SubShop()`	ja	ja	ja	–
`SUBS-Data_PR_Index`	ja	ja	ja	–
`SUBS-Data_PR_Number`	ja	ja	ja	–
`SUBS-Data_PR_Name`	ja	ja	ja	–
`SUBS-Data_PR_Price`	ja	ja	ja	–
`SUBS-Data_PR_CurrencyCode`	ja	ja	ja	–
`SUBS-Data_PR_Quantity`	ja	ja	ja	–
`SUBS-Data_PR_Quantity_input`	ja	ja	ja	–
`SUBS-Data_Cycle_count`	ja	ja	ja	–
`SUBS-Data_Cycle_unit_code`	ja	ja	ja	–
`SUBS-Data_Cycle_unit_isday`	ja	ja	ja	–
`SUBS-Data_Cycle_unit_isweek`	ja	ja	ja	–
`SUBS-Data_Cycle_unit_ismonth`	ja	ja	ja	–
`SUBS-Data_Cycle_unit_isyear`	ja	ja	ja	–
`SUBS-Data_created_unixtimestamp`	ja	ja	ja	–
`SUBS-Data_lastchange_unixtimestamp`	ja	ja	ja	–
`SUBS-Data_nextorder_unixtimestamp`	ja	ja	ja	–
`SUBS-Data_lastorder_unixtimestamp`	ja	ja	ja	–
`SUBS-Data_counter_orderedviasubscription`	ja	ja	ja	–
`SUBS-Data_state_code`	ja	–	–	–
`SUBS-Data_state_isactive`	ja	ja	ja	–
`SUBS-Data_state_isnew`	ja	ja	ja	–
`SUBS-Data_state_ispaused`	ja	ja	ja	–
`SUBS-Data_state_istriggered`	ja	ja	ja	–
`SUBS-Data_Buttonname`	ja	ja	ja	–
`SUBS-Data_Buttonvalue_delete`	ja	ja	ja	–
`SUBS-Data_Buttonvalue_pause`	ja	ja	ja	–
`SUBS-Data_Buttonvalue_resume`	ja	ja	ja	–
`SUBS-Data_affected`	ja	ja	ja	–
`SUBS-Data_affected_code`	ja	ja	ja	–
`SUBS-Data_affected_changed`	ja	ja	ja	–
`SUBS-Data_affected_paused`	ja	ja	ja	–
`SUBS-Data_affected_resumed`	ja	ja	ja	–
`SUBS-Data_PaymentCode()`	ja	ja	ja	–
`SUBS-Data_BankIndex()`	ja	ja	ja	–
`SUBS-Data_DelivAddress()`	ja	ja	ja	–
`SUBS-Buttonname`	ja	ja	ja	–
`SUBS-Buttonvalue_triggernewsubscriptions`	ja	ja	ja	–

Die Tabelle gibt die Tag-Maske des Shopsystems wieder. Mehrere Tags sind darin als Einzel-Tag zulässig, geben dort aber nichts aus. Das betrifft alle reinen Klammerungen, also die Einheiten, die Zustände und die Tags der Familie SUBS-Data_affected. Alle Tags außer SUBS-Buttonname und SUBS-Buttonvalue_triggernewsubscriptions gehören in die SUBS-Data-Schleife. Außerhalb sind sie ungültige Tags.

​Die Schleife über die Abos

​Das abonnierte Produkt

​Das Lieferintervall

​Das Intervall ändern lassen

​Zeitpunkte und Zähler

​Der Zustand des Abos

​Pausieren, fortsetzen und löschen

​Die Rückmeldung nach einer Aktion

​Zahlungsart, Bankverbindung und Lieferadresse je Abo

​Die Auswahl zum Ändern aufbauen

​Neue Abos anstoßen

​Die Tags im Überblick

​Verwandte Themen

Die Schleife über die Abos

Das abonnierte Produkt

Das Lieferintervall

Das Intervall ändern lassen

Zeitpunkte und Zähler

Der Zustand des Abos

Pausieren, fortsetzen und löschen

Die Rückmeldung nach einer Aktion

Zahlungsart, Bankverbindung und Lieferadresse je Abo

Die Auswahl zum Ändern aufbauen

Neue Abos anstoßen

Die Tags im Überblick

Verwandte Themen