How to: Formly

Parte 1: Introduzione, installazione ed esempio

Salvatore Sabbia

Introduzione

Ogni sviluppatore web che utilizza Angular sa bene che i form sono gli elementi più comuni da implementare all'interno di una web app.
Angular mette a disposizione diversi strumenti per l'implementazione dei form (template driven forms, reactive forms), ma se dobbiamo implementarne tanti e con una certa complessità, la gestione della parte di template e della logica di validazione e visualizzazione può diventare difficile da realizzare e mantenere.

Per semplificare il lavoro di creazione e gestione dei form, in questo articolo vi parlerò di Formly.

Formly la libreria Open Source di Angular

Formly è una libreria open source per Angular che permette di creare form a partire dalla definizione di una struttura in JSON. Ciò rende estremamente facile e veloce la creazione ed il mantenimento di form, sia semplici che complessi. Ecco le caratteristiche principali:

Generazione automatica di form
Facile da estendere tramite la definizione di field, validatori e wrapper personalizzati
Supporto di differenti formati: Formly Schema, JSON Schema.
Supporto di differenti temi tra cui:
- Bootstrap
- Material
- Ionic
- PrimeNG
- Kendo

"less Html, more Javascript"
L'idea principale di Formly in poche parole: è meno HTML in favore di Javascript

Esempio di template HTML di un classico form

<form>
    <div class="form-group">
      <label for="inputEmail1">Email address</label>
      <input type="email" class="form-control" id="inputEmail1" placeholder="Enter email" [(ngModel)]="user.email">
    </div>
    <div class="form-group">
      <label for="inputPassword1">Password</label>
      <input type="password" class="form-control" id="inputPassword1" placeholder="Password" [(ngModel)]="user.password">
    </div>
    <div class="form-group">
      <label for="inputFile">File input</label>
      <input type="file" id="inputFile" [(ngModel)]="user.file">
      <p class="help-block">Example block-level help text here.</p>
    </div>
    <div class="checkbox">
      <label>
        <input type="checkbox" [(ngModel)]="user.checked"> Check me out
      </label>
    </div>
    <button type="submit" class="btn btn-default" (click)="submit(user)">Submit</button>
  </form>

Esempio di form realizzato con Formly

<form [formGroup]="form" (ngSubmit)="onSubmit(model)">
    <formly-form [form]="form" [fields]="fields" [model]="model"></formly-form>
    <button type="submit" class="btn btn-default">Submit</button>
 </form>

Installare Formly all'interno di un progetto Angular

Per installare ed integrare Formly all'interno di un progetto Angular basta lanciare il seguente comando:

ng add @ngx-formly/schematics --ui-theme=bootstrap

L'opzione ui-theme permette di selezionare il tema da installare insieme al modulo principale. In questo caso utilizzeremo Bootstrap.

Una volta installato, FormlyModule sarà importato nell'AppModule:

import { AppComponent } from './app.component';
import { ReactiveFormsModule } from '@angular/forms';
import { FormlyModule } from '@ngx-formly/core';
import { FormlyBootstrapModule } from '@ngx-formly/bootstrap';

@NgModule({
  imports: [
    BrowserModule
    ReactiveFormsModule,
    FormlyModule.forRoot(),
    FormlyBootstrapModule
  ],
  ...
})
export class AppModule { }

Un esempio pratico di Login Form

In questo esempio vedremo come realizzare un semplice form di login.

Per creare un form, nel template HTML basta includere il tag <formly-form> all'interno del tag <form> nel seguente modo:

<form [formGroup]="form" (ngSubmit)="onSubmit()">
    <formly-form [form]="form" [fields]="fields" [model]="model" ></formly-form>
    <button class="btn btn-primary">LOGIN</button>
 </form>

Il componente <formly-form> è il container principale e si occupa di creare e visualizzare i vari campi del form.

Accetta i seguenti input:

form : l'instanza del form che permette di tracciare i valori dei campi e lo stato di validazione
fields : la configurazione dei campi del form
model : il modello di dati rappresentato dal form

Per configurare il form all'interno del nostro componente occorre quindi definire questi 3 campi:

import { Component } from '@angular/core';
import { FormGroup } from '@angular/forms';
import { FormlyFieldConfig, FormlyFormOptions } from '@ngx-formly/core';

@Component({
    selector: 'app-form-login',
    templateUrl: './form-login.component.html',
    styleUrls: ['./form-login.component.scss']
})
export class FormLoginComponent {

    form: FormGroup = new FormGroup({});
    model: any = {
        username: null,
        password: null
    };
    fields: FormlyFieldConfig[] = [
        {
            key: 'username',
            type: 'input',
            templateOptions: {
                label: 'Username',
                placeholder: 'Enter username',
                required: true,
            },
        },
        {
            key: 'password',
            type: 'input',
            templateOptions: {
                label: 'Password',
                type: 'password',
                placeholder: 'Enter password',
                required: true,
            },
        }
    ];;

    onSubmit() {
        if (this.form.valid) {
            console.log(this.model);
        }
    }

}

Come potete vedere tramite la definizione dei *fields* è possibile configurare tutti gli aspetti del form. Ogni *field* accetta diverse opzioni e parametri:

key : chiave che permette di collegare il valore del campo al model
type : il tipo di campo da visualizzare; tra le varie opzioni disponibili sono presenti input, textarea, checkbox, select, datepicker, ecc.. (possono variare in base al tema utilizzato); inoltre è possibile definire dei tipi di campo personalizzati
templateOptions : in questo oggetto è possibile definire tutti i parametri che verranno utilizzati dal template

Sono disponibili altri parametri con i quali sarà possibile aggiungere ai vari campi varie funzionalità, tra cui:

valore di default
eventuali classi css da applicare al campo
validazione con relativo messaggio di errore
visibilità condizionale
ecc...

Per maggior informazioni su tutte le opzioni e le funzionalità fare riferimento alla documentazione.

Nelle prossime parti vedremo alcune funzionalità più avanzate, come l'utilizzo di custom validator e la creazione di componenti e wrapper personalizzati. Stay Tuned!

Recovery MySQL

Gianluigi Tiesi