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