GitXplorerGitXplorer
k

react-form

public
17 stars
5 forks
1 issues

Commits

List of commits on branch master.
Unverified
d5cc16722672d50d64a19afd5cc112a6add0a25e

Merge pull request #2 from vesln/patch-1

kkorbin committed 10 years ago
Unverified
41887e1449f4f0ba0fd2787725cd435b8a5918fc

Relative links

vvesln committed 10 years ago
Unverified
6130adca36f3ac57e29c4b2113af72fe9549835d

Merge pull request #1 from gabehesse/master

kkorbin committed 10 years ago
Unverified
4eb699932e213a3dc0e6c4ee8c285fb44b47f624

Fix Spelling

ggabehesse committed 10 years ago
Unverified
5cd64c57172ba5fda54929cdacfb51e9af5b1d9d

fix: temporarily remove broken shouldComponentUpdate

kkorbin committed 10 years ago
Unverified
2e23f9e3fc6a2219db198d2f4df34267dc963f10

react-form: initial commit

kkorbin committed 10 years ago

README

The README file for this repository.

react-form

npm version Build Status

Synopsis

react-form is a lightweight, opinionated form-building system for React. The react-form DSL was designed to produce clean code that directly resembles an underlying object hierarchy.

Design Goals

  • Consistent, clean, fun-to-use DSL.
  • Server-side rendering is assumed.
  • Input components are pluggable.
  • HTTP POST backward compatibility.

Quick Start

Install react-form, react-form-inputs:

npm install --save react-form react-form-inputs

Basic usage example (JSX+ES6):

var React = require('react');
var {Form, Input} = require('react-form');
var {Password, Text} = require('react-form-inputs');

var LoginForm = React.createClass({
  render() {
    return (
      <Form {...this.props} for="user">
        <h1>Login</h1>
        <Input type={Text} for="username" placeholder="Username" />
        <Input type={Password} for="password" placeholder="Password" />
        <input type="submit" value="Login" />
      </Form>
    );
  }
});

var user = {
  username: null,
  password: null
};

React.render(<LoginForm object={user} />, document.getElementById('login'));

react-form ships with an example application - try it out:

cd example
npm install
npm link ../
node app
#Open http://localhost:3000

Technical

Object mapping

react-form uses a context-based materialized path system to track and propagate object changes.

The Form, Inputs, and Input components expose interfaces to easily reference nodes anywhere in an object hierarchy. Each of the aforementioned components represents a "path segment."

Each of these components exposes

Components

Form

Form is a required outer container component. Form components are responsible for maintaining state and propagating changes. Form exposes event interfaces for advanced integration with a parent application, Store, component, etc.

Form has several configurable props:

  • for String - Namespace for a Form instance. Used to generate input names. Defaults to "object."
  • object Object - Object used to hydrate input fields. Defaults to "{}."
  • onSubmit Function(event) - Called when Form instance is submitted.
  • onUpdate Function(path, value) - Called when a nested Input at path undergoes a value change to value. NOTE: Supplying this handler disables internal Form state management; onUpdate must replace props.object to trigger a rerender.
  • Unmentioned props are applied to the resulting form tag.

Tip: When implementing a custom onUpdate or onSubmit handler, use objectPath and this.getValue() to negotiate object changes.

Inputs

Inputs is a nested container element. Inputs is required to reference nested objects and arrays of objects. Inputs is not utilized in simple, single-tier models.

When referencing an Array of objects, all children are duplicated and mapped to each array element.

Inputs has two user-configurable props:

  • for String - Required path segment. Must reference an object or array of objects.
  • forName String - Optionally used to override "name" attributes of nested components.

Example:

var {Form, Inputs} = require('react-form');
var gizmo = { //path: []
    widgets: [ //path: [widgets] <-- INPUTS
        { color: "Red" }, //path: [widgets, 0, color]
        { color: "Blue" } //path: [widgets, 1, color]
//...
<Form for="gizmo" object={gizmo}>
  <Inputs for="widgets"> //in this example, children will be duplicated twice

Input

Input is the most commonly-used component. Input is used to render form controls, each varying in function and complexity.

Input requires API-compliant, pluggable components known as "types." For flexibility, no Input types ship with react-form. A number of useful, common components can be found in react-form-inputs.

Input has three universally-applicable props:

  • type Input type - Required, API-compliant component to render.
  • for String - Required path segment. Must reference a value appropriate for given Input type.
  • forName String - Optionally used to override generated Input "name."

See type-specific documentation for respective Input types for additional, configurable props.

Example:

var React = require('react');
var {Form} = require('react-form');
var Text = require('react-form-inputs/text');

var gizmo = { //path: []
    name: "Foo" //path: [name]
//...
<rf.Form for="gizmo" object={gizmo}>
    <rf.Input type={Text} for="name" /> //Initial value of "Foo"

Addons

Documentation regarding the built-in addon system will be provided in an upcoming release. Optional addons enabling conformity with Rails-conventions, field label generation, and error handling are in development.

Developing

Presently, react-form APIs are highly unstable, untested, and explosive!

Run tests:

npm test

Link a dependent project:

#Within dependent project directory...
npm link ~/path-to-react-form/

Contributing

  • Fork the project.
  • Create a descriptively-named branch for your changes. (fix_whatever, add_this)
  • Commit your change.
  • Add appropriate documentation, test coverage.
  • Test with "npm test" (requires jest-cli).
  • Issue a pull request for your branch.

Thanks

The react-form DSL was heavily inspired by (stolen from) Formtastic.

License

react-form is released under the MIT License.