@goldencomm/strapi-plugin-gcforms

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.)