npm package: @goldencomm/strapi-plugin-gcforms
Description: Accept form submissions on your Strapi app.
Author: GoldenComm
Latest version: 2.1.4

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

```js
{
  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.

```js
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

```js
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](https://docs.strapi.io/developer-docs/latest/plugins/email.html). 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](https://docs.strapi.io/developer-docs/latest/development/providers.html#creating-providers) 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.

```js
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:

```js
{
  gcforms: {
    config: {
      captcha: {
        provider: 'recaptcha',
        config: {
          secretKey: '<YOUR_SECRET_KEY>',
        }
      }
    }
  }
}
```

Here is an example form submission with the Recaptcha token:

```js
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](https://developers.google.com/recaptcha/docs/v3#automatically_bind_the_challenge_to_a_button).

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