ng-nested-reactive-forms

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 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.

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.

The Reactive Form tag

<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.

<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 has two approaches to handle forms:

1. Template-driven forms
2. Reactive Forms

Both of them, require that the <form> and the <input> tags resides on the same "scope". e.g.:

<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 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:

<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:

<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