@payloadcms/plugin-form-builder

Payload Form Builder Plugin

A plugin for Payload CMS to easily allow your admin editors to build and manage forms from the admin panel.

Core features:

• Creates a forms collection where you can:
  • Build dynamic forms with any number of fields
  • Add payment fields that can handle dynamic prices
  • Build completely custom and dynamic emails
• Creates a formSubmissions collection that:
  • Validates and saves the form data submitted by your frontend
  • Sends emails (if applicable)
  • Handles payment processing (if applicable)

Installation

  yarn add @payloadcms/plugin-form-builder
  # OR
  npm i @payloadcms/plugin-form-builder

Basic Usage

In the plugins array of your Payload config, call the plugin with options:

import { buildConfig } from 'payload/config';
import formBuilder from '@payloadcms/plugin-form-builder';

const config = buildConfig({
  collections: [
    {
      slug: 'pages',
      fields: []
    }
  ],
  plugins: [
    formBuilder()
  ]
});

export default config;

Options

• fields An object of field types to allow your admin editors to build forms with. Pass either a boolean value or a partial Payload Block to override default settings. See Fields for more details.

  fields: {
    text: true,
    select: true,
    email: true,
    state: true,
    country: true,
    checkbox: true,
    number: true,
    message: true,
    payment: false
  }
  

  You can also provide your own custom field definitions by passing a new Payload Block object into fields.

• redirectRelationships

  An array of collection slugs that, when enabled, are populated as options in form redirect fields.

  redirectRelationships: ['pages']
  

• handlePayment

  A beforeChange hook that is called upon form submissions. You can integrate into any third-party payment processing API here. There is a getPaymentTotal function that will calculate the total cost after all conditions have been applied.

  import { getPaymentTotal } from '@payloadcms/plugin-form-builder';
  ...
  handlePayment: async ({ form, submissionData }) => {
    // first calculate the price
    const paymentField =  form.fields?.find((field) => field.blockType === 'payment');
    const price = getPaymentTotal({
      basePrice: paymentField.basePrice,
      priceConditions: paymentField.priceConditions,
      fieldValues: submissionData,
    });
    // then asynchronously process the payment here
  }
  

• beforeEmail

  A beforeChange hook that is called just after emails are prepared, but before they are sent. This is a great place to inject your own HTML template to add custom styles.

  beforeEmails: (emailsToSend) => {
    // modify the emails in any way before they are sent
    return emails.map((email) => ({
      ...email,
      html: email.html // transform the html in any way you'd like (maybe wrap it in an html template?)
    }))
  };
  

• formOverrides

  Override anything on the form collection by sending a Payload Collection Config. Your overrides will be merged into the default forms collection.

  formOverrides: {
    slug: 'contact-forms'
  }
  

• formSubmissionOverrides By default, this plugin relies on Payload access control to restrict the update and read operations. This is because anyone should be able to create a form submission, even from a public-facing website - but no one should be able to update a submission one it has been created, or read a submission unless they have permission.

  You can override access control and anything else on the form submission collection by sending a Payload Collection Config. Your overrides will be merged into the default formSubmissions collection.

  formSubmissionOverrides: {
    slug: 'leads'
  }
  

Fields

Each form field is defined as a Payload Block with the following subfields:

• Text
  • name: string
  • label: string
  • defaultValue: string
  • width: string
  • required: checkbox
• Select
  • name: string
  • label: string
  • defaultValue: string
  • width: string
  • options: array
  • required: checkbox
• Email
  • name: string
  • label: string
  • defaultValue: string
  • width: string
  • required: checkbox
• State
  • name: string
  • label: string
  • defaultValue: string
  • width: string
  • required: checkbox
• Country
  • name: string
  • label: string
  • defaultValue: string
  • width: string
  • required: checkbox
• Checkbox
  • name: string
  • label: string
  • defaultValue: checkbox
  • width: string
  • required: checkbox
• Number
  • name: string
  • label: string
  • defaultValue: number
  • width: string
  • required: checkbox
• Message
  • message: richText
• Payment
  • name: string
  • label: string
  • defaultValue: number
  • width: string
  • required: checkbox
  • priceConditions: array
    • fieldToUse: relationship, dynamically populated based on the fields in your form
    • condition: string - equals, notEquals | hasValue
    • valueForOperator: string - only if condition is equals or notEquals
    • operator: string - add, subtract, multiply, divide
    • valueType: string - static, valueOfField
    • value: string - only if valueType is static

Email

This plugin relies on the email configuration defined in your payload.init(). It will read from your config and attempt to send your emails using the credentials provided.

TypeScript

All types can be directly imported:

import {
  FormConfig,
  Form,
  FormSubmission,
  FieldsConfig,
  BeforePayment,
  HandlePayment
 } from '@payloadcms/plugin-form-builder/dist/types';

Screenshots

Changelog

1.0.4 (2022-07-19)

Features

• Updated UI: Dark Mode
• Updated UI: Collapsibles (60bfb1c)
• Updated UI: Tabs field (68e7c41)
• Updated UI: Styling Revamp and responsive improvements
• More maintainable colors via CSS vars
• Improved test coverage through granular Payload configs
• Introduction of E2E tests through Playwright
• allow clear select value (#735) (3132d35)

BREAKING CHANGES

We have removed our reliance on SCSS variables like color and font, replacing them instead with CSS variables wherever possible.

Due to this change, the admin.scss functionality has become obsolete, and overriding SCSS variables is not longer needed or supported. If you want to customize CSS, you can still do so, but via the admin.css property instead.