# @webdev-tools/ng-nested-reactive-forms

> Implement Nested FormControl for Angular Reactive Forms.

Latest version **7.0.1** (published 2018-11-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @webdev-tools/ng-nested-reactive-forms
pnpm add @webdev-tools/ng-nested-reactive-forms
yarn add @webdev-tools/ng-nested-reactive-forms
bun add @webdev-tools/ng-nested-reactive-forms
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 7.0.1 |
| Published | 2018-11-19 |
| First published | 2018-05-09 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 582.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | carlos.algms |
| Keywords | Angular, Forms, Reactive |

## Links

- npm: https://www.npmjs.com/package/@webdev-tools/ng-nested-reactive-forms
- Repository: https://github.com/webdev-tools/ng-nested-reactive-forms
- Homepage: https://github.com/webdev-tools/ng-nested-reactive-forms#readme
- Issues: https://github.com/webdev-tools/ng-nested-reactive-forms/issues
- npm.io page: https://npm.io/package/@webdev-tools/ng-nested-reactive-forms

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^1.9.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 7.0.1 (latest) — 2018-11-19
- 7.0.0 — 2018-11-19
- 6.2.6 — 2018-07-27
- 6.2.5 — 2018-07-27
- 6.2.4 — 2018-07-24
- 6.2.3 — 2018-07-06
- 6.2.2 — 2018-07-06
- 6.2.1 — 2018-07-04
- 6.2.0 — 2018-07-02
- 6.1.0 — 2018-07-01
- 6.0.3 — 2018-06-28
- 6.0.2 — 2018-06-27
- 5.0.7 — 2018-06-27
- 5.0.6 — 2018-06-27
- 6.0.1 — 2018-05-29
- … 10 more at https://npm.io/package/@webdev-tools/ng-nested-reactive-forms/versions

## README

# ng-nested-reactive-forms

![travis build](https://api.travis-ci.org/webdev-tools/ng-nested-reactive-forms.svg?branch=master)
![Codecov](https://img.shields.io/codecov/c/github/webdev-tools/ng-nested-reactive-forms.svg)
![NPM version](https://img.shields.io/npm/v/@webdev-tools/ng-nested-reactive-forms.svg)
![Downloads](https://img.shields.io/npm/dy/@webdev-tools/ng-nested-reactive-forms.svg)
![Downloads](https://img.shields.io/npm/l/@webdev-tools/ng-nested-reactive-forms.svg)

Implement Nested FormControl for Angular Reactive Forms.

Split your forms as much as you need,
and let the nested reactive form components handle the data changes.

The `form` tag and the inputs doesn't have to share the same scope.

# Concepts

Enforce the usage of an `Entity`, also know as `Model`, to share data between the form and the controller.

Use two-way data-binding as [AngularJS 1.x](https://docs.angularjs.org/tutorial/step_06) does.

**Do not** mutate the original `Entity` when user make changes to inputs.

Define the data-binding using dot-notation e.g.: `user.addresses[1].streetName`

It is not necessary to pass the `Entity` through all nested components,  
**forms** and **inputs** will communicate with each other
no matter how deep the nested components are.

Submit event will only be triggered if all inputs are [Valid](https://angular.io/guide/form-validation).


# Usage

Only two directives are mandatory:

1. `nrfForm` on the `<form>` tag
2. `*nrfNestedControl` on a parent of a given `input`, `textarea`, `select`, or even a [custom component](https://angular.io/api/forms/DefaultValueAccessor).


## The Reactive `Form` tag

```html
<form
  nrfForm
  (nrfSubmit)="handleSubmit($event)"
  [nrfEntity]="anyObject"
>
<!-- All components and inputs -->
</form>
```

| Property    | type     | Description                                                                        |
|-------------|----------|------------------------------------------------------------------------------------|
| nrfForm     | --       | **Required** The main directive that enables communication with the nested inputs. |
| (nrfSubmit) | function | This `@Output` only will be called if all the inputs inside this form are valid.   |
| [nrfEntity] | Object   | The `Entity` that will be handled by this form. If not empty, inputs will be pre-filled using its data |


### Submit `$event` properties

| Property   | type               | Description                                          |
|------------|--------------------|------------------------------------------------------|
| entity     | Object             | A reference to the original `Entity` passed to the form tag |
| formData   | Object             | An Object containing all Entity's properties and changes made by the user |
| formGroup  | FormGroup          | The form FormGroup instance, used to validate fields |
| nrfForm    | nNgRFFormDirective | The nrfForm directive instance                       |
| event      | Event              | The original HTML event from the form submit         |



## The Reactive `input` tag

You have to put `*nrfNestedControl` on an input parent tag.  
And use `[formControl]` directly on the `input` tag, as described on
[Angular Reactive Forms](https://angular.io/guide/reactive-forms#create-the-template).

```html
<div *nrfNestedControl="'userModel.firstName'; let control=formControl">
  <input [formControl]="control" />
</div>
```

### Variables available in the context
| Name             | Description                                    |
|------------------|------------------------------------------------|
| formControl      | It is **mandatory** to use this on the given input, otherwise no data-binding or validation will be applied  |
| formGroup        | A reference to the form formGroup              |
| nrfNestedControl | The NestedControl instance                     |



# Motivation

[Angular](https://angular.io) has two approaches to handle forms:

1. [Template-driven forms](https://angular.io/guide/forms#template-driven-forms)
2. [Reactive Forms](https://angular.io/guide/reactive-forms#reactive-forms)

Both of them, require that the `<form>` and the `<input>` tags resides on the same "scope".
e.g.: 
```html
<form ....>
  <div ...>
    <input [ngModel]="firstName" /> <!-- Works! -->
  </div>
  <component-with-ng-content>
    <input [formControl]="myControlInstance" /> 
    <!-- Also Works!, even after it get rendered inside this component -->
  </component-with-ng-content>

  <!-- FAIL! Angular will not look on the rendered content -->
  <!-- Even though it will only renders an <input> and a <label> -->
  <my-input-with-label></my-input-with-label>
</form>
```

[NG_VALUE_ACCESSOR](https://angular.io/api/forms/DefaultValueAccessor) 
is available, but it has to share same "scope", as well.

---

Given these difficulties, it is very hard to "componentize" our App's forms.

Here is just a example on how one can split a form:

```html
<app-form-abstraction>
  <user-page>
    <user-personal-data></user-personal-data>
    <user-contacts></user-contacts>
    <user-addresses></user-addresses>
  </user-page>
  <default-form-buttons></default-form-buttons>
</app-form-abstraction>
```

Think about Reusability:
```html
<user-details-page>
  ....
  <modal-abstraction>
    <user-contacts></user-contacts> <!-- Yes, the same component -->
  </modal-abstraction>
  ....
</user-details-page>
```

## Versioning

```
+----- Major version is synchronize with Angular's major version.
| +--- Minor version has BREAKING CHANGE and features.
| | +- Patch version has fixes and features, but no breaking changes.
| | |
0.0.0
```

---
_Source: https://npm.io/package/@webdev-tools/ng-nested-reactive-forms · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._