@webdev-tools/ng-nested-reactive-forms v7.0.1

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>

Submit $event properties

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

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