← 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:
- The visitor enters their e-mail (optionally a note and, with
oo-subscribe-extra, title and name) and submits — a confirmation mail is sent. - The link in that mail leads back to this page with a
oo-subscribetoken; the component confirms the subscription. - Unsubscribe links in newsletters lead here with a
oo-unsubscribetoken; 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:
- On start it asks the shop whether a captcha is wanted. If not, nothing is shown and nothing extra is loaded.
- If yes, it loads the widget (about 40 KB gzipped, only then) and inserts an "I'm not a robot" checkbox
in a
<div class="oo-altcha">directly in front of the send button#oo-subscribe-btn. - Solving starts when the visitor first focuses the form; the visitor does not need to click the checkbox. The send waits for the solution (usually well under a second).
- A solution is valid once: after every send, successful or not, the widget gets a new puzzle.
- If the shop rejects the form for the captcha, the flash shows the shop's text
boss.subscribe.captcha.
What you have to take care of on your page:
- HTTPS. The widget needs a secure context (WebCrypto). On a plain-HTTP page it can not solve, and with the captcha switched on every subscription is rejected.
- Content-Security-Policy. If your page sends one, the widget's worker is started from a
data:URL — allow it withworker-src data:(or ascript-srcthat permitsdata:). - Own template. Keep the button id
#oo-subscribe-btninside.oo-subscribe-subscribe; the widget is placed in front of that button. Without it the widget has no place and the form can not be sent. - Styling. The widget has no shadow DOM, so your form CSS reaches it. Adjust it with the
widget's CSS variables on
.oo-altcha(e.g.--altcha-max-width,--altcha-border-radius,--altcha-color-base,--altcha-color-primary,--altcha-checkbox-size), see the ALTCHA widget (version 3.5.0). - The widget speaks the page's shop language (de, en, es, fr, sl).
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. |