OGGETTO GRIGLIA | QualiWare Docs

Descrizione

L’oggetto Griglia consente la visualizzazione di informazioni sotto forma di tabella modificabile. Dalla release release 2023.02.00 dalla è disponibile una nuova versione, attivabile assegnando la proprietà NuovoLayout=true. Le funzionalità aggiunte o modificate sono evidenziate in colore giallo. Nel paragrafo Migrazione sono riportate alcune indicazioni utili ad agevolare la migrazione delle griglie esistenti al nuovo layout.

NOTA IMPORTANTE: per motivi di performance legati alla struttura dell’oggetto, se NuovoLayout=true eventuali aggiornamenti di altri oggetti del form effettuati all’interno dei gestori di questi eventi (ad esempio l’assegnazione di un testo ad un’etichetta, oppure l’assegnazione di un valore ad un campo), non comporteranno l’aggiornamento grafico del form . Per aggiornare anche visivamente questi oggetti, è necessario inserirli in un oggetto contenitore con la proprietà ContenitoreAggiornamento assegnata a true, e, nel gestore dell’evento, richiamare il metodo UpdateContainer dell’oggetto form specificando come parametro il contenitore stesso.

Proprietà specifiche

Oltre alle proprietà comuni (vedi) sono disponibili le seguenti proprietà:

NuovoLayout: se True viene utilizzato il layout aggiornato disponibile dalla versione 2023.02.00. Il default è True per gli oggetti creati con questa versione o successiva.
CampoFiltro e ValoreCampoFiltro:
In un form è possibile inserire più di una griglia. Dal momento che i dati delle griglie vengono memorizzati nella tabella DOC_ROWS del database, è necessario definire il set di righe che fa riferimento a ciascuna griglia. Lo si può fare definendo la proprietà CampoFiltro indicando il campo sul quale verrà effettuato il filtro, e la proprietà ValoreCampoFiltro nella quale verrà specificato il valore da controllare. Nella griglia verranno quindi caricate le sole righe della tabella DOC_ROWS che soddisfano il filtro, e ogni riga aggiunta verrà memorizzata con il campo specificato nella proprietà CampoFiltro assegnato al valore specificato nella proprietà ValoreCampoFiltro.
Tutte le griglie presenti in un form dovranno avere lo stesso valore della proprietà CampoFiltro e valori differenti della proprietà ValoreCampoFiltro, in modo da fare riferimento a set di righe di DOC_ROWS diversi.
GrigliaFiglia e CampoFiltroGrigliaFiglia:
Se NuovoLayout=true è possibile collegare due griglie in modo da mostrare, per ogni riga della prima, le corrispondenti righe della seconda, il cui nome deve essere specificato nella proprietà GrigliaFiglia. Le due griglie sono collegate da una colonna in comune, che deve essere inserita nella proprietà CampoFiltroGrigliaFiglia. Tale campo deve essere collegato ad una colonna in entrambe le griglie. Sia nella griglia principale che in quella figlia, tale colonna deve avere Richiesto=true e ChiavePrimaria=true. Nella griglia figlia la colonna verrà automaticamente nascosta.
Colonne:
Questa proprietà consente di definire l’insieme delle colonne che comporranno la griglia. Ciascuna colonna disporrà a sua volta di proprietà specifiche che sono elencate nel seguito.
- Intestazione: intestazione della colonna
- Larghezza: larghezza della colonna in pixel
- Campo: campo della tabella DOC_ROWS collegato alla colonna
- ChiavePrimaria: se true, la colonna fa parte dell’insieme che compone la chiave primaria
- FormatoNumerico: consente di specificare quanti decimali visualizzare se la colonna è di tipo numerico
- QueryLista: query da utilizzare per visualizzare i dati fra i quali è possibile scegliere il valore del campo. Per fare in modo che i valori ritornati dalla query vengano mostrati in una lista a discesa, anzichè in una finestra a parte attivata da un apposito pulsante, specificare l’alias “DROPDOWN_VALUE” nel campo che dovrà essere utilizzato per alimentare la lista a discesa stessa. E’ possibile utilizzare, nei filtri presenti nella query, i valori dei campi presenti nel form, utilizzando come nome di parametro il nome del campo del database cui sono collegati o, per gli oggetti non collegati, il nome dell’oggetto stesso.
- Richiesto: se true è obbligatorio l’inserimento dei dati nella colonna
- SeparatoreMigliaia: se true abilita la visualizzazione del separatore delle migliaia nelle colonne di tipo numerico
- SolaLettura: se true la colonna è a sola lettura
- TuttoMaiuscole: se true il valore inserito verrà convertito in tutte maiuscole
- VincolatoAllaLista: se true non è possibile inserire un valore manualmente ma può solo essere scelto dalla lista
L’insieme delle righe può inoltre essere caratterizzato da una o più colonne che fungono da chiave primaria, identificate assegnando la proprietà ChiavePrimaria=true, impedendo quindi l’inserimento di righe che presentano lo stesso valore per tali colonne.

NOTA: se una colonna contiene immagini codificate base64, queste vengono visualizzate automaticamente nella cella, con la possibilità di aprirle ingrandite cliccandovi sopra.
DisabilitaPaginazione: se true i record non vengono organizzati in pagine. Se NuovoLayout=true questa impostazione viene ignorata in quanto la paginazione è sempre disabilitata.
NonAggiornareAlCambioRiga: se true la griglia non viene aggiornata quando viene cambiata la riga. Questo migliora le prestazioni.
AltezzaRigaMax: determina la massima altezza della riga in pixel. Se NuovoLayout=false viene ignorato.
ConsentiTrascinamento: assegnare a True per consentire il trascinamento della riga su un altro oggetto Griglia e implementare il Drag/Drop come spiegato in questo esempio, o su un oggetto Calendario, come riportato in questo esempio.
TestoACapo: Se true, consente l’andata a capo del testo nell’intestazione e nelle celle. Se NuovoLayout=false viene ignorato.
ScrollVirtuale: assegnare a True per caricare i record dinamicamente in fase di scroll. Valido solo se NuovoLayout=true.
MostraCasellaRicerca: assegnare a True per visualizzare la casella di ricerca. Valido solo se NuovoLayout=true
TestoACapo: Se true, consente l’andata a capo del testo nell’intestazione e nelle celle. Se NuovoLayout=false viene ignorato.

Eventi specifici

EventoCambiaRiga (sulla griglia)
Evento attivato ad ogni cambiamento della riga selezionata da parte dell’utente. Può essere utilizzato per intraprendere azioni come ad esempio l’aggiornamento di altri oggetti del form sulla base dei valori della riga sui cui ci si è posizionati.
N.B. questo evento viene eseguito anche quando il cambiamento di riga viene effettuato da programma. E’ possibile evitarlo assegnando la proprietà StopExecuteChangeRow a True.
EventoSalvaRiga (sulla griglia)
Evento attivato ad ogni salvataggio della riga corrente, sia a seguito del cambio della riga, sia a seguito del richiamo del metodo SaveRow(). L’evento viene eseguito prima dell’effettivo salvataggio, e può essere utilizzato per verificare la coerenza dei campi. Se l’evento ritorna il valore True, il salvataggio viene eseguito, se ritorna False il salvataggio non viene eseguito e l’eventuale cambio riga non viene effettuato.
EventoAggiungiRiga (sulla griglia)
Evento attivato al momento dell’aggiunta di una riga. Può essere usato per impedire l’aggiunta, ritornando il valore “False”. Utilizzabile se NuovoLayout=true.
EventoEliminaRiga (sulla griglia)
Evento attivato al momento dell’eliminazione di una riga. Può essere usato per impedire l’aggiunta, ritornando il valore “False”. Utilizzabile se NuovoLayout=true.
EventoCambia (sulle colonne)
evento attivato al cambiamento del valore di una cella appartenente alla colonna cui l’evento è collegato. Può essere utilizzato per
– assegnare altri campi in base al valore inserito nella cella
– verificare la validità del valore inserito dando eventualmente un messaggio all’utente.
– in versione client, per invalidare il valore inserito ritornando il valore “false”. Se NuovoLayout=”true” è anche possibile ritornare il testo che dovrà essere visualizzato in caso di valore non valido.
Di seguito un esempio di codice client che consente di invalidare il valore e di modificare il colore della cella:
```
if ($('#<Grid1>').readField("NUMBER1")<2) {
  $.QualiWare.alert("Il numero deve essere maggiore o uguale a 2","ATTENZIONE");
  return false
}

if ($('#<Grid1>').readField("NUMBER1")>=10) {
  $('#<Grid1>').assignField("FLAG1",true)
  $('#<Grid1>').getCurrentRowCell("NUMBER1").css("background-color","red")	
}
```
EventoDatiCaricatiClient (sulla griglia)
Evento attivato lato client solo se NuovoLayout=true al termine di ogni caricamento asincrono dei dati. Può essere usato per modificare gli stili delle celle.
EventoEditCellaClient (sulle colonne)
evento attivato lato client nel momento in cui l’utente tenta di entrare in una cella per modificarne il valore. Può essere utilizzato per disabilitare la modifica senza la necessità di un’interazione con il server. L’evento, scritto in linguaggio Javascript, deve ritornare il valore “false” se la modifica deve essere inibita. Altrimenti può ritornare il valore “true” o nessun valore. Di seguito un esempio di utilizzo:
```
if ($('#<Grid1>').readField("CUSTOM1")==2)
  return false
```
EventoRenderCellaClient (sulla griglia)
Evento attivato lato client solo se NuovoLayout=true al momento di effettuare il render di ogni cella. Può essere usato per modificare i valori visualizzati, inserendo, ad esempio, delle icone, come riportato nell’esempio riportato di seguito. Nel codice è possibile usare la variabile “field”, che contiene il nome della campo, la variabile “value” contiene il valore della cella, e la variabile “row”, che contiene il valore di tutti i campi della griglia. L’evento deve ritornare il valore da visualizzare, che può contenere codice HTML.
Di seguito un esempio di utilizzo, che visualizza sulla colonna associata al campo NUMBER1 una freccia verde verso l’alto se il valore è maggiore di 10, una freccia rossa verso il basso altrimenti.
```
if (field=='NUMBER1')
    if (value>10)
        return value.toString()+' <span class="mdi mdi-arrow-up-bold" style="color:green"></span>'
    else
        return value.toString()+' <span class="mdi mdi-arrow-down-bold" style="color:red"></span>'
```

Per maggiori informazioni sugli eventi leggi qui.

Proprietà utilizzabili da codice lato Server (VB.NET/C#)

Enabled As Boolean – se viene settato a False, disabilita la modifica dei valori nelle celle della griglia.
NewRow As Boolean – proprietà a sola lettura che ritorna True se la riga corrente è nuova e non è quindi stata salvata nemmeno una volta.
StopExecuteChangeRow As Boolean – se viene assegnato a True, non viene eseguito l’EventoCambiaRiga.

Metodi utilizzabili da codice lato Server (VB.NET/C#)

Nel codice degli eventi è possibile utilizzare i seguenti metodi:

AddRow() As Boolean – aggiunge una riga vuota e spostare il cursore sulla riga aggiunta che diventa la riga corrente (solo versione web)
AddRow(Optional ByVal ShowEdit As Boolean = False) As Boolean – aggiunge una riga vuota e se il parametro è True mostra la scheda di editing dei valori della riga (solo versione mobile)
AssignField(ByVal field As String, ByVal value As String) As String – assegna al campo specificato nel primo parametro il valore specificato nel secondo, per la riga corrente
AssignField(ByVal field_set As AssocArray) As String – prende come input un AssocArray che ha come chiavi i nomi dei campi e come valori delle stringhe. Assegna ogni stringa come valore di ciascun campo esistente, per la riga corrente.
Count() As Integer – restituisce il numero totale delle righe caricabili nella griglia
DeleteAllRows() As Boolean – cancella tutte le righe attualmente mostrate dalla griglia
DeleteRow() As Boolean – cancella la riga corrente
EndOfRows() As Boolean – restituisce True se il puntatore della riga corrente è oltre l’ultima riga
FilterRows(ByVal condition As String) As Boolean – filtra le righe della griglia in base alla condizione SQL passata come argomento. Per annullare tutti i filtri presenti basta passare una stringa vuota. NOTA: per la versione client/server non è possibile utilizzare l’operatore like (**)
GetCellValue(Byval Row As Integer, Byval field As String)(*) – restituisce il valore contenuto nella cella corrispondente alla colonna collegata al campo field nella riga Row
GoToRow(ByVal bookmark As Object) As Boolean – muove il cursore sulla riga corrispondente al segnalibro specificato
LocateRow(ByVal condition As String) As Boolean – muove il cursore sulla prima riga della griglia che soddisfa la condizione SQL passata (**). Restituisce un valore booleano che indica se è stata trovata una riga. NOTA: la ricerca parte dalla riga selezionata al momento. Può quindi essere necessario chiamare prima MoveFirst() per ottenere i risultati desiderati.
MoveFirst() As Boolean – sposta il puntatore delle righe sulla prima riga tra quelle mostrate, ritornando False se l’operazione non è riuscita, ad esempio perchè non vi sono righe
MoveLast() As Boolean – sposta il puntatore delle righe sull’ultima riga tra quelle mostrate, ritornando False se l’operazione non è riuscita, ad esempio perchè non vi sono righe
MoveNext() As Boolean – sposta il puntatore delle righe sulla riga successiva a quella corrente, ritornando False se si era sull’ultima riga e il puntatore è andato oltre la fine dell’insieme di righe
MovePrevious() As Boolean – sposta il puntatore delle righe sulla riga precedente a quella corrente, ritornando False se si era sulla prima riga e il puntatore è andato prima dell’inizio dell’insieme di righe
ReadField(ByVal field As String) As Object – restituisce il valore del campo specificato nel parametro, per la riga corrente
Refresh() – aggiorna la visualizzazione della griglia
RowBookmark() As Object – restituisce un oggetto che rappresenta il segnalibro della riga corrente, ed è possibile utilizzarlo per riposizionarsi successivamente sulla riga
RowCount()(*) – restituisce il numero totale delle righe caricate nella griglia. A differenza del metodo Count(), nel caso di griglie paginate restituisce il solo numero delle griglie visualizzate.
SetColumnReadOnly(ByVal columnname As String, ByVal readonly As Boolean) – rende a sola lettura la colonna corrispondente al campo columnname se readonly = True, la rende editabile se readonly = False.
SetColumnWidth(ByVal columnname As String, ByVal width As Integer) – definisce la larghezza della colonna corrispondente al campo columnname. Se width = 0, la colonna viene nascosta.
SetColumnHeaderText(ByVal columnname As String, ByVal text As String) – definisce il testo dell’intestazione della colonna corrispondente al campo columnname.
SetColumnHidden(ByVal columnname As String, ByVal hidden As Boolean) – definisce se la colonna corrispondente al campo columnnameè nascosta (parametro hidden=true) o meno (parametro hidden=false).
SetColumnItems(ByVal field As String, ByVal items As dbArray) – assegna alla casella a discesa corrispondente al campo specificato nel primo parametro gli elementi specificati nel secondo parametro. Perché il metodo funzioni, è necessario che la colonna in questione abbia una query fittizia nell’apposita proprietà che termini con as DROPDOWN_VALUE. In seguito alla chiamata di questo metodo, è poi necessario fare un refresh della griglia tramite Refresh().
SetFocusOnColumn(ByVal columnname As String) – rende attiva la cella corrispondente al campo columnname della riga corrente, entrando in modalità di modifica.
SaveRow() As Boolean – salva la riga corrente, restituendo True se l’operazione è andata a buon fine
SetCellStyle(Byval Row As Integer, Byval field As String, Byval Style As String) (*) – assegna lo style specificato nel parametro <style>, precedentemente definito con il metodo AddStyle del form, alla cella corrispondente alla colonna collegata al campo <field> nella riga <Row>. Se NuovoLayout=true, nel parametro <style> è possibile specificare la definizione dello style, senza la necessità di una definizione con AddStyle.
SetHeaderStyle(Byval Style As String) (*): assegna lo style specificato nel parametro <style>, precedentemente definito con il metodo AddStyle del form, all’intestazione della griglia. Se NuovoLayout=true, nel parametro <style> è possibile specificare la definizione dello style, senza la necessità di una definizione con AddStyle.
SetHeaderStyle(Byval field As String, Byval Style As String) (*): assegna lo style specificato nel parametro <style>, precedentemente definito con il metodo AddStyle del form, all’intestazione della colonna corrispondente al campo <field>. Se NuovoLayout=true, nel parametro <style> è possibile specificare la definizione dello style, senza la necessità di una definizione con AddStyle.
setReadOnly(ByVal bool As Boolean) – se richiamato passando il valore True al parametro porta la griglia in modalità sola lettura, se si passa False la porta in modalità lettura/scrittura
SetRowStyle(Byval Row As Integer, Byval Style As String) (*): assegna lo style specificato nel parametro <style>, precedentemente definito con il metodo AddStyle del form, alla riga <Row>. Se NuovoLayout=true, nel parametro <style> è possibile specificare la definizione dello style, senza la necessità di una definizione con AddStyle.
SetSelectedRowStyle(Byval Style As String)(*): se NuovoLayout=true, assegna lo style definito nel parametro <style> alla riga selezionata.
setVisible(ByVal bool As Boolean) se richiamato passando il valore False nasconde la griglia, se si passa True la visualizza
sort(ByVal columns As string) (*) ordina la griglia in base ai datalink indicati come argomento. I nomi delle colonne vanno separati da un comma e da uno spazio e possono essere seguiti dalla stringa “DESC” (obbligatoriamente in uppercase) nel caso in cui l’ordinamento debba essere discendente. Esempio di chiamata: form.FindControl("Grid1").sort("NUMBER1, DATE1 DESC")
ExpandChildGrid()– espande le righe mostrando la griglia figlia collegata a ciascuna.
CollapseChildGrid()– chiude le righe nascondendo la griglia figlia collegata a ciascuna.

(*) Non disponibile nella versione mobile
(**) È necessario ovviamente trasformare i numeri e le date in stringa, come nel seguente esempio:

Dim condizione As String = "NUMBER1=" & CStr(N1) & " and NUMBER2=" & CStr(N2) & " and DATE1=#" & dtoc(D1,"yyyy/MM/dd") & "#"

Metodi utilizzabili da codice lato Client (Javascript)

show() – mostra l’oggetto.
hide() – nasconde l’oggetto.
assignField(field,value)– assegna il valore valueal campo field della riga correntemente selezionata.
readField(field)– restituisce il valore del campo field della riga correntemente selezionata.
expandChildGrid()– espande le righe mostrando la griglia figlia collegata a ciascuna.
collapseChildGrid()– chiude le righe nascondendo la griglia figlia collegata a ciascuna.
getCell(row,field) – restituisce l’oggetto jQuery della cella corrispondente alla riga row e alla colonna field. Sull’oggetto restituito è possibile usare qualsiasi metodo jQuery, come ad esempio css,addClass e removeClass. Ad esempio, può essere usato per assegnare le proprietà dello stile:
$('#<Grid1>').getCell(row,"NUMBER1").css("background-color","red")
getCellValue(row, field) – restituisce il valore della cella corrispondente alla riga row e alla colonna field.
getCurrentRowCell(field) – restituisce l’oggetto jQuery della cella corrispondente alla riga corrente e alla colonna field. Sull’oggetto restituito è possibile usare qualsiasi metodo jQuery, come ad esempio css,addClass e removeClass (vedere metodo getCell).
grid() – restituisce l’oggetto griglia.
rowCount() – restituisce il numero di righe visualizzate.
setCellValue(row, field, value) – assegna il valore value alla cella corrispondente alla riga row e alla colonna field.
setColumnWidth(field,width) – definisce la larghezza della colonna corrispondente al campo field. Se width = 0, la colonna viene nascosta.
setColumnHeaderText(field,text) – definisce il testo dell’intestazione della colonna corrispondente al campo field.
setColumnHidden(field,hidden) – definisce se la colonna corrispondente al campo fieldnascosta (parametro hidden=true) o meno (parametro hidden=false).
setFocusOnColumn(field,hidden) – solo se NuovoLayout=true, rende attiva la cella corrispondente al campo field della riga corrente, entrando in modalità di modifica.

Migrazione a nuovo layout

Sui form esistenti è possibile utilizzare il nuovo layout dell’oggetto Griglia, assegnando la proprietà NuovoLayout a true ed effettuando le verifiche elencate nel seguito e le modifiche eventualmente conseguenti.

Nei selettori utilizzati nelle funzioni jQuery “$”,”find”, e nel primo parametro della funzione “attr”, sostituire l’attributo “idx” con “data-rowindex”. Dove viene ricercato l’attributo “data-rowindex”, il valore deve essere messo fra apici.
Nei selettori utilizzati nelle funzioni jQuery “$” e “find” sostiture la classe “.igg_ActiveRow” con “.e-row”
Le istruzioni che aggiornano i colori di righe e celle via Javascript vanno spostate dall’evento “RenderClient” del form all’evento “DatiCaricatiClient” della griglia, che si attiva al termine del caricamento asincrono dal server.
Se la proprietà “ScrollVirtuale” è true, va tenuto presente che le righe caricate in ogni momento sono solo una parte di quelle presenti nel database. In questo caso è necessario evitare di effettuare operazioni come totali o ricerca di dati maggiori o minori via javascript, in quanto la probabilità di non considerare tutte le righe è molto alta.
Per cercare la riga corrente in corso di editing, usare il selettore “.e-editedrow[role=’row’]”
I pulsanti che interagiscono con la griglia, ad esempio per aggiungere, inserire, eliminare o aggiornare righe, è bene siano spostati all’interno di un oggetto Contenitore con la proprietà “ContenitoreAggiornamento” a true. In questo modo, gli aggiornamenti delle righe non comportano il refresh grafico dell’intera griglia.
Allo stesso modo, eventuali oggetti esterni alla griglia il cui valore viene aggiornato nell’evento “CambiaRiga” lato server, devono essere inseriti in un oggetto Contenitore con la proprietà “ContenitoreAggiornamento” a true, prevedendo, nell’evento stesso, l’aggiornamento del contenitore tramite il metodo “UpdateContainer” del form.
Se si ha la necessità di attivare da codice l’editing di una riga, è sufficiente richiamare il metodo “SetFocusOnColumn” specificando la colonna sulla quale si vuole posizionare il cursore.