Skip to content

Commit

Permalink
Merge branch 'develop' of https://github.com/bietkul/react-reactive-form
Browse files Browse the repository at this point in the history
  • Loading branch information
bietkul committed Dec 28, 2017
2 parents 0fdbe8e + 9acc11c commit a951591
Show file tree
Hide file tree
Showing 10 changed files with 190 additions and 193 deletions.
64 changes: 1 addition & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,73 +16,10 @@ It's a library inspired by the [Angular's Reactive Forms](https://angular.io/gui
npm install react-reactive-form --save
```
# Basic Example
```js
import React, { Component } from 'react';
import { FormBuilder, Validators, reactiveForm } from "react-reactive-form";

// Create the controls
const loginForm = FormBuilder.group({
username: ['', Validators.required],
password: ['', Validators.required],
rememberMe: false
});

class Login extends Component {
handleReset=(e) => {
loginForm.reset();
e.preventDefault();
}
handleSubmit=(e) => {
console.log("Form values", loginForm.value);
e.preventDefault();
}
render() {
const {
username,
password,
rememberMe
} = this.props;
return (
<form onSubmit={this.handleSubmit}>
<div>
<input {...username.handler()}/>
<span>
{username.touched
&& username.hasError('required')
&& "Username is required"}
</span>
</div>
<div>
<input {...password.handler()}/>
<span>
{password.touched
&& password.hasError('required')
&& "Password is required"}
</span>
</div>
<div>
<input {...rememberMe.handler('checkbox')}/>
</div>
<button onClick={this.handleReset}>Reset</button>
<button disabled={loginForm.invalid} type="submit">Submit</button>
</form>
);
}
}
// React HOC to connect form with component.
export default reactiveForm(Login, loginForm);
```

### Note:
While working with larger forms, deep nested forms & [Form Array’s](docs/api/FormArray.md) it’s highly recommended to use the [Field](docs/api/Field.md) component instead of `reactiveForm` method.

`Field` component subscribes a particular control & only update it when it’s or it’s parent’s state changes, which of course reduces the re-rendering and boost the performance significantly.


```js
import React, { Component } from 'react';
import { FormBuilder, Validators, Field } from "react-reactive-form";
import { AbstractControl } from "react-reactive-form";

export default class Login extends Component {
constructor(props) {
Expand Down Expand Up @@ -169,6 +106,7 @@ Try out `react-reactive-forms` in these sandbox versions of the Examples.
* [Sync & Async Validation](https://codesandbox.io/s/qq8xq7j2w)
* [User Registeration Form With Nested Forms](https://codesandbox.io/s/p2rqmr8qk7)
* [Form Array With Dynamic Controls](https://codesandbox.io/s/nw9wxw2nvl)
* [Update On Submit](https://codesandbox.io/s/3qk1ly16j1)

Let's make React Reactive Forms better! If you're interested in helping, all contributions are welcome and appreciated.

Expand Down
108 changes: 13 additions & 95 deletions docs/GettingStarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,6 @@ The basic implementation of reactive forms is super easy but it may be helpful t
* [Form Array](api/FormArray.md)
* [Form Control](api/FormControl.md)
* [Form Builder](api/FormBuilder.md)
## Overview
There are two ways to connect your components to reactive-form.

### By using `reactiveForm`
You can use the [`reactiveForm`](api/ReactiveForm.md) method. It returns a higher order component
which regulary provides control(mapped) props to your component.
```ts
reactiveForm(ReactComponent: React.SFC|React.ComponentClass<any>, form: FormGroup|FormArray):React.ComponentClass<any>
```

### By using `Field` ( recommended )

For better performance with large forms & [Form Array’s](api/FormArray.md) it’s highly recommended to use the [Field](api/Field.md) component instead of `reactiveForm` method.

`Field` component subscribes a particular control & only update it when it’s or it’s parent’s state changes, which of course reduces the re-rendering and boost the performance significantly.


## Basic Usage Guide
### step 1: Create FormGroup or FormArray
Expand Down Expand Up @@ -58,100 +42,34 @@ const loginForm = new FormGroup({
```

### step2: Connect form with component

### With `reactiveForm`

Use the `reactiveForm` method to connect your form group or array to the Component in which you want to use input handlers.
Now you'll start receiving the [mapped control props](api/Props.md) with input handlers.

In below given example `username.handler` is a function which binds the input element to the `username` control.

```js
import React, { Component } from 'react';
import { FormBuilder, Validators, reactiveForm } from "./react-reactive-form";

// Create the controls
const loginForm = FormBuilder.group({
username: ['', Validators.required],
password: ['', Validators.required],
rememberMe: false
});

class Login extends Component {
handleReset=(e) => {
loginForm.reset();
e.preventDefault();
}
handleSubmit=(e) => {
console.log("Form values", loginForm.value);
e.preventDefault();
}
render() {
const {
username,
password,
rememberMe
} = this.props;
return (
<form onSubmit={this.handleSubmit}>
<div>
<input {...username.handler()}/>
<span>
{username.touched
&& username.hasError('required')
&& "Username is required"}
</span>
</div>
<div>
<input {...password.handler()}/>
<span>
{password.touched
&& password.hasError('required')
&& "Password is required"}
</span>
</div>
<div>
<input {...rememberMe.handler('checkbox')}/>
</div>
<button onClick={this.handleReset}>Reset</button>
<button type="submit">Submit</button>
</form>
);
}
}
// React HOC to connect form with component.
export default reactiveForm(Login, loginForm);

```

### With `Field`
[Field](api/Field.md) subscribes the component to a particular control's state changes which improves the performance by restricting the re-rendering of other fields.
[Field](api/Field.md) component subscribes a particular control & only update it when it’s or it’s parent’s state changes, which improves the performance by restricting the unnecessary re-rendering of other fields.

```js
import React, { Component } from 'react';
import { FormBuilder, Validators, Field } from "react-reactive-form";
import { AbstractControl } from "react-reactive-form";

// Create the controls
const loginForm = FormBuilder.group({
username: ["", Validators.required],
password: ["", Validators.required],
rememberMe: false
});

export default class Login extends Component {
constructor(props) {
super(props);
// Create the controls
this.loginForm = FormBuilder.group({
username: ["", Validators.required],
password: ["", Validators.required],
rememberMe: false
});
}
handleReset=(e) => {
loginForm.reset();
this.loginForm.reset();
e.preventDefault();
}
handleSubmit=(e) => {
console.log("Form values", loginForm.value);
console.log("Form values", this.loginForm.value);
e.preventDefault();
}
render() {
return (
<Field
control={loginForm}
control={this.loginForm}
render={({ get, invalid }) => (
<form onSubmit={this.handleSubmit}>
<Field
Expand Down
9 changes: 7 additions & 2 deletions docs/api/FormArray.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,11 @@ controls: AbstractControl[]
```
##
```ts
submitted: boolean
```
A form is submitted if the `handleSubmit` function has been called on it.
##
```ts
at(index: number): AbstractControl
```
Get the [AbstractControl](AbstractControl.md) at the given index in the array.
Expand Down Expand Up @@ -177,14 +182,14 @@ Otherwise, the `value` property is the best way to get the `value` of the array.

##
```ts
onSubmit():void
handleSubmit():void
```
Submit action, can be used to tell the form that it has been submitted.
Useful when `updateOn` property is `submit`.

Example
```ts
<form onSubmit={this.form.onSubmit}/>
<form onSubmit={this.form.handleSubmit}/>
```
<br/></br>
Note: This document is a derivative of ["Form Array Document"](https://angular.io/api/forms/FormArray) by Google,
Expand Down
108 changes: 106 additions & 2 deletions docs/api/FormControl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,113 @@ Function needs to be called whenever a blur event triggers.
```ts
handler: (inputType?: InputType, value?: string) => Handler;
```
Returns the props required to bind a control with an input element.
Returns the props required to bind a control to a native input element.

For more details see the handler section of [props](Props.md).
Note:
* `inputType` parameter is required for `checkbox`, `radio` and `switch`( React Native ) components.
* `value` parameter only can be used for `radio` buttons to assign a value to a particular button.

Example

```ts
<input type="text" {...username.handler()}/>
```
Binds a `text` input.
##
```ts
<input type="date" {...birthday.handler()}/>
```
Binds a `date` input.
##
```ts
<input {...terms.handler("checkbox")}/>
```
Binds a `checkbox` input.
##
```ts
<input {...gender.handler('radio', 'male')}/> Male
<input {...gender.handler('radio', 'female')}/> Female
<input {...gender.handler('radio', 'other')}/> Other
```
Binds a `radio` input.
##
```ts
<TextInput {...username.handler()}/>
```
Binds a React Native `TextInput` component.
##
```ts
<Switch {...terms.handler('switch')}/>
```
Binds a React Native `Switch` component.

##
A `handler` object can have these properties:

```ts
value: any;
```
Sometimes this value can be different from the actual value of `control`.

For example, if the `updateOn` property is `blur` or `submit` than the value property of handler will be `_pendingValue`
of the control.

The `_pendingValue` is the value of a control which is not validated yet which means the actual value of the
control is different.

So, this `value` is just to control the input element, for actual value of the control you can use the `value` property
of the mapped control prop.
##
```ts
onChange: (e: any) => void;
```
Function needs to be called whenever a value change event triggers.
##
```ts
onBlur: (e: any) => void;
```
Function needs to be called whenever a `blur` event triggers.
##
```ts
disabled: boolean;
```
Tells the input element about the `disabled` status.
##
```ts
checked?: boolean;
```
Checked property for `checkbox` and `radio` buttons.
##
```ts
editable?: boolean;
```
React Native uses `editable` property to tell the `TextInput` about the `enabled` status.
##
```ts
type?: string;
```
Returns the type of input element in case of `checkbox` & `radio` buttons.


Although `handler` works well with all kind of inputs, you can also bind your custom input
components.

Example

```ts
<Field
control={myForm.get('birthday')}
render={({ onChange, value }) => (
<DatePickerIOS
date={value}
dateForm="MM/DD/YYYY"
onDateChange={onChange}
/>
)}
/>
```
Binds a React Native `DatePickerIOS` component.
Note: This document is a derivative of ["Form Control Document"](https://angular.io/api/forms/FormControl) by Google,
under [CC BY](https://creativecommons.org/licenses/by/4.0/).
Expand Down
11 changes: 8 additions & 3 deletions docs/api/FormGroup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,11 @@ controls: {
```
##
```ts
submitted: boolean
```
A form is submitted if the `handleSubmit` function has been called on it.
##
```ts
registerControl(name: string, control: AbstractControl): AbstractControl
```
Registers a control with the group's list of controls.
Expand Down Expand Up @@ -187,14 +192,14 @@ Otherwise, the value property is the best way to get the value of the group.

##
```ts
onSubmit():void
handleSubmit():void
```
Submit action, can be used to tell the form that it has been submitted.
Useful when `updateOn` property is `submit`.
Useful when `updateOn` property is `handleSubmit`.

Example
```ts
<form onSubmit={this.form.onSubmit}/>
<form onSubmit={this.form.handleSubmit}/>
```

<br/></br>
Expand Down
Loading

0 comments on commit a951591

Please sign in to comment.