FormKeep.js
This library offers a few methods to make it easier to add interactivity to FormKeep forms, so you can show success messages, dynamically change the redirect URLs, post the form through AJAX and handle the response on your side or even post JSON data to FormKeep from JavaScript. If you just want to configure a redirect url or the default "Thanks" page, regardless of the input check the docs.
Installation
With a bundler
-
npm install @formkeep/formkeep
, or yarn add @formkeep/formkeep
- Then use in your code with:
const FormKeep = require('@formkeep/formkeep')
Without a bundler
- Add to your HTML header:
<!-- For library use: --> <script src="unpkg.com/@formkeep/formkeep"></script> <!-- For autoload use: --> <script src="unpkg.com/@formkeep/formkeep/autoload"></script>
- Use the
FormKeep
global variable:FormKeep.post('<YOUR_FORM_IDENTIFIER>', { hello: 'world' })
Contents
Guide
Samples
Show a success message
- Load the autoload script
- Add a
<form>
withdata-formkeep-id="<YOUR_FORM_IDENTIFIER>"
- Give the
<form>
or any other element anid="<SOME_UNIQUE_ID>"
- Add a
<template>
withdata-formkeep-success-template=<YOUR_FORM_IDENTIFIER>
anddata-target="#<SOME_UNIQUE_ID>"
(notice the#
) - When the form is successfully submitted, the element with the unique id will be replaced by the contents of the template.
Example
<!-- On your page -->
<div id="example-success-notice"></div>
<form data-formkeep-id="<YOUR_FORM_IDENTIFIER>">
<input type="hidden" name="utf8" value="✓" />
<input name="name" value="John Dowd" />
<input name="email" value="test@example.com" />
<button type="submit">Submit</button>
</form>
<template
data-formkeep-success-template="<YOUR_FORM_IDENTIFIER>"
data-target="#example-success-notice"
>
<div>
Your form was successfully posted! We'll get back to you!
</div>
</template>
Redirect to a page depending on input
- Load the script
- Add a regular FormKeep form
- Use the
redirectForm
function on your form - Pass a
setRedirectUrl
function and return a URL (the form's data is passed to this function for convenience) - The
setRedirectUrl
callback will be called after the user clicks submit (but before posting to FormKeep) so you can use their input to set the redirect URL.
Example
<!-- On your page -->
<form
id="test-form"
action="https://formkeep.com/f/<YOUR_FORM_IDENTIFIER>"
method="POST"
>
<div>
<input type="radio" name="site" value="google" checked>
<label for="site">Take me to Google</label>
</div>
<div>
<input type="radio" name="site" value="apple">
<label for="site">Take me to Apple</label>
</div>
<button type="submit">Submit</button>
</form>
// On your script
document.addEventListener('DOMContentLoaded', function() {
var form = document.getElementById('test-form')
FormKeep.redirectForm(form, {
setRedirectUrl: function(formJson) {
if (formJson.site === 'google') {
return 'https://google.com'
}
if (formJson.site === 'apple') {
return 'https://apple.com'
}
}
})
})
Thanks page depending on input
Customize the- Load the script
- Add a regular FormKeep form
- Use the
thanksForm
function on your form - Pass a
setHeading
and asetSubheading
function and return a string from each (the form's data is passed to this function for convenience) - The
setHeading
andsetSubheading
callbacks will be called after the user clicks submit (but before posting to FormKeep) so you can use their input to set up the "Thanks" page.
Example
<!-- On your page -->
<form
id="test-form"
action="https://formkeep.com/f/<YOUR_FORM_IDENTIFIER>"
method="POST"
>
<input name="name" value="John Doe" />
<input name="email" value="test@example.com" />
<button type="submit">Submit</button>
</form>
// On your script
document.addEventListener('DOMContentLoaded', function() {
var form = document.getElementById('test-form')
FormKeep.thanksForm(form, {
setHeading: function(formJson) {
return "Thanks, " + formJson.name + "!"
},
setSubheading: function(formJson) {
return "We will contact you at " + formJson.email + " soon"
}
})
})
Submit the form through AJAX
- Install formkeep.js
- Add the desired form in your HTML
- Use the
asyncForm
function on your form with your FormKeep identifier - Use the
beforeSubmit
hook to do something before the form is posted (this function is passed the form's data as an object)
- Return
false
to prevent the submission - Return the
data
object to submit it (you can modify it)
- Use the
onSuccess
callback to do something after the form is successfully posted - Use the
onFailure
callback to do something if the form fails to post
Note you can also leave out the onSuccess
and onFailure
callbacks and asyncForm
will return a Promise
instead.
Example
<!-- On your page -->
<form id="example-form">
<input type="hidden" name="utf8" value="✓" />
<input type="text" name="name" value="Barney" />
<input type="email" name="email" value="awesome@legendary.com" />
</form>
// On your script
const FormKeep = require('formkeep') // or window.FormKeep
document.addEventListener('DOMContentLoaded', () => {
const form = document.getElementById('example-form')
FormKeep.asyncForm(form, '<YOUR_FORM_IDENTIFIER>', {
beforeSubmit: (formJson) => {
if (!formJson.email.includes('@')) {
return false
}
formJson.publisher = 'ACME'
return formJson
},
onSuccess: () => {
window.alert('Successfully posted!')
},
onFailure: () => {
window.alert('There was an error posting your form!')
}
})
})
Post JSON data to FormKeep
- Install formkeep.js
- Use the
post
function - Either pass a config object with
onSuccess
andonFailure
or omit those andpost
will return aPromise
Example
const { post } = require('formkeep')
post('<YOUR_FORM_IDENTIFIER>', { name: 'Barney', email: 'awesome@legendary.com' })
.then(() => {
window.alert('Successfully posted!')
})
.catch(() => {
window.alert('There was an error posting your form!')
})
API
post
post(formkeepIdentifier: string, formJson: Object, options: Object | null): true | Promise
You can use it to easily post JSON data to a FormKeep form. You can omit the onSuccess and onFailure callbacks and a Promise will be returned instead.
-
formkeepIdentifier
: your form's unique identifier (you can find it in your FormKeep dashboard) -
formJson
: a JSON object with the data you want to post -
options
:-
onSuccess [optional]
a function to call when the data is successfully posted to FormKeep. -
onFailure [optional]
a function to call if posting the form fails
-
asyncForm
asyncForm(form: HTMLFormElement, formkeepIdentifier: string, options: Object | null): true | Promise
You can use this to make any form post to FormKeep using AJAX, so you can handle what to do afterwards. You can omit the onSuccess and onFailure callbacks and a Promise will be returned instead.
-
form
: the form element you want to post through AJAX. -
formkeepIdentifier
: the id of the form to post. -
options
:-
beforeSubmit
: a function to call before the form is posted, in here you can do validations or show a loading indicator. Returningfalse
from this function will halt the submission. It receives the form's data as a json object, and should return a json object with the data to be posted (this allows for modifying this data dynamically) -
onSuccess
: a function to call when the data is successfully posted to FormKeep. -
onFailure
: a function to call if posting the form fails
-
thanksForm
thanksForm(form: HTMLFormElement, config: Object)
You can use this to dynamically add thanks params to the FormKeep thanks page
-
form
: the form element you want to modify (it should be set up to post to formkeep). -
options
:-
setHeading(formJson: Object)
: a function that sets the heading for the thank you page. It is passed the form's data as a JSON object for convenience. -
setSubheading(formJson: Object)
: a function that sets the subheading for the thank you page. It is also passed the form's data as a JSON object.
-
redirectForm
redirectForm(form: HTMLFormElement, config: Object)
You can use this to dynamically add thanks params to the FormKeep thanks page
-
form
: the form element you want to modify (it should be set up to post to formkeep). -
options
:-
setRedirectUrl(formJson: Object)
: a function that sets the redirect URL when the form is submitted. It is passed the form's data as a JSON object for convenience.
-
Contributing
Please submit a PR if you have an improvement!
Setup
To set up the dependencies:
- Install yarn
- Run
yarn install
Testing
Unit tests are run with Jest, which automatically uses the .babelrc
to apply es6 transforms.
To run the unit tests:
yarn test
Build
The build is run with Parcel, which uses @babel/env
by default, so our .babelrc
mimics that.
To run the build:
yarn build