@goldencomm/strapi-plugin-gcforms
v2.1.4
Published
Accept form submissions on your Strapi app.
Downloads
24
Readme
GC Forms
This plugin only supports Strapi v4
Easily integrate form submissions from your front end to your Strapi site. Automatically prevent spam, send out email notifications, and store submission data in your database.
Getting Started
Installation
npm install @goldencomm/strapi-plugin-gcforms
or
yarn add @goldencomm/strapi-plugin-gcforms
Configuration
In the Strapi project's config/plugins.js
file, add a configuration.
{
gcforms: {
}
}
With the plugin installed, you can set up your first Form in the admin.
Currently the "Form" content type's only purpose is to determine which "Form Email" should be sent when a new "Form Submission" is created. The plan is to eventually create a custom admin where editors can have a form builder experience. See the Roadmap section for more planned features.
See the available configuration options below.
| Property | Type | Description |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| config
| Object | |
| config.captcha
| Object | |
| config.captcha.provider
| String | Name of the Captcha provider. |
| config.captcha.config
| Object | A configuration object specific to the Captcha provider. See below for Google Recaptcha config options. |
| config.settings
| Object | |
| config.settings.sendEmail
| Boolean | Whether to send emails on form submission. Default true
. |
API Token Set-Up
In the Strapi API Token settings, set up your API token to have the permissions your app will require.
At a minimum you will need find
and findOne
for forms, notifications, and submissions, and create
for submissions.
Submitting a Form
To create a new submission, send a POST
request to /api/gcforms/form-submissions
on your Strapi site. The body can be a JSON object, or FormData.
The form
field in the submitted JSON or FormData must be set equal to the associated form's slug. See below for an example.
Using FormData
If your form requires file submissions, you must use FormData.
let formData = new FormData();
formData.set("form", "contact-us");
formData.set("firstName", "Bob");
formData.set("lastName", "Belcher");
fetch("/api/gcforms/form-submissions", {
method: "POST",
body: formData,
});
Using JSON
fetch("/api/gcforms/form-submissions", {
method: "POST",
body: JSON.stringify({
form: "contact-us",
firstName: "Bob",
lastName: "Belcher",
}),
});
Emails
In order to send autoresponder emails, you will need an Email Provider. If the form associated with a new submission also has associated emails, those emails will be sent out through the configured email provider.
To turn off the autoresponder functionality entirely, set config.settings.sendEmail
to false.
All the Form Email fields use Liquid templating with the submitted data. For example, if the submitted data contains a lastName
field (like the example submissions above), then you could use {{lastName}}
in any of the Form Email fields where you want that data displayed when the email is sent.
When a submission is created, by default, an email will be sent. Pass the query parameter ?notify=false
to prevent an email.
When a submission is updated with PUT or PATCH, an email will not be sent by default. Pass the query parameter ?notify=true
to send emails.
Captcha
Configure a Captcha Provider to prevent spam.
Google Recaptcha is currently the only supported provider, but you can create your own provider if needed.
A Custom Provider
Here is a basic example of what a custom Captcha Provider might look like. Refer to the Google Recaptcha provider included in this plugin for another example.
module.exports = {
init(providerConfig) {
// Do any initialization work if needed.
return {
async validate(formData) {
// Validate the recaptcha token in the form data.
// On error return an object like this:
// return {
// valid: false,
// message: 'An error message detailing what went wrong.',
// code: 400 // or 500
// }
// On success return an object like this:
return {
valid: true,
};
},
};
},
};
Google Recaptcha
The Google Recaptcha provider can be configured with the following:
| Property | Type | Description |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| secretKey
| String | Required. The secret key that is provided to you when setting up recaptcha. |
| threshold
| Number | Any number between 0 and 1. A response of 0 is a bad interaction (a bot or spammy), while a 1 is a good interaction (a human). Default threshold for accepted submissions is 0.5. |
| tokenName
| String | The field name that will contain the recaptcha token. Default is g-recaptcha-response
. |
A basic configuration would look like this:
{
gcforms: {
config: {
captcha: {
provider: 'recaptcha',
config: {
secretKey: '<YOUR_SECRET_KEY>',
}
}
}
}
}
Here is an example form submission with the Recaptcha token:
grecaptcha.ready(function () {
grecaptcha
.execute("<YOUR_SITE_KEY>", { action: "submit" })
.then(function (token) {
fetch("/api/gcforms/form-submissions", {
method: "POST",
body: JSON.stringify({
form: "contact-us",
"g-recaptcha-response": token,
}),
});
});
});
For more implementation examples, refer to the Google Recaptcha documentation.
Endpoints
| Method | URL | Description |
| -------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| GET
| /api/gcforms/forms
| Get a list of forms. |
| POST
| /api/gcforms/forms
| Create a form. |
| GET
| /api/gcforms/forms/:formId
| Get a form. |
| PUT
| /api/gcforms/forms/:formId
| Update a form. |
| DELETE
| /api/gcforms/forms/:formId
| Delete a form. |
| GET
| /api/gcforms/form-emails
| Get a list of email templates. |
| POST
| /api/gcforms/form-emails
| Create a email template. |
| GET
| /api/gcforms/form-emails/:formId
| Get a email template. |
| PUT
| /api/gcforms/form-emails/:formId
| Update a email template. |
| DELETE
| /api/gcforms/form-emails/:formId
| Delete a email template. |
| GET
| /api/gcforms/form-submissions
| Get a list of submissions. |
| POST
| /api/gcforms/form-submissions
| Create a submission. |
| GET
| /api/gcforms/form-submissions/:formId
| Get a submission. |
| PUT
| /api/gcforms/form-submissions/:formId
| Update a submission. The data in the request replaces the existing submission. |
| PATCH
| /api/gcforms/form-submissions/:formId
| Update a submission. The data in the request updates fields or adds new fields in the existing submission. |
| DELETE
| /api/gcforms/form-submissions/:formId
| Delete a submission. |
Roadmap
- [] Admin pages
- [] List forms
- [] Edit/create form
- [] Form builder
- [] Configurable validation
- [] Edit/create notification related to a form - email builder
- [] View submissions related to a form
- [] More captcha providers.
- [] Example (or supported) integrations with other services (CRMs, Google Sheets data syncing, etc.)