← API Index · How to use components

subscribe component #oo-subscribe

This component implements a double opt-in subscription to the shop's newsletter (or waiting list) and the unsubscription:

  1. The visitor enters their e-mail (optionally a note and, with oo-subscribe-extra, title and name) and submits — a confirmation mail is sent.
  2. The link in that mail leads back to this page with a oo-subscribe token; the component confirms the subscription.
  3. Unsubscribe links in newsletters lead here with a oo-unsubscribe token; the component performs the unsubscription.

The backend settings define the pages these links point to, so host this component on exactly those pages. Other components (profile, status) link to the subscription page configured in the backend or, as fallback, to the oo-subscribe-page switch.

How components are mounted, how switch values are resolved and how debug output is enabled is described in the use-js-components skill.

<div id="oo-flash"></div>
<h1>Get our newsletter!</h1>
<div id="oo-subscribe" data-oo-subscribe-ag="12"></div>

component switches

Switch Default Description
oo-subscribe-ag 0 Id of an action group the new subscriber is assigned to after a successful subscription (see the actiongroups skill).
oo-subscribe-extra false true shows the extra fields (title, first name, last name) in the subscription form.
oo-subscribe-nosubscribe true false hides the subscription form; the page then only handles confirmation and unsubscription links.

Page parameters

Parameter Description
?oo-subscribe=<token> Confirms a subscription (link from the confirmation mail).
?oo-unsubscribe=<token> Unsubscribes (link from a newsletter).

States

Element Shown when
.oo-subscribe-subscribe The subscription form (initial state).
.oo-subscribe-done Confirmation mail was sent.
.oo-subscribe-checking A token is being verified.
.oo-subscribe-confirmed Subscription confirmed.
.oo-subscribe-already The address was already subscribed.
.oo-subscribe-unsubreq / .oo-subscribe-unsubreq-no Unsubscription requested / declined.
.oo-subscribe-unsubscribed Unsubscription done.

Errors (e.g. an address that declined mails earlier) are shown through the flash component — host one on the page. You may create a popup version by wrapping this component's page in a page of its own.

Spam protection (captcha)

Shops can protect the subscription with an ALTCHA proof-of-work captcha (shop setting "Spam-Schutz (ALTCHA)", group Mail, on by default). The component handles it completely — there is nothing to switch on in the page:

What you have to take care of on your page:

Building your own subscription form without this component? The flow (challenge, solve, parameter altcha) is described in the use-altcha-captcha skill.

debug options

Debug scope subscribe (enable with data-oo-debug="true" on the element or debug:subscribe:all+, see the skill):

Term Description
subscribe:all Resolved switches, detected state (form / confirmation / unsubscribe) and API results.