Awesome
NGX-FORM
Model based typed reactive forms made easy.
Summary
- How to install
- Basic usage
- FormGroup
- FormArray
- Validator, AsyncValidator and UpdateOn
- FormChild
- Form lifecycle
- DisableOn
- [OnValueChanges]
How to install
First install the library in your project :
npm install --save @paddls/ngx-form
Recommended Angular versions
Angular | NgxForm |
---|---|
18.0.0 and above | 8.0.0 and above |
17.0.0 and above | 7.0.0 and above |
16.0.0 and above | 6.0.0 and above |
15.0.0 and above | 5.0.0 and above |
14.0.0 and above | 4.0.1 and above |
13.0.0 and above | 3.0.1 and above |
12.0.0 and above | 2.0.0 and above |
11.0.0 and above | 1.0.0 and above |
After that, import NgxFormModule
as follows :
import {ReactiveFormsModule} from '@angular/forms';
import {NgxFormModule} from '@paddls/ngx-form';
@NgModule({
imports: [
ReactiveFormsModule,
NgxFormModule
]
})
export class AppModule {
}
Basic usage
Create a form
With ngx-form, the form creation is model driven. Therefore, to create a form, you need to create a model class which will represent the form.
A form model should look like this :
import {FormControl} from '@paddls/ngx-form';
export class AddressForm {
@FormControl()
public city: string;
@FormControl({defaultValue: 3})
public streetNumber: number;
@FormControl({defaultValue: '10055', name: 'postalCode'})
public zipCode: string;
@FormControl('street')
public route: string;
public constructor(data: Partial<AddressForm> = {}) {
Object.assign(this, data);
}
}
Each class attribute with the @FormControl()
decorator will be marked as a form control. Inside
the @FormControl()
annotation, you can add some context at your will. Two properties are
available : defaultValue
and name
.
By specifying a defaultValue
, the form control will be initialized with this value at the form creation.
With the name
property, you can differentiate the name given to the field in your model and the name of the control
in the created form.
You can define only one of the properties in the context, or both. If you just want to specify the
name
property, you can do it just by passing a string as the context like in the example above.
Build a form
Once you've created the model, you can build the form wherever you like through your entire Angular application using
the @BuildForm()
decorator.
import {Component} from '@angular/core';
import {BuildForm, NgxFormGroup} from '@paddls/ngx-form';
import {AddressForm} from './form/address.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html'
})
export class AppComponent {
@BuildForm(() => AddressForm)
public addressForm: NgxFormGroup<AddressForm>;
public onSubmit(): void {
console.log(this.addressForm.getValue());
}
}
That's it ! You can now use your newly created form juste like any other reactive form. Furthermore, the form is
strongly typed. To retrieve the strongly typed result, just call form.getValue()
method.
FormGroup
import {FormControl, FormGroup} from '@paddls/ngx-form';
import {AddressForm} from './address.form';
export class UserForm {
@FormControl({value: 'Brad'})
public firstName: string;
@FormControl({value: 'Pitt'})
public lastName: string;
@FormGroup(() => AddressForm)
public personalAddress: AddressForm;
@FormGroup({type: () => AddressForm, defaultValue: myAddressValue, name: 'companyAddress'})
public workAddress: AddressForm;
}
To nest forms, use the @FormGroup()
decorator. Do not forget to specify the type of your child form in the decorator
context.
You can also specify defaultValue
and name
properties if necessary. If you don't need to specify them, you can
specify the type in the context directly like in the example above.
FormArray
import {FormControl, FormArray} from '@paddls/ngx-form';
import {CompanyForm} from './company.form';
export class UserForm {
@FormControl({defaultValue: 'Leonardo'})
public firstName: string;
@FormControl()
public lastName: string;
@FormArray({defaultValue: 'Default skill', defaultValues: ['Java', 'C++'], updateOn: 'blur', name: 'userSkills'})
public skills: string[];
@FormArray(() => CompanyForm)
public companies: CompanyForm[];
}
To add a FormArray
to your form model, just add an attribute with the @FormArray()
decorator. Again, you can specify defaultValue
and name
properties if necessary. Like with the @FormGroup()
decorator, you can specify a type if you wish to create an array of nested forms.
Additionally, you can add defaultValues
or updateOn
properties to the context.
Like with the @FormControl()
or @FormGroup()
decorators, shorthands for name
and type
properties are available. Just specify the properties directly in the context if they are the only property used.
Validator, AsyncValidator and UpdateOn
import {FormControl, FormGroup, UpdateOn, Validator, AsyncValidator} from '@paddls/ngx-form';
import {AddressForm} from './address.form';
import {clone} from 'lodash';
import {Validators} from '@angular/forms';
@UpdateOn('change')
export class UserForm {
@FormControl({defaultValue: 'Thomas'})
@Validator(Validators.required)
@UpdateOn('blur')
public firstName: string;
@AsyncValidator(myAsyncValidator)
@FormControl('lastname')
public lastName: string;
@Validator([Validators.required, Validators.min(0)])
public age: number;
@FormGroup({type: () => AddressForm, defaultValue: clone(defaultAddress)})
@UpdateOn('submit')
public personalAddress: AddressForm;
}
To add Validators, AsyncValidators or specify the updateOn
property on any form, FormControl
,
FormGroup
or FormArray
, just add a @Validator
, @AsyncValidator
or @UpdateOn
decorator on any form
model attribute or on the form model class if you want to apply it to a form.
The @Validator
or @AsyncValidator
decorators take any ValidatorFn
, AsyncValidatorFn
or arrays of
ValidatorFn
and AsyncValidatorFn
as parameters to apply them to the desired control or form. The
@UpdateOn
decorator takes 'change'
, 'blur'
or 'submit'
value as parameter to apply it to the desired
control or form.
ValidatorFactory
You can use a ValidatorFactory
to build a ValidatorFn
using values from any provider (@Injectable()
) with the
following syntax :
class Form {
@Validator([
ValidatorFactory.of(((provider: MyProvider) => Validators.min(provider.length)), [MyProvider])
])
@FormControl()
public secondaryAddress: string;
}
You can mix standard ValidatorFn
and ValidatorFactory
inside the @Validator
decorator.
AsyncValidatorFactory
You can also use a AsyncValidatorFactory
, it has the same behaviour as ValidatorFactory
.
class Form {
@AsyncValidator([
AsyncValidatorFactory.of(
(service: MyService) => () => service.httpCall().pipe(map((result: string) => ({error: result}))),
[MyService]
)
])
@FormControl()
public secondaryAddress: string;
}
FormChild
import {Component} from '@angular/core';
import {BuildForm, FormChild, NgxFormArray, NgxFormGroup} from '@paddls/ngx-form';
import {UserForm} from '../form/user.form';
import {CompanyForm} from '../form/company.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss']
})
export class AppComponent {
@BuildForm(() => UserForm)
public userForm: NgxFormGroup<UserForm>;
@FormChild({attribute: 'userForm', path: 'skills'})
public skillForms: NgxFormArray<string>;
@FormChild({attribute: 'userForm', path: 'companies'})
public companyForms: NgxFormArray<CompanyForm>;
}
@FormChild
attribute can be used to access a subform of a built parent form directly. To do that, add an attribute
with the @FormChild
decorator in the same class as your built parent form. Just specify the attribute name of the
parent form with the attribute
decorator parameter, the path
of the form child you want to directly access, and you're done !
Form lifecycle
A NgxForm
object exposes the following methods :
getValue()
Returns the current strongly typed value of the form.
import {Component} from '@angular/core';
import {BuildForm, NgxFormGroup} from '@paddls/ngx-form';
import {AddressForm} from './form/address.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html'
})
export class AppComponent {
@BuildForm(() => AddressForm)
public addressForm: NgxFormGroup<AddressForm>;
public onSubmit(): void {
console.log(this.addressForm.getValue());
}
}
setValue()
Sets a new value on the form. The behaviour of this method is similar to classic reactive forms.
import {Component} from '@angular/core';
import {BuildForm, NgxFormGroup} from '@paddls/ngx-form';
import {AddressForm} from './form/address.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html'
})
export class AppComponent {
@BuildForm(() => AddressForm)
public addressForm: NgxFormGroup<AddressForm>;
public constructor() {
this.addressForm.setValue(new AddressForm({city: 'New York City'}))
}
}
patchValue()
Patches a new value on the form. The behaviour of this method is similar to classic reactive forms.
import {Component} from '@angular/core';
import {BuildForm, NgxFormGroup} from '@paddls/ngx-form';
import {AddressForm} from './form/address.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html'
})
export class AppComponent {
@BuildForm(() => AddressForm)
public addressForm: NgxFormGroup<AddressForm>;
public constructor() {
this.addressForm.patchValue(new AddressForm({city: 'New York City'}))
}
}
restore()
Restores the form value to the initial value. Each control initial value is defined with the defaultValue
attribute
available in the @FormControl()
, @FormGroup()
and @FormArray()
decorators.
import {Component} from '@angular/core';
import {BuildForm, NgxFormGroup} from '@paddls/ngx-form';
import {AddressForm} from './form/address.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html'
})
export class AppComponent {
@BuildForm(() => AddressForm)
public addressForm: NgxFormGroup<AddressForm>;
public onRestore(): void {
this.addressForm.restore();
}
}
empty()
Empties all values of the form. This calls reset()
method on each form control and clear()
method on all form
arrays.
import {Component} from '@angular/core';
import {BuildForm, NgxFormGroup} from '@paddls/ngx-form';
import {AddressForm} from './form/address.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html'
})
export class AppComponent {
@BuildForm(() => AddressForm)
public addressForm: NgxFormGroup<AddressForm>;
public onRestore(): void {
this.addressForm.empty();
}
}
cancel()
Cancels the last setValue()
applied on the form.
import {Component} from '@angular/core';
import {BuildForm, NgxFormGroup} from '@paddls/ngx-form';
import {AddressForm} from './form/address.form';
@Component({
selector: 'app-root',
templateUrl: './app.component.html'
})
export class AppComponent {
@BuildForm(() => AddressForm)
public addressForm: NgxFormGroup<AddressForm>;
public onRestore(): void {
this.addressForm.cancel();
}
}
markAllAsDirty()
Sets all controls to DIRTY
state.
markAllAsPending()
Sets all controls to PENDING
state.
markAllAsPristine()
Sets all controls to PRISTINE
state.
markAllAsUntouched()
Sets all controls to UNTOUCHED
state.
add()
Adds a new element to a form array. Prefer this method over push()
method available on classic reactive forms as you
don't need to explicitly pass a new form control to add : by default, NgxForm will add a new instance of the type of the
form array. You can set a default value to the new element and set a specific index.
DisableOn
The @DisableOn()
decorator allows you to control when to enable/disable a control. The decorated control will be
disabled
when the Observable
passed as an argument is truthy, and enabled otherwise.
If you want to use a context from providers, you can use a DisableOnFactory
and inject your providers.
Options can also be passed as a second argument of the decorator.
class UserForm {
@DisableOn(of(true))
@FormControl()
public surname: string;
@DisableOn(DisableOnFactory.of((provider: MyProvider) => provider.disableWithTimeout(), [MyProvider]))
@FormControl()
public disabledWithTimeoutAddress: string;
@DisableOn(DisableOnFactory.of((provider: MyProvider) => provider.disableWithTimeout(), [MyProvider]), {emitEvent: false})
@FormControl()
public disabledWithTimeoutAddressWithoutEvents: string;
}
⚠️ Any instance (built with
@BuildForm()
) of a form using this feature must haveunsubscribeOn
parameter provided in the config as follows :
class ConsumerComponent {
public readonly obs$: Observable<any> = EMPTY;
@BuildForm(() => UserForm, {unsubscribeOn: 'obs$'})
public form: NgxFormGroup<UserForm>;
}
OnValueChanges
The @OnValueChanges()
decorator allows you to call a method when a form value is changed. Pass the
control name(s) for which you wish to listen to changes. If you wish to listen to changes on the whole
form, you can apply the decorator without any parameters.
class SumForm {
@FormControl()
public a: number;
@FormControl()
public b: number;
@FormControl()
public sum: number;
@OnValueChanges(['a', 'b'])
public computeSum(instance: NgxFormGroup<SumForm>): void {
this.sum = this.a + this.b;
instance.setValue(this, {emitEvent: false});
}
}
⚠️ Any instance (built with
@BuildForm()
) of a form using this feature must haveunsubscribeOn
parameter provided in the config as follows :
class ConsumerComponent {
public readonly obs$: Observable<any> = EMPTY;
@BuildForm(() => UserForm, {unsubscribeOn: 'obs$'})
public form: NgxFormGroup<UserForm>;
}