@tc-libs/backoffice

Libreria Angular per interfacce backoffice basata su componenti standalone, Angular Material e integrazione diretta con @tc-libs/angular.

La libreria espone layout dashboard, tabelle dati, toolbar di filtro, helper per form/editing, componenti media, feedback utente e tipografia UI.

Requisiti

• Angular ^21.1.0
• @tc-libs/angular
• Angular Material e CDK
• animazioni Angular
• Font Awesome Angular
• ngx-image-cropper per TabImageComponent

Installazione

Nel progetto host installa la libreria insieme alle dipendenze usate dai componenti pubblici:

npm install @tc-libs/backoffice @tc-libs/angular
npm install @angular/cdk @angular/material @angular/animations
npm install @fortawesome/angular-fontawesome @fortawesome/fontawesome-svg-core
npm install @awesome.me/kit-d313f4f1a8 ngx-image-cropper

@tc-libs/backoffice usa direttamente servizi e modelli esportati da @tc-libs/angular, quindi i due pacchetti vanno installati insieme.

Bootstrap applicativo

Configurazione minima consigliata:

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
import {
  provideHttpClient,
  withFetch,
  withInterceptorsFromDi,
} from '@angular/common/http';
import {
  AUTH_CONFIGURATION_TOKEN,
  CONFIGURATION_TOKEN,
  TRANSLATION_CONFIGURATION_TOKEN,
} from '@tc-libs/angular';
import {
  DASHBOARD_CONFIGURATION_TOKEN,
  MenuItem,
  SEO_GENERATOR_TOKEN,
} from '@tc-libs/backoffice';

const MENU_ITEMS: MenuItem[] = [
  {
    icon: 'table',
    label: 'Catalogo',
    route: 'catalog',
    roles: [],
    subItems: [
      {
        icon: 'list',
        label: 'Prodotti',
        route: 'products',
        roles: [],
      },
    ],
  },
];

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideAnimationsAsync(),
    provideHttpClient(withFetch(), withInterceptorsFromDi()),
    {
      provide: CONFIGURATION_TOKEN,
      useValue: {
        server: {
          basePath: 'http://localhost:7002',
          apiBase: 'http://localhost:7002/api',
        },
        seo: {
          append: ' | Backoffice',
          title: 'Backoffice',
          description: 'Backoffice application',
        },
      },
    },
    {
      provide: AUTH_CONFIGURATION_TOKEN,
      useValue: { disabled: false },
    },
    {
      provide: SEO_GENERATOR_TOKEN,
      useValue: { enabled: false },
    },
    {
      provide: TRANSLATION_CONFIGURATION_TOKEN,
      useValue: {},
    },
    {
      provide: DASHBOARD_CONFIGURATION_TOKEN,
      useValue: {
        title: 'Backoffice',
        color: 'primary',
        menu: MENU_ITEMS,
      },
    },
  ],
};

Stili globali

La libreria usa componenti Angular Material ma non include un tema globale del progetto host. Assicurati di avere un tema Material attivo nel tuo styles.scss.

Se usi le icone testuali di Angular Material presenti nella toolbar filtri, carica anche il font Material Icons nel progetto host.

Esempio minimo:

@use '@angular/material' as mat;

@include mat.core();

$theme: mat.m2-define-light-theme(
  (
    color: (
      primary: mat.m2-define-palette(mat.$m2-blue-palette),
      accent: mat.m2-define-palette(mat.$m2-orange-palette),
    ),
  )
);

@include mat.all-component-themes($theme);

.snackbar-ok {
  --mdc-snackbar-container-color: #65a30d;
}

.snackbar-warn {
  --mdc-snackbar-container-color: #fbbf24;
  --mdc-snackbar-supporting-text-color: black;
}

.snackbar-error {
  --mdc-snackbar-container-color: #ef4444;
}

Layout dashboard

DashboardLayoutComponent

DashboardLayoutComponent e il contenitore principale del backoffice. Legge la configurazione dal token DASHBOARD_CONFIGURATION_TOKEN, mostra il menu laterale e delega il logout ad AuthService.

Routing tipico:

import { Routes } from '@angular/router';
import { DashboardLayoutComponent } from '@tc-libs/backoffice';

export const routes: Routes = [
  {
    path: '',
    component: DashboardLayoutComponent,
    loadChildren: () =>
      import('./pages/dashboard.routes').then((m) => m.DASHBOARD_ROUTES),
  },
];

MenuItem

Shape del menu:

type MenuItem = {
  icon: string;
  label: string;
  route?: string;
  subItems?: MenuItem[];
  roles: string[];
  startOpened?: boolean;
};

I ruoli vengono filtrati nel menu attraverso la direttiva *isGranted di @tc-libs/angular.

Se nel tuo progetto non hai ancora auth attiva, puoi impostare AUTH_CONFIGURATION_TOKEN con disabled: true.

Tabelle e listing

EntityTableComponent

EntityTableComponent e il componente principale per tabelle remote o locali.

Input piu usati:

• service: servizio che implementa IService<T>
• columns: definizione colonne
• displayedColumns: ordine colonne
• mappingFunction: mapper opzionale dei dati in ingresso
• actions: azioni disponibili (edit, remove, copy, send, confirm, toggleVisibility, home)
• dragDrop: abilita drag and drop
• localData: array locale, senza backend
• withoutPagination: carica e filtra client-side
• enum e enumHiddens: filtri enum persistiti nella toolbar
• hiddenToolbar: nasconde la toolbar filtri
• autoInit: utile quando devi aspettare route params o stato iniziale

Output disponibili:

• onEdit
• onRemove
• onCopy
• onSend
• onConfirm
• onToggleVisibility
• onToggleHome
• onDrop

Tipi colonna

I principali ENTITY_LIST_COLUMN_TYPE disponibili sono:

• STRING
• NUMBER
• PRICE
• THUMB
• DATE
• CREATED_AT
• UPDATED_AT
• ICONTRUEFALSE
• ICONSTRING
• HTML
• ACTION

Esempio con backend

import { Component, Injectable } from '@angular/core';
import {
  IDatabaseMongoEntity,
  PaginationService,
  ServiceAdminBase,
} from '@tc-libs/angular';
import {
  ENTITY_LIST_COLUMN_TYPE,
  EntityTableComponent,
  ITableColumn,
} from '@tc-libs/backoffice';

interface IProduct extends IDatabaseMongoEntity {
  title: { it: string };
  active: boolean;
}

@Injectable({ providedIn: 'root' })
class ProductAdminService extends ServiceAdminBase<IProduct> {
  override basePath = 'product';
  override entity = 'ProductEntity';
}

@Component({
  standalone: true,
  imports: [EntityTableComponent],
  template: `
    <tcbo-entity-table
      [service]="productService"
      [columns]="columns"
      [displayedColumns]="displayedColumns"
      [mappingFunction]="mappingFunction"
      [actions]="['edit', 'toggleVisibility']"
      visibilityStatusField="active"
      (onEdit)="edit($event)"
      (onToggleVisibility)="toggleVisibility($event)"
    />
  `,
})
export class ProductListComponent {
  displayedColumns = ['title', 'actions'];

  columns: ITableColumn[] = [
    {
      columnDef: 'title',
      type: ENTITY_LIST_COLUMN_TYPE.STRING,
      dbField: 'title.it',
      header: 'Titolo',
      mappedField: 'title',
    },
    {
      columnDef: 'actions',
      type: ENTITY_LIST_COLUMN_TYPE.ACTION,
      dbField: '',
      header: '',
      mappedField: '',
    },
  ];

  mappingFunction = (product: IProduct) => ({
    ...product,
    title: product.title.it,
  });

  constructor(
    public readonly productService: ProductAdminService,
    public readonly paginationService: PaginationService,
  ) {}

  edit(product: IProduct) {}
  toggleVisibility(product: IProduct) {}
}

Esempio con dati locali

<tcbo-entity-table
  [columns]="columns"
  [displayedColumns]="displayedColumns"
  [localData]="rows"
></tcbo-entity-table>

FilterToolbarComponent

FilterToolbarComponent e gia integrato dentro EntityTableComponent.

Funzioni principali:

• ricerca testuale con debounce
• filtri enum/select
• persistenza dello stato nei query params (options)
• supporto a joinServices per popolare select da altri endpoint
• modalita client-side quando withoutPagination e true

Nella maggior parte dei casi non serve usarlo direttamente: basta passare service, enum, enumHiddens e joinServices a EntityTableComponent.

Helper per pagine di editing

EntityEditNgModelComponent

Base class per schermate edit/create che lavorano direttamente sul modello:

export class ProductEditComponent extends EntityEditNgModelComponent<IProduct> {
  override entity = {} as IProduct;

  constructor(route: ActivatedRoute) {
    super(route);
  }

  protected override loadEntity() {
    return this.productService.getById(this.id!).pipe(map((x) => x.data));
  }

  save() {}

  override isDisabled() {
    return false;
  }
}

Metodi utili:

• setEntityAndTrack(entity)
• isDirty()

EntityEditFormComponent

Alternativa per pagine basate su FormGroup.

Metodi utili:

• setFormAndTrack(form)
• isDirty()

Media e SEO

TabImageComponent

Gestisce upload, crop e ordinamento immagini. Supporta:

• binding singolo con [(image)]
• binding multiplo con [(images)]
• upload via StorageAdminService
• crop tramite ngx-image-cropper
• drag and drop in modalita multi

Esempio immagine singola:

<tcbo-tab-image
  [(image)]="entity.thumb"
  title="Immagine principale"
  noImageTitle="Nessuna immagine presente."
  entity="ProductEntity"
></tcbo-tab-image>

Esempio gallery:

<tcbo-tab-image
  [(images)]="entity.images"
  [multi]="true"
  title="Gallery"
  noImageTitle="Nessuna immagine presente."
  entity="ProductEntity"
></tcbo-tab-image>

Input aggiuntivi:

• ratio
• format
• isLogo

entity deve contenere il nome backend usato da StorageAdminService durante l'upload.

TabSeoComponent

Editor rapido dei metadati SEO su entita con shape { seo: ISEO }:

<tcbo-tab-seo [(entity)]="entity"></tcbo-tab-seo>

Input disponibili:

• titleMaxLength
• descriptionMaxLength

ThumbComponent

Anteprima immagine standalone:

<tcbo-thumb [img]="imageUrl" [size]="'mini'" [hasBorder]="true"></tcbo-thumb>

Taglie supportate:

• micro
• mini
• base
• large
• logo

Feedback e componenti UI

SnackbarService

Metodi disponibili:

• ok({ message? })
• warn({ message? })
• error({ message? })

Ricorda di definire le classi globali snackbar-ok, snackbar-warn e snackbar-error nel CSS globale dell'app.

DialogDeleteComponent

Dialog pronto all'uso con MatDialog:

this.dialog.open(DialogDeleteComponent, {
  data: {
    subject: 'questo elemento',
    entity: 'Prodotto',
  },
});

Alla conferma il dialog chiude restituendo { confirmed: true }.

Altri componenti esportati

• BreadcrumbComponent
• ChipComponent
• EntityListItemComponent
• TableActionsComponent
• TableDateComponent
• LabelComponent
• DataComponent
• IconCheckComponent
• IconDragDropComponent
• IconLoginComponent
• IconSortingComponent
• IconTrueFalseComponent
• MenuItemComponent
• SidenavComponent

Esempi rapidi:

<tcbo-breadcrumb [text]="'Prodotti'" [link]="['/products']"></tcbo-breadcrumb>
<tcbo-chip [color]="'accent'">non salvato</tcbo-chip>
<tcbo-icon-true-false
  [condition]="row.active"
  trueTooltip="Attivo"
></tcbo-icon-true-false>
<tcbo-label>Nome</tcbo-label>
<tcbo-data>{{ row.title }}</tcbo-data>

Sviluppo locale

Comandi utili in questo workspace:

ng build backoffice
ng test backoffice
ng serve demo-bo

Il progetto dimostrativo che usa entrambe le librerie si trova in projects/demo-bo ed e la referenza migliore per esempi completi di integrazione.