Forms For Caldera

This is a React component library for forms. It is designed to be used in Caldera UIs, including Caldera Forms.

Install

yarn add @calderajs/forms

Testing

• Run Unit Tests - Jest.

  • yarn tests

• Run Storybooks

  • yarn storybook

Other Commands

• Lint code
  • yarn lint
• Build Package
  • yarn package
  • The output is stored in the dist folder.
• Run tests once for CI
  • yarn test:ci

Usage

<CalderaForm />

This component is used for all forms in the Caldera Framework. The Caldera Forms front-end (Caldera Forms 2.0+) and all UI sections.

This component uses Formik for managing state and validation. The layout uses the CalderaGrid component of this package and uses the fieldAreaFactory from the calderawp/@factory package.

Why Formik?

I originally wanted to use redux-forms. I didn't love the API or the validation. Also, I had a less articulate version of these conncerns. We're using more of Formik's features than you need to create a working form. Formik feels like it does the basics really well and everything is extensible.

Specific benefits:

• We are not developing our own validation system.
  • The validation system is super extensible.
  • Validation Documentation
• Loop Fields/ Repeater Fields: Totally Covered.
  • <FieldArray />
• Great Documentation
• Allows us to supply our own field components, CSS, layouts, etc.
  • Formik has text, select, textarea fields, but we don't have to use them.

Import With webpack

import {CalderaForm} from '@calderajs/forms';

Creating a form

The Caldera Forms component is totally decoupled from Caldera Forms 1.x form submission. The <CF2Form /> component is designed to be used with Caldera Forms 1.9 or later.

<CalderaForm
    form={form}//form config
    onSubmit={(
        //current values of all fields
        values, 
        actions
    ) => {
        setTimeout(() => {
            alert(JSON.stringify(values, null, 2));
            actions.setSubmitting(false);
        }, 1000);
    }}
    onChange={(values) => {
        console.log(values) //all field values
    }}
    />

Props

• formRows - Object - The form layout.
• onSubmit Function - Called when form is submitted by Formik.onSubmit()
  • Receives all field values and a Formik Bag
  • Formik Docs
• onChange Function - Called when any field is changed.
  • Is passed all updated field values.
• initialValues - Object. Initial values for all fields in form. Mapped fieldId : fieldValue

Shape Of Form

• id - string
• name - string
• fields - array
• conditionals - array
• rows - array

import{createFieldRule} from '@calderajs/forms';
const form = {
    id: 'contact-form',
    name: 'Contact Form',
    rows : [
        {
            rowId: 'r1',
            columns: [
                {
                    columnId: 'c1',
                    fields: ['sendEmail'],
                    width: '1/4'
                },
                {
                    columnId: 'c2',
                    fields: ['primaryEmail'],
                    width: '3/4'
                }
            ]
        }	
    ],
    fields:[
        {
            type: 'select',
            fieldId: 'sendEmail',
            label: 'Would you like to provide an email?',
            options: [
                {optionValue: true, label: 'Yes' },
                {optionValue: false, label: 'No' },
            ]
        },
        {
            type: 'input',
            fieldId: 'primaryEmail',
            html5type: 'email',
            label: 'Your Email'
        }
    ],
    conditionals: [
        {
            //result of conditional
            type: 'hide',
            //Logic of conditional
            rule: createFieldRule('is', 'sendEmail', true ),
            //fields effected by conditional
            fields: [
                'primaryEmail'
            ]
        }
    ]
}

<CF2Form>

Wrapper for <CalderaForm /> designed to be used with the "cf2" API in Caldera Forms 1.x.

🌋👀Documentation

<HorizontalForm>

Wrapper for <CalderaForm /> where every field is in its own 100% wide row. Useful for Gutenberg block settings for field settings in Caldera Forms form builder.

🌋👀Documentation

MailChimp Forms

Mailchimp sign up and survey forms. 🌋👀Documentation

Contact Form

🌋👀Documentation

Clients

See the clients Readme