Skip to content

Latest commit

 

History

History
129 lines (106 loc) · 5.36 KB

README.md

File metadata and controls

129 lines (106 loc) · 5.36 KB
Raw

Shaking React Form

build and use extensible react forms easily.

Deprecated

This project is deprecated. Please refer to the replacement project rf-form.

Activation

Writing forms is boring, writing forms with validations is extremely boring. We want to build forms with validations easily, meanwhile, we want to use different styles. By searching and learning some existing react form projects, I found them difficult to use or hard to extend...

Design Goals

  • based on react
  • schema driven
  • least dependencies
  • simple and robust
  • easy to use
  • easy to extend with different layouts, styles, input types

Installation

  • install React
  • install core form by npm install shaking-react-form --save
  • write your form field class or install some existing field packages listed below.

Available field packages

Demo

More demos

Brief demo:

import ShackingForm from 'shaking-react-form';
import RawShakingReactFormField from 'raw-shaking-react-form-field';

const schemas = {
    username: {
        label: 'Username',
        validate(v){
            if (!v) return 'username is required'
        },
        options: {
            placeholder: 'input username'
        }
    },
    
    password: {
        label: 'Password',
        type: 'password',
        validate(v){
            if (!v || v.length < 6) return 'password cannot be less than 6 letters'
        }
    },
}

class SomeReactComponent extends React.Component {
    // you can save form values as you like, here is just for convenience saving them directly into state
    constructor(props) {
        super(props);
        this.state = {};
        Object.keys(schemas).forEach(key=>this.state[key] = null);
    }

    render() {
        return <div>
            <ShackingForm
                schemas={schemas}
                values={this.state}
                onChange={(values)=>{this.setState(values)}}
                onSubmit={(values)=>console.log('submit', values)}
                onErrors={(errors)=>console.log('errors', errors)}
                fieldClass={RawShakingReactFormField}
            >
                <button type="submit">Submit</button>
            </ShackingForm>
        </div>
    }
}

Apis

props

  • {Array | Object} schemas - schemas for form fields. a schema is like

      {
      type: '...', // defined by the field class you use
      label: '...',
      validate: function(value){...}, // validation function for value of this field, return a string to indicate an validation error
      options: ..., // any thing a specific field needs, defined by the field class you use  
      fieldClass: ..., // you can specify a the field class for this filed individually
      readOnly: bool,
      disabled: bool
  }

  • {ReactComponent} [fieldClass] - the field class the form will use to render the fields

  • {Array | Object} [values] - values for form fields. if not defined, the form will be uncontrolled

  • {Func} [onChange] - function(values), callback for change events of fields, only changed values are passed in

  • {Func} [onSubmit] - function(values), callback for submit event of the form, won't be triggered if there are validation errors

  • {Func} [onErrors] - function(errors), callback for submit event of the form, will be triggered only if there are validation errors

  • {Boolean} [readOnly]

  • {Boolean} [disabled]

settings

  • defaultFieldClass - you can set a field class for all forms in your app by ShackingForm.defaultFieldClass = ...

Advanced

You can create your own field classes, it's not hard, and we hope you can contribute them to the society :)

A field class is nothing but a react component which is responsible to properly render the field with several props:

  • {String} label
  • {String} type
  • {Any} options
  • {Any} value
  • {Func(value)} onChange
  • {String} validationState - null, 'success' or 'error'
  • {String} validationError

there are no limit about type, options, and value, you can define and describe them clearly in your docs.

it's helpful to have a look at how we do.

Q&A

How to customize style or layout of a field?

You can create your own field class, use it for a individual field or compose it into default field class. see how to create field class and how to compose field classes

How to compose field classes

A field class can be just a swicher which renders other field class by type. So you can write such a swicher field class to compose many other field classes. react-mapper is a good helper for you to do this. see this demo.