SUBS- (Abo abschließen) - WEBSALE Dokumentation

Ein Abo entsteht auf der Produktseite. Der Käufer wählt dort nicht nur die Menge, sondern zusätzlich ein Lieferintervall, und je nach Einstellung auch die Zahlungsart, eine Bankverbindung und eine Lieferadresse, die dauerhaft für dieses Abo gelten. Diese Seite beschreibt die Tags für genau diesen Schritt. Die Verwaltung bereits bestehender Abos steht auf einer eigenen Seite.

Wegweiser: Abo-Modul
Referenz: SUBS- (Abos verwalten)

Die Abo-Funktion wird im Abschnitt Subscription der Shopkonfiguration freigeschaltet. Dort stehen auch die wählbaren Lieferintervalle und die zulässigen Zahlungsarten.

Darf dieses Produkt abonniert werden

SUBS-CycleSelection ist die Klammerung um den gesamten Abo-Bereich. Sie greift, wenn das Produkt abonnierbar ist.

{SUBS-CycleSelection}
   <fieldset>
      <legend>Als Abo bestellen</legend>
      ...
   </fieldset>
{/SUBS-CycleSelection}

Setzen Sie den gesamten Abo-Teil des Produkttemplates in diese Klammerung. Ohne sie erscheinen die Eingabefelder auch bei Produkten, die gar nicht abonniert werden können.

Die Zyklusauswahl

Die wählbaren Lieferintervalle sind im Shop konfiguriert, nicht am Produkt. SUBS-CycleSelection_data läuft als Schleife über sie und liefert als Einzel-Tag ihre Anzahl.

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

Tag	Liefert
`SUBS-CycleSelection_input`	den HTML-Namen des Auswahlfelds
`SUBS-CycleSelection_data`	die Schleife über die Intervalle, als Einzel-Tag deren Anzahl
`SUBS-CycleSelection_data_value`	den Wert des Eintrags für das `value`-Attribut
`SUBS-CycleSelection_data_descr`	die Beschriftung des Eintrags
`SUBS-CycleSelection_data_selected`	das Wort `selected`, wenn dieser Eintrag der gewählte ist
`SUBS-CycleSelection_data_count`	die Anzahl der Einheiten, beispielsweise die 3 in “alle 3 Monate”
`SUBS-CycleSelection_data_unit_code`	den technischen Code der Einheit

SUBS-CycleSelection_data_value liefert nicht die Anzahl, sondern die Kombination aus Einheit und Anzahl in der Form Einheit-Anzahl. Ein Intervall von drei Monaten ergibt also 1-3. Dieser Wert gehört unverändert in das value-Attribut, denn das Shopsystem erkennt die Auswahl daran wieder.

Die Beschriftung aus SUBS-CycleSelection_data_descr stammt aus dem Parameter Description des jeweiligen Intervalls in der Shopkonfiguration. Ist dort nichts hinterlegt, gibt das Tag nichts aus und greift auch als Klammerung nicht. Bauen Sie die Beschriftung in diesem Fall aus _data_count und den Einheiten-Klammerungen selbst zusammen. SUBS-CycleSelection_data_selected gibt als Einzel-Tag ein führendes Leerzeichen gefolgt von selected aus. Sie können es deshalb direkt hinter das letzte Attribut schreiben, ohne selbst ein Trennzeichen zu setzen.

Die Einheit des Intervalls

Vier Klammerungen beantworten, um welche Einheit es geht. Der technische Code dahinter steht in SUBS-CycleSelection_data_unit_code.

Tag	Greift bei	Code
`SUBS-CycleSelection_data_unit_isday`	Tag	0
`SUBS-CycleSelection_data_unit_ismonth`	Monat	1
`SUBS-CycleSelection_data_unit_isyear`	Jahr	2
`SUBS-CycleSelection_data_unit_isweek`	Woche	3

{@SUBS-CycleSelection_data}
   <option value="~SUBS-CycleSelection_data_value~" ~SUBS-CycleSelection_data_selected~>
      alle ~SUBS-CycleSelection_data_count~
      {SUBS-CycleSelection_data_unit_isday}Tage{/SUBS-CycleSelection_data_unit_isday}
      {SUBS-CycleSelection_data_unit_isweek}Wochen{/SUBS-CycleSelection_data_unit_isweek}
      {SUBS-CycleSelection_data_unit_ismonth}Monate{/SUBS-CycleSelection_data_unit_ismonth}
      {SUBS-CycleSelection_data_unit_isyear}Jahre{/SUBS-CycleSelection_data_unit_isyear}
   </option>
{/@SUBS-CycleSelection_data}

Die Reihenfolge der Codes folgt nicht der Länge der Zeiträume. Die Woche hat den Code 3 und steht damit hinter dem Jahr. Werten Sie _unit_code deshalb nie mit einem Größenvergleich aus, sondern nehmen Sie die vier Klammerungen.

Die vier Einheiten-Tags sind laut Tag-Maske auch als Einzel-Tag zulässig. Sie geben dort jedoch nichts aus. Verwenden Sie sie ausschließlich als Klammerung.

Einen Eintrag gezielt ansprechen

Alle _data_-Tags nehmen wahlweise einen Parameter entgegen, nämlich die laufende Nummer des Intervalls. Damit greifen Sie außerhalb der Schleife auf einen bestimmten Eintrag zu.

Standardintervall: ~SUBS-CycleSelection_data_descr(1)~

SUBS-CycleSelection_data_selected ohne Parameter und außerhalb der Schleife hat eine eigene Bedeutung. Dort greift es als Klammerung, wenn der Käufer überhaupt schon ein Intervall gewählt hat. Das eignet sich für den Hinweis, dass die Auswahl noch aussteht.

Eine Nummer außerhalb des konfigurierten Bereichs macht das Tag ungültig. Das gilt auch innerhalb der Schleife, wenn Sie dort zusätzlich einen Parameter setzen.

Ist das Produkt schon im Abo

Bevor Sie den Abo-Bereich anbieten, lohnt der Blick in die bestehenden Abos des Käufers. Zwei Klammerungen beantworten das, die eine über den Produktindex, die andere über die Produktnummer.

{SUBS-ProdNumberOnSubscription(~PR-Number~)}
   <p>Dieses Produkt haben Sie bereits abonniert.</p>
{/SUBS-ProdNumberOnSubscription(~PR-Number~)}

{!SUBS-ProdNumberOnSubscription(~PR-Number~)}
   {SUBS-CycleSelection}
      ...
   {/SUBS-CycleSelection}
{/!SUBS-ProdNumberOnSubscription(~PR-Number~)}

Beide Tags brauchen ihren Parameter. Ohne Parameter greifen sie nie, auch die negative Klammerung nicht. Ein Fehler wird dabei nicht gemeldet, der Bereich bleibt einfach stumm.

Die Suche läuft über alle Abos des angemeldeten Käufers, unabhängig von deren Zustand. Ein pausiertes Abo gilt also ebenfalls als vorhanden.

Die Zahlungsart für das Abo

Ein Abo wird immer wieder abgerechnet und verträgt deshalb nicht jede Zahlungsart. Welche zulässig sind, steht im Parameter AllowedPayments im Abschnitt Subscription der Shopkonfiguration.

Tag	Liefert
`SUBS-AllowedPayments`	die Schleife über die zulässigen Zahlungsarten, im Durchlauf den Zahlungsartencode
`SUBS-PaymentMethod_input`	den HTML-Namen des Auswahlfelds
`SUBS-PaymentMethod_selected()`	Klammerung: dieser Zahlungsartencode ist gewählt
`SUBS-FixedPaymentCodeUsed()`	die fest eingestellte Zahlungsart, mit Parameter ein Vergleich darauf

{SUBS-AllowedPayments}
   <select name="~SUBS-PaymentMethod_input~">
      {@SUBS-AllowedPayments}
         <option value="~SUBS-AllowedPayments~"
                 {SUBS-PaymentMethod_selected($SUBS-AllowedPayments$)}selected{/SUBS-PaymentMethod_selected($SUBS-AllowedPayments$)}>
            {PAY-IsDebit(~SUBS-AllowedPayments~)}Lastschrift{/PAY-IsDebit(~SUBS-AllowedPayments~)}
            ...
         </option>
      {/@SUBS-AllowedPayments}
   </select>
{/SUBS-AllowedPayments}

Ohne sie lässt sich eine Auswahl der Zahlungsart nicht aufbauen. Als Zahlungsart lässt das Shopsystem im Abo ausschließlich Lastschrift, Rechnung, PayPal Checkout und PayPal Checkout auf Rechnung zu. Ein anderer Code in AllowedPayments wird beim Einlesen der Konfiguration verworfen und protokolliert.

SUBS-PaymentMethod_selected() vergleicht den Parameter mit der zuletzt abgeschickten Auswahl, nicht mit einer am Abo gespeicherten Zahlungsart. Beim ersten Aufruf der Produktseite ist noch nichts gewählt, und das Tag greift ohne Parameter als Klammerung dann, wenn überhaupt eine Auswahl vorliegt.

Der Parameter UsePaymentCode ist der Vorläufer von AllowedPayments und sollte nicht mehr verwendet werden. Ist er gesetzt und AllowedPayments nicht, wird daraus eine Liste mit genau einem Eintrag. SUBS-FixedPaymentCodeUsed gibt diesen Code als Einzel-Tag aus und greift als Klammerung, solange er gesetzt ist. Referenz: PAY- (Zahlungsarten)

Die Bankverbindung

Bei Lastschrift braucht das Abo eine Bankverbindung. Vier Tags bilden das ab, und sie bauen aufeinander auf.

Tag	Bedeutung
`SUBS-BankSelection`	Klammerung: eine Bankverbindung kann gewählt werden
`SUBS-BankData`	Klammerung: zum Abo ist bereits eine Bankverbindung hinterlegt
`SUBS-BankIndex`	die Kennung der hinterlegten Bankverbindung
`SUBS-BankIndex_input`	den HTML-Namen des Auswahlfelds

{SUBS-BankSelection}
   <select name="~SUBS-BankIndex_input~">
      {@BANK-Data}
         <option value="~BANK-Index~" {SUBS-BankIndex_selected($BANK-Index$)}selected{/SUBS-BankIndex_selected($BANK-Index$)}>
            ~BANK-IBAN~
         </option>
      {/@BANK-Data}
   </select>
{/SUBS-BankSelection}

SUBS-BankSelection greift nur, wenn drei Bedingungen zugleich erfüllt sind: ein Käufer ist angemeldet, die fest eingestellte Zahlungsart ist Lastschrift, und der Shop arbeitet nicht mit PayPal Checkout SEPA. Trifft eine davon nicht zu, bleibt der Bereich leer.Das Tag lädt beim ersten Auswerten die Bankverbindungen des Käufers aus der Datenbank. Setzen Sie es deshalb einmal als Klammerung um den gesamten Bankbereich und werten Sie darin aus, statt es mehrfach im Template zu verteilen.

SUBS-BankData lädt ebenfalls aus der Datenbank, und zwar die eine am Abo hinterlegte Verbindung. Es beantwortet die Frage “gibt es schon eine”, während SUBS-BankSelection die Frage “darf überhaupt eine gewählt werden” beantwortet. Es vergleicht seinen Parameter mit der zuletzt abgeschickten Auswahl und greift ohne Parameter dann, wenn überhaupt eine Auswahl vorliegt.

SUBS-BankIndex_input verhält sich auf der Abo-Seite anders als sonst. Ist dort genau eine Zahlungsart zulässig und diese Lastschrift, liefert es den Namen ws_subscription_debitindex und greift zusätzlich als Klammerung, nämlich dann, wenn eine Bankverbindung überhaupt gewählt werden darf. In allen anderen Fällen ist es ein reines Einzel-Tag mit dem Namen ws_subscription_bank. Diese Doppelbelegung ist im Shopsystem als Altlast vermerkt.

Die Lieferadresse

Soll das Abo an eine andere Adresse gehen als die Rechnungsadresse, wählt der Käufer sie aus seinem Adressbuch.

Tag	Liefert
`SUBS-DelivAddress_input`	den HTML-Namen des Auswahlfelds
`SUBS-DelivAddress_selected()`	Klammerung: dieser Adressindex ist gewählt

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

Der Wert 0 bedeutet “keine abweichende Lieferadresse”, das Abo geht also an die Rechnungsadresse. Jeder Wert darüber ist der Index eines Adressbucheintrags, derselbe, den auch D-DeliverySelection_value liefert. Referenz: D- (Lieferadresse)

Die HTML-Namen der Eingabefelder

Alle _input-Tags liefern feste Namen. Auf der Produktseite sind es diese:

Tag	HTML-Name
`SUBS-CycleSelection_input`	`ws_subscription_cycle`
`SUBS-PaymentMethod_input`	`ws_subscription_payment`
`SUBS-BankIndex_input`	`ws_subscription_bank` oder `ws_subscription_debitindex`
`SUBS-DelivAddress_input`	`ws_subscription_deliv`

Verwenden Sie trotzdem die Tags und nicht die Namen selbst. Innerhalb der Schleife über bestehende Abos liefern dieselben Tags einen anderen Namen, nämlich denselben mit angehängter Abo-Kennung. Das Template arbeitet dadurch in beiden Zusammenhängen.

Die Tags im Überblick

Tag	Einzel-Tag	Bereichs-Tag	negatives Bereichs-Tag	Schleifen-Tag
`SUBS-CycleSelection`	–	ja	ja	–
`SUBS-CycleSelection_input`	ja	–	–	–
`SUBS-CycleSelection_data`	ja	ja	ja	ja
`SUBS-CycleSelection_data_selected`	ja	ja	ja	–
`SUBS-CycleSelection_data_descr`	ja	ja	ja	–
`SUBS-CycleSelection_data_value`	ja	–	–	–
`SUBS-CycleSelection_data_count`	ja	–	–	–
`SUBS-CycleSelection_data_unit_code`	ja	–	–	–
`SUBS-CycleSelection_data_unit_isday`	ja	ja	ja	–
`SUBS-CycleSelection_data_unit_isweek`	ja	ja	ja	–
`SUBS-CycleSelection_data_unit_ismonth`	ja	ja	ja	–
`SUBS-CycleSelection_data_unit_isyear`	ja	ja	ja	–
`SUBS-ProdIndexOnSubscription()`	ja	ja	ja	–
`SUBS-ProdNumberOnSubscription()`	ja	ja	ja	–
`SUBS-AllowedPayments`	ja	ja	ja	ja
`SUBS-PaymentMethod_input`	ja	–	–	–
`SUBS-PaymentMethod_selected()`	–	ja	ja	–
`SUBS-FixedPaymentCodeUsed()`	ja	ja	ja	–
`SUBS-BankSelection`	ja	ja	ja	–
`SUBS-BankData`	–	ja	ja	–
`SUBS-BankIndex`	ja	ja	ja	–
`SUBS-BankIndex_input`	ja	ja	ja	–
`SUBS-BankIndex_selected()`	–	ja	ja	–
`SUBS-DelivAddress_input`	ja	–	–	–
`SUBS-DelivAddress_selected()`	–	ja	ja	–

Mehrere Tags sind laut Tag-Maske als Einzel-Tag zulässig, geben dort aber nichts aus. Das betrifft die vier Einheiten-Klammerungen, SUBS-ProdIndexOnSubscription() und SUBS-ProdNumberOnSubscription(). Die Tabelle gibt die Maske des Shopsystems wieder.

SUBS-BankIndex_input ist im Shopsystem zweimal in der Tag-Tabelle eingetragen. Wirksam ist nur der erste Eintrag, der zweite wird nie erreicht. Für Templates ändert sich dadurch nichts, das Verhalten bleibt wie oben beschrieben.

​Darf dieses Produkt abonniert werden

​Die Zyklusauswahl

​Die Einheit des Intervalls

​Einen Eintrag gezielt ansprechen

​Ist das Produkt schon im Abo

​Die Zahlungsart für das Abo

​Die Bankverbindung

​Die Lieferadresse

​Die HTML-Namen der Eingabefelder

​Die Tags im Überblick

​Verwandte Themen

Darf dieses Produkt abonniert werden

Die Zyklusauswahl

Die Einheit des Intervalls

Einen Eintrag gezielt ansprechen

Ist das Produkt schon im Abo

Die Zahlungsart für das Abo

Die Bankverbindung

Die Lieferadresse

Die HTML-Namen der Eingabefelder

Die Tags im Überblick

Verwandte Themen