JavaScript API
Send submissions from your own code, watch widgets that aren't forms, and tell the script what to leave alone.
Formcrier.send()
The script adds a Formcrier object to the page. Formcrier.send() sends a submission you've put together yourself, from a React app or a custom widget.
form is the reference the form is known by, and name is what it's called in your dashboard. fields holds the answers.
The form appears under Sites → Forms the first time you send to it, switched off like any other. Switch it on to get its alerts. Passwords, card numbers and tokens are removed as usual.
send() returns true when the script has taken the submission. It isn't a delivery receipt.
Formcrier.send({
form: 'quote-request',
name: 'Quote request',
fields: { name: 'Sarah Jones', phone: '07700 900123' }
});
Fields with labels
fields can also be a list, which lets you give each field a label. Without one, we make a label from the name.
A value can be text, a number, a list, or true or false, which is sent as Yes or No. Empty values are left out.
Formcrier.send({
form: 'quote-request',
fields: [
{ name: 'service', label: 'Service needed', value: 'New boiler' },
{ name: 'extras', label: 'Extras', value: ['Thermostat', 'System flush'] }
]
});
Formcrier.watch()
watch() treats an element that isn't a <form> as one. Pass a selector or an element, with the form's reference and name. When a button inside it is clicked, the script reads the fields inside and sends them.
Unlike send(), a watched element follows its switch under Sites → Forms. On a real <form>, watch() only sets the reference and name.
Formcrier.watch('#newsletter', { form: 'newsletter', name: 'Newsletter' });
Formcrier.ignore()
ignore() tells the script to leave a form or a field alone. It's never sent and never listed. A selector also covers matching elements that are added later.
Formcrier.ignore('.login-form');
data-formcrier-ignore
The same can be done in HTML. data-formcrier-ignore on a form, a field or any element around them does what ignore() does. data-formcrier-form and data-formcrier-name set a form's reference and name.
<form data-formcrier-form="quote" data-formcrier-name="Quote request"> <input name="internal-note" data-formcrier-ignore> </form> <form data-formcrier-ignore>…</form>
Waiting for the script
The script loads with async, so Formcrier may not exist yet when your code runs. It fires a formcrier:ready event on window once it's there.
function setUp() {
Formcrier.watch('#newsletter', { form: 'newsletter', name: 'Newsletter' });
}
if (window.Formcrier && Formcrier.watch) setUp();
else window.addEventListener('formcrier:ready', setUp);
Queueing calls
You can also queue calls before the script loads. Put this above the Formcrier tag: each entry is a method name followed by its arguments, and the script runs them when it loads.
Formcrier.version holds the script's version. If the tag has no data-key, the script does nothing and Formcrier isn't defined.
<script>
window.Formcrier = { q: [
['send', { form: 'quote-request', fields: { name: 'Sarah Jones' } }]
] };
</script>