@richnologies/forms v0.9.3

@richnologies/forms

Extra functionality to deal with forms. Validators and soon more

Features

• Validators
• Error Hint Handler

Installation

To install this library, run:

$ npm install @richnologies/forms --save

Using the library

Import the RFormsModule into the application

This module does not require any configuration

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';

// Import your library
import { RFormsModule } from '@richnologies/forms';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    RFormsModule,
    LibraryModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Once imported, it can be used both for Template Driven and Reactive Forms

Validators

This module provides some common validators so they are easier to use than the general pattern Validator.

Template Driven Froms

<!-- You can now use your library component in app.component.html -->
<form novalidate #form="ngForm" (onSubmit)="onSubmit(form)">
    <input type="text" ngModel name="email" required rEmailValidator>
    <input type="text" ngModel name="phone" rSpainPhoneValidator>
    <input type="text" ngModel name="zipCode" required rSpainZipCodeValidator>
    <input type="text" ngModel name="coordinate" rCoordinateValidator>
    <input type="text" ngModel name="ip" required rIpValidator>
    <input type="text" ngModel name="url" required rUrlValidator>
    <input type="text" ngModel name="_id" required rMongoIdValidator>
    <input type="password" ngModel name="password" required rPasswordStrengthValidator="50">
</form>

Reactive Forms

// hello-world.html

<form novalidate [formGroup]="form" (onSubmit)="onSubmit(form)">
    <input type="text" formControlName="email">
    <input type="text" formControlName="phone">
    <input type="text" formControlName="zipCode">
    <input type="text" formControlName="coordinate">
    <input type="text" formControlName="ip">
    <input type="text" formControlName="url">
    <input type="text" formControlName="_id">
</form>

import { Component, OnInit } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

import * as RValidators from '@richnologies/forms';

@Component({
    selector: 'app-hello-world',
    templateUrl: './hello-world.html'
})
export class FormComponent implements OnInit {
    form: FormGroup;
    
    constructor(private fb: FormBuilder) {}
    
    ngOnInit() {
        this.form = this.fb.group({
           email: ['', [Validators.required, RValidators.emailValidator]],
           phone: ['', [RValidators.phoneValidator]],
           zipCode: ['', [Validators.required, RValidators.zipCodeValidator]],
           coordindate: ['', [RValidators.coordinateValidator]],
           ip: ['', [Validators.required, RValidators.ipValidator]],
           url: ['', [Validators.required, RValidators.urlValidator]],
           _id: ['', [Validators.required, RValidators.mongoIdValidator]],
           password: ['', [Validators.required, RValidators.passwordStrengthValidator(50)]]
        });
    }
}

Password Strength Validator

The password strength validator allow check if a password is weak or strong. Every password gets a strength score (0 - 100). The validator needs a parameter, the trigger, with is the minimum score for a password to be consider strong, 50 by default.

A special function #passwordMetter can be used to determine the score of any password.

import { passwordMetter } from '@richnologies/forms';

passwordMetter('123456');

Optional Validator (only for ReactiveForms)

It is a high order validator. It will get as a parameter any validator and returns a new validator. This new validator accept any value from the validator passed as parameter and also the empty value

import { Component, OnInit } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

import { optionalValidator, emailValidator } from '@richnologies/forms';

// 'mail@example.com': valid
// '': valid
// 'mail@example: not valid
const optionalEmailValidator = optionalValidator(emailValidator);

@Component({
    selector: 'app-hello-world',
    templateUrl: './hello-world.html'
})
export class FormComponent implements OnInit {
    form: FormGroup;
    
    constructor(private fb: FormBuilder) {}
    
    ngOnInit() {
        this.form = this.fb.group({
           email: ['', [optionalEmailValidator]]
        });
    }
}

Error Hint Handler

This component is meant to work as a hint message generator

It takes two inputs:

• rErrorHint
• control

Error hint is an object when each key is a possible error code, and the value for each key is the desired error message when that error happend

Control is a reference to the form control. The directive will update the inner HTML of the host element to represent the error message.

It is important to note that the order of validators matter, since the error to be display is the first to be founded. So for example in the case of the email, if email-validator is passed first to the form builder, the required error message will never be displayed, since every time is not set is also not valid.

// hello-world.html

<form novalidate [formGroup]="form" (onSubmit)="onSubmit(form)">
    <input type="text" formControlName="email">
    <span [rErrorHint]="errors.email" [control]="form.get('email')">
    </span>
    <input type="text" formControlName="phone">
    <input type="text" formControlName="zipCode">
    <input type="text" formControlName="coordinate">
    <input type="text" formControlName="ip">
    <input type="text" formControlName="url">
</form>

import { Component, OnInit } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

import * as RValidators from '@richnologies/forms';

@Component({
    selector: 'app-hello-world',
    templateUrl: './hello-world.html'
})
export class FormComponent implements OnInit {
    form: FormGroup;

    errors = {
        email: {
            required: 'The email is required',
            'email-validator': 'The email is not valid'
        }
    };
    
    constructor(private fb: FormBuilder) {}
    
    ngOnInit() {
        this.form = this.fb.group({
           email: ['', [Validators.required, RValidators.emailValidator]],
           phone: ['', [RValidators.phoneValidator]],
           zipCode: ['', [Validators.required, RValidators.zipCodeValidator]],
           coordindate: ['', [RValidators.coordinateValidator]],
           ip: ['', [Validators.required, RValidators.ipValidator]],
           url: ['', [Validators.required, RValidators.urlValidator]]
        });
    }
}

Testing

The following command run unit & integration tests that are in the tests folder, and unit tests that are in src folder:

npm test 

Building

The following command:

npm run build

• starts TSLint with Codelyzer
• starts AoT compilation using ngc compiler
• creates dist folder with all the files of distribution

To test locally the npm package:

npm run pack-lib

Then you can install it in an app to test it:

npm install [path]to-library-[version].tgz

Publishing

npm run publish-lib

Documentation

To generate the documentation, this starter uses compodoc:

npm run compodoc
npm run compodoc-serve 

License

MIT © Ricardo Sánchez Gregorio