Signup forms

A signup form collects email addresses, checks each one with a code, and puts every person into your audience. Put one on any page: Arc CMS handles joining, the emailed code, the confirmation, the contact and its lists, and the welcome email.

What it is

Each form is a document in Waitlists. Its members live under it, one document per address. A form can be used in two ways:

• Its own page at /waitlist/{form}, which Arc CMS renders from the form's settings.
• Your own markup on any page of your site: a plain HTML <form> marked with data-waitlist-form, which Arc CMS takes over when the page loads.

Every sign-up becomes a contact that joins the form's own list and any other lists the form feeds. From there, broadcasts and sequences reach them (Email marketing).

Turn it on or off

The feature id is forms. It is on by default and needs audience. To turn it off, add it to off in src/custom/features.ts:

export const CUSTOM_FEATURES: FeatureChoice = {
    off: ['forms'],
};

When it is off:

• The Signup Forms menu item and every form page (/waitlist, /leaderboard, /user/{form}/{member}, /admin/waitlists) are gone and show the not-found page.
• Form markup on your pages stays as you wrote it, but nothing reads, counts or submits it.
• The functions in functions/src/features/forms.ts are not built, so the next deploy of all functions removes them.
• The forms, members and templates stay in Firestore. Turn the feature back on to have them again.

See Feature ids and Choose your app's features.

Set it up

1. Set up email in Settings, Email Settings (see Email engine). Without a working provider no code can be sent, so every form confirms people without one.

2. Open Signup Forms and click the add button. Give it a name. The slug is filled in from the name and becomes the form's id, the {form} in every address above. Editing the slug later changes the slug only, never the id, and breaks links that used the old slug.

3. Creating the form also creates its list under Audience, Lists and its two email templates. Open the form's Email Templates to adjust them.

4. Link to /waitlist/{form}, or put the form on a page of your site (next section).

Put a form on a page

Every page of your site binds every form that has data-waitlist-form: the home page (src/custom/site/home.html and its translations, see Build your home page), content pages and list pages from your templates, and static pages. It works in the app and on the published page, where public/assets/js/arc-site.js runs the same steps through the same functions:

<form data-waitlist-form data-waitlist-id="beta">
  <input name="firstName" placeholder="Your name">
  <input type="email" name="email" required>
  <input name="company" placeholder="Company">
  <button type="submit">Join the beta</button>
</form>
<p><span data-waitlist-count="beta"></span> people have joined</p>

If no form has the given id, the first visit creates one with default settings. The code step, the confirmation and the error messages are drawn inside the form. To reword the confirmation, see Add signup forms to your site.

Use it

What happens on a sign-up

1. The visitor submits. The joinForm function finds or creates their member record on that form. Submitting the same address again returns the same record, never a second one.

2. The member record creates a pending contact, which joins the form's list and the lists it feeds, gets the form's default tag and its mapped answers.

3. requestFormOtp emails a 6-digit code. It is valid for 15 minutes, can be resent once a minute, and allows 5 wrong tries.

4. The visitor enters it. verifyFormOtp checks it and finalizeFormSignup confirms the member and counts them in the form's totalSignups.

5. The contact becomes subscribed, the waitlist.joined event fires (see Automations), and the welcome email goes out.

6. The form shows a tick, "You're on the list!" and the address. Someone who was already on the list sees "You're already on the list." instead.

The code step is skipped, and the member confirmed at once, when email is not set up, when the Waitlist emails switch in Settings, Email Settings is off, or when the form's verification template is inactive. Such a member is confirmed but not verified.

Form settings

Edit a form from its row or its dashboard (Settings):

Emails

Each form has its own two templates, on its Email Templates page (/admin/waitlists/templates/{form}):

A form's welcome can instead be the first step of a sequence on its list: the migrateWelcomeToSequences admin callable moves every form's welcome there and marks the form, after which the sequence sends it and the template is not sent directly (see Email marketing).

To turn a form's code step off, make its verification template inactive. For more emails after the welcome, add a sequence on the form's list (Email marketing). Every tag is listed in Email merge tags.

Upgrading from referrals and the leaderboard

Older versions gave every member a referral code and link, a queue position and a public leaderboard. Signup forms have none of these now. After updating an install that used them:

1. Deploy the website first, then all the functions, then the rules. The old form page reads members through a function this version deletes, while the new pages work with the old functions. A deploy of all the functions deletes the referral and leaderboard functions; a targeted deploy never deletes one (see Functions that are deleted).

2. Run npm run forms:remove-referrals to count the old referral records, then npm run forms:remove-referrals -- --apply to delete them. Each one holds the address of the person referred, and nothing else removes it when that person is deleted.

3. Check each form's welcome email for referral or leaderboard buttons you added yourself.

The old fields on member records (referralCode, referralLink, leaderboardLink, queuePosition, totalReferrals, referredBy) stay where they are and are not read any more. Old ?ref= links open the page as usual.

Members

View Users on a form lists its members, with notes and the form's own tags. Each form's dashboard shows sign-up numbers, traffic sources, devices and recent sign-ups, and exports the members.

• Deleting a member takes the contact off the form's own list. The contact itself stays, and so do the other lists the form fed.
• Deleting a form deletes all its members and their notes, takes every contact off the form's list and deletes that list.
• To remove a person everywhere, erase the contact (see Audience): that deletes their member records too.

Extend it

Any page that renders your own HTML can collect sign-ups by linking to /waitlist/{form}. To react to a sign-up in code or without code, listen for the waitlist.joined event with an automation rule (Automations), or add a sequence on the form's list.

The public functions are callable from any client, but prefer the built-in page and markup: they already call joinForm, requestFormOtp, verifyFormOtp and finalizeFormSignup in the right order. Calling them from a client uses the prefixed name, such as arccms-joinForm.

What it stores

Every collection is also in Data model. The contacts and the form's list belong to Audience. The cover image is picked from the Media library.

Cloud Functions (each deploys as arccms- followed by its name):

See Cloud Functions for the full list.

Who can do what

Verification, confirmation and the signup count are worked out by Cloud Functions. The admin callables refuse anyone without the admin role (Roles and claims).

Troubleshooting