Configurazione

La configurazione delle DataTables si divide in due fasi. La prima viene effettuata lato server mentre la seconda lato client

Nota

La configurazione lato client, se omessa, verrà effettuata automaticamente alla conclusione del caricamento della pagina con impostazioni di default. Se si volesse effettuare un inizializzazione differita dopo il caricamento della pagina sarà sufficiente chiamare DT.late("NOME_TABELLA")

Configurazione Server

Il sistema lato server è composto da due concetti:

Il modello

Il modello è un tipo che contiene tutti i dati che verranno trasmessi dal server.

La sorgente dati

La sorgente dati è rappresentata da un IDataTableDataProvider<T> (dove T è il tipo della sorgente dati) che deve fornire i dati con cui verrà compilato.

Importante

Tutti i tipi dei campi utilizzati del modello devono necessariamente essere ICustomType o tipi primitivi con mappatura a ICustomType registrata

Per poter definire un modello come DataTable sarà necessario aggiungere l’interfaccia IDataTableModel e implementare il metodo BuildTables. Al metodo verrà passata l’istanza condivisa di IDataTableShelf che permette di definire nuove tabelle.

Grazie alla shelf sarà possibile definire da 0 una nuova tabella (DefineTable) oppure estendere una tabella esistente con nome o permessi differenti (ExtendTableAs) senza dover riscrivere l’intera definizione.

Una volta iniziata la creazione della tabella sarà possibile aggiungere, modificare ed eliminare colonne. Per aggiungere una colonna sarà sufficiente riferirsi ad un campo nel modello e personalizzare la colonna a piacimento. Nel caso in cui si volesse configurare la colonna con funzionalità avanzate di datatables.net sarà sufficiente utilizzare il metodo Configure di IDataTableColumnBuilder per poter accedere ad una versione più avanzata delle opzioni della colonna.

Una volta terminata la configurazione della colonna sarà necessario fornire il IField di riferimento da utilizzare come sorgente dati

Nota

Durante la modifica di una colonna esistente non sarà necessario chiamare il metodo Done a meno che non si voglia modificare il field utilizzato come sorgente dati

Tramite il IDataTableBuilder è anche possibile aggiungere dei filtri utilizzati per restringere i dati visibili agli utenti secondo criteri personalizzati.

Questi filtri si suddividono in 3 tipi a seconda del livello di caching utilizzabile:

• User-based

  I filtri basati per utente vanno a dividere il sistema di caching nella modalità più granulare supportata e permettono di aggiungere filtri personalizzati per ogni singolo utente in modo specifico.

  Nota

  È sconsigliato l’utilizzo di questo layer se non necessario in quanto andrà ad appesantire notevolmente le operazioni in applicativi con basi utenti di dimensioni medio-grandi

• Permission-based

  I filtri suddivisi per permessi suddividono il sistema di caching in settori basati sui permessi a cui l’utente richiedente ha accesso (e.g. Filtri determinati dal ruolo dell’utente)

• Global-based

  Se presenti verranno applicati prima di ogni altro filtro e influenzeranno la visualizzazione per tutti gli utenti (e.g. Filti determinati dal ruolo della tabella)

Nota

Il sistema di caching andrà ad utilizzare la strategia più granulare tra quelle richieste. e.g.:

• Se inserisco un filtro per utente e uno globale il sistema utilizzerà una settorizzazione della cache per utente

• Se inserisco solo filtri globali il sistema utilizzerà una cache globale

• Se inserisco filtri globali e permissions-based il sistema utilizzerà una settorizzazione per permessi

Importante

Le referenze utilizzate all’interno di tutto il sistema possono essere modificate utilizzando la proprietà References esposta dall”IDataTableBuilder mappate dalla sorgente dati. Le references assegnate alla tabella sorgente verranno ignorate

Per poter utilizzare la tabella in una pagina sarà necessario inserire le seguenti righe nella view interessata (con T come tipo del modello interessato):

[@using Ingage.WebCore.Implementations.AspNetCore.Mvc]
@inject IDataTableEngine<T> DataTableEngine;

// [ ... ]

@this.Render(DataTableEngine)

Importante

Nel caso in cui sia necessario modificare, creare o eliminare righe da una tabella sarà necessario notificarlo al servizio IDataTableEngine o, più genericamente, IDataTableShelf per permettere ai layer di cache di aggiornarsi e servire dati up-to-date

È anche possibile registrare DataTableCacheStore come CacheStore per la sorgente dati in modo da non doversi preoccupare di aggiornare manualmente la cache

È anche possibile utilizzare il decoratore DataTableEventManager sulla classe della sorgente dati per registrare automaticamente gli eventi necesssari al mantenimento dei dati nel lifecycle di ITO [disponibile dalla v4 della suite ITO]

Configurazione Client

La configurazione lato client viene fatta tramite la classe DT e permette di modificare estensivamente tutte le impostazioni e feature delle datatables.

Per inizializzare la datatable è necessario chiamare la funzione statica DT.load("NOMETABELLA"). Essa ritornerà un oggetto promise-like che risolverà l’istanza di DT associata dopo la sua inizializzazione.

Nel caso in cui si voglia inizializzare la tabella in un secondo momento è possibile segnalarlo al sistema chiamando la funzione DT.late("NOMETABELLA"). Facendo ciò si prevenirà l’inizializzazione di default della tabella al termine del caricamento della pagina.

L’istanza DT permette di modificare la configurazione ottenuta dal server, aggiungere azioni, aggiungere tasti di esportazione e modificare le interazioni con la tabella

Modifica della configurazione

La configurazione può essere modificata riferendosi al valore DT.configuration ed è rappresentata dalle opzioni ufficiali di datatables.net.

Aggiunta e gestione azioni

Per azioni si intendono i tasti interattivi presenti solitamente nell’ultima colonna della tabella. Essi possono essere modificati utilizzando l’API DT.actions.

Importante

Se la colonna “actions” viene rimossa dalla configurazione le azioni non verranno visualizzate correttamente

Nota

Per poter utilizzare il sistema di azioni lato server è necessario impostare una colonna come primary key nella configurazione lato server