design-angular-kit

Design Angular Kit

Design Angular Kit è un toolkit basato su Bootstrap Italia
per la creazione di applicazioni web sviluppate con Angular.

italia.github.io/design-angular-kit

⚠️ Attenzione: questo codice è ancora in fase di sviluppo e non è pronto per essere utilizzato! Stiamo lavorando all'aggiornamento per portare il kit alla versione 1.0.0, commenti e contributi di tutta la community sono più che benvenuti! Se si necessita della vecchia versione il codice e la sua documentazione possono essere reperiti qua.

Verso la versione 1.0.0 📣

Sono partite le lavorazioni per l'aggiornamento del kit Angular a Bootstrap Italia 2 (basato su Bootstrap 5). Sul branch main potete trovare il codice dei lavori in corso e nella milestone Version 1.0.0 un piano preliminare delle attività. La vecchia versione è da considerarsi deprecata.

👉🏻 È possibile contribuire a questa nuova versione in vari modi:

• Con il proprio codice, prendendo in carico una issue tra quelle aperte e non già assegnate tra le issue di Angular Kit (è sufficiente anche un commento sulla issue per notificare la volontà di presa in carico).
• Attraverso la segnalazione di bug o miglioramenti al repository ufficiale di Angular Kit.
• Scrivendoci sul canale dedicato di Slack.

Commenti e contributi di tutta la community sono più che benvenuti! 🎉

Link utili

• Video Meetup Angular Roma: Angular, Bootstrap Italia e non solo..
• Demo Design Angular Kit
• Preview di Vercel (aggiornata ad ogni commit)
• Discussione sulla nuova release
• Milestone 1.0.0

Come iniziare

Design Angular Kit è disponibile su NPM, per installarlo su una applicazione esistente sulla quale provare la libreria (attualmente non stabile) esegui il comando

npm install design-angular-kit@unstable --save

Procedi a registrare DesignAngularKitModule nel tuo app.module.ts.

import {DesignAngularKitModule, ItComponentsModule} from 'design-angular-kit';

@NgModule({
  imports: [
    ...
    DesignAngularKitModule,
    ItComponentsModule // importa tutti i componenti della libreria
  ]
})

Configurazione custom della libreria

import {DesignAngularKitModule, DesignAngularKitInit} from 'design-angular-kit';

// Puoi aggiungere alla libreria una configurazione iniziale
const initConfig: DesignAngularKitInit | undefined = {
  /**
   * The initial path in the `href` attribute in the `IconComponent` component
   * @default './bootstrap-italia/dist/svg/sprites.svg'
   */
  iconHref: string | undefined,
};

@NgModule({
  imports: [
    ...
    DesignAngularKitModule.forRoot(initConfig)
  ]
})

Usa ItComponentsModule per importare tutti i componenti della libreria, in alternativa puoi importare solo i componenti/moduli di cui hai bisogno, ad es. Alert, Paginazione e Breadcrumb.

import {ItAlertComponent, ItPaginationComponent, ItBreadcrumbsModule} from 'design-angular-kit';

@NgModule({
  imports: [
    ItAlertComponent, 
    ItPaginationComponent, 
    ItBreadcrumbsModule // Include ItBreadcrumbComponent e ItBreadcrumbItemComponent 
  ],
})
export class YourAppModule {
}

@Component({
  selector: 'app-product',
  standalone: true,
  imports: [ItAlertComponent],
  templateUrl: './product.component.html'
})
export class ProductComponent {
}

Importazione stili bootstrap-italia

Configura gli stili richiesti nel file styles.scss. Importa la libreria SCSS come mostrato nell'esempio qui sotto.

// Importazione libreria SCSS di bootstrap-italia
@import "bootstrap-italia/src/scss/bootstrap-italia";

Come personalizzare e sovrascrivere le variabili di default della libreria (es. colori, font-family, misure, ecc.)

Bootstrap Italia eredita ed estende tutte le variabili di default di Bootstrap, sovrascrivendo alcuni valori in fase di compilazione e impostandone di nuovi all’occorenza. Un esempio fra tutti è il valore del colore $primary che in Bootstrap Italia è rappresentato dal colore blu #0066CC, tipico della libreria.

L’utilizzo del blu #0066CC dovrebbe però essere riservato alle amministrazioni centrali dello Stato, e quindi ci si può trovare nella condizione di dover personalizzare i valori delle variabili colore di Bootstrap Italia, impostando nuovi valori per le proprie necessità.

Questo colore e le altre tonalità vengono generate a partire dalla terna HSB, pertanto occorre modificare le variabili primary-h, primary-s e primary-b. Per avere la corrispondenza tra valore esadecimale del colore e HSB si può utilizzare il portale rgb.to, ad esempio https://rgb.to/0066CC.

Di seguito un esempio di file styles.scss con la personalizzazione dei colori. Le personalizzazioni delle variabili devono sempre essere effettuate prima dell'importazione del file bootstrap-italia.scss

// modifica completa del template: è possibile ricompilare la libreria modificando alcune variabili SCSS

// Per l'override del colore $primary della palette in formato HSB (colore #FF3333 https://rgb.to/ff3333):
$primary-h: 0;
$primary-s: 80;
$primary-b: 100;

// Per l'override della famiglia di caratteri
$font-family-serif: 'Custom Font', Georgia, serif;
$font-family-sans-serif: 'Custom Font', Arial, Helvetica, sans-serif;
$font-family-monospace: 'Custom Font', 'Courier New', Courier, monospace;

// Importazione libreria SCSS di bootstrap-italia
@import 'bootstrap-italia/src/scss/bootstrap-italia';

Supporto icone e assets

Per aggiungere il supporto icone/assets, modifica il tuo angular.json aggiungendo:

 "assets": [
    ...
    {
      "glob": "**/*",
      "input": "./node_modules/bootstrap-italia/",
      "output": "/bootstrap-italia/"
    }
  ]

Supporto i18n (localizzazione)

La libreria usa ngx-translate per aggiungere le localizazioni i18n.

Modifica il tuo angular.json aggiungendo:

 "assets": [
    ...
    {
      "glob": "**/*",
      "input": "./node_modules/design-angular-kit/assets/i18n",
      "output": "/bootstrap-italia/i18n/"
    }
  ]

Localizzazione esistente

Se utilizzi già i file di localizzazione nella tua app, puoi utilizzare la libreria ngx-translate-multi-http-loader per caricare i file di localizzazione dell'app e di design-angular-kit

Modifica nel tuo app.module.ts:

@NgModule({
  imports: [
    ...
    HttpClientModule,
    TranslateModule.forRoot({
      loader: {
        provide: TranslateLoader,
        useFactory: (http: HttpBackend) => new MultiTranslateHttpLoader(http, [
          './bootstrap-italia/i18n/', // Load library translations first, so you can edit the keys in your localization file
          './assets/i18n/' // Your i18n location
        ]),
        deps: [HttpBackend]
      },      
      defaultLanguage: 'it'
    }),
    DesignAngularKitModule
  ]
})

Se vuoi personalizzare le nostre label puoi aggiungere le localizzazioni nei tuoi file json, sovrascrivendo le chiavi del json della libreria.

Puoi utilizzare le label localizzate di design-angular-kit nella tua applicazione, ad esempio {{'it.errors.required-field' | translate}}. Vedi le nostre label

Localizzazione non esistente

Se non utilizzi i file di localizzazione nella tua app, devi aggiungere il provider TranslateStore nel tuo app.module.ts:

@NgModule({
  imports: [
    ...
    DesignAngularKitModule,
  ],
  providers: [
    TranslateStore
  ],
})

Se vuoi personalizzare le nostre label:

• Non includere il supporto i18n nel tuo angular.json ma crea i tuoi file di localizzazione personalizzati nella tua cartella assets/bootstrap-italia/i18n/ (crea il percorso se non esiste).
• Il json deve avere questo formato.

Supporto animazione

La libreria usa BrowserAnimationsModule per gestire alcune animazioni.

Per abilitarle, bisogna aggiungere al tuo app.module.ts il modulo :

imports: [
  ...
  BrowserAnimationsModule
]

Segnalazione bug e richieste di aiuto

Vuoi segnalare un bug o fare una richiesta?

Prima di tutto assicurati che sia un problema relativo al tema Design Angular Kit e non alla libreria Bootstrap Italia da cui deriva (in tal caso puoi fare riferimento al repository di Bootstrap Italia), poi dai un'occhiata a come creare una issue.

Come contribuire

Vorresti dare una mano su Design Angular Kit? Sei nel posto giusto!

Se non l'hai già fatto, inizia spendendo qualche minuto per approfondire la tua conoscenza sulle linee guida di design per i servizi web della PA, e fai riferimento alle indicazioni su come contribuire a Design Angular Kit.

A questo punto, è necessario impostare il tuo ambiente locale per la compilazione dei file sorgente e la generazione della documentazione:

1. Clonare il progetto

git clone https://github.com/italia/design-angular-kit.git

1. Nella cartella di progetto installare le dipendenze

npm i

1. Lanciare l'applicazione in locale

npm run start

1. Per eseguire i test di unità eseguire il comando

npm run test

Contributor della libreria

Un grazie speciale a chi ha reso possibile lo sviluppo di questa nuova versione!

Cristian Borelli	Antonino Bonanno	NetService	Alessio Napolitano

---

Tutti i contributor (made with contributors-img)

Changelog

1.0.0-20 (2023-11-30)

Bug Fixes

• form input label (2180ab5)
• input number editable when disabled (364fac6)