README.md

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