OGGETTO VISTADATI

Descrizione

L’oggetto VistaDati consente la visualizzazione in sola lettura dei dati reperiti dal database tramite una query. 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.

È bene sottolineare che, a differenza di ciò che succede con le griglie, per selezionare una colonna di una vista è necessario chiamarla tramite l’alias che le è stato assegnato nella relativa QueryLista. In eventuale mancanza di alias, si dovrà naturalmente usare il nome proprio che la colonna ha all’interno del database.

Se una colonna contiene immagini codificate base64, queste vengono visualizzate automaticamente nella cella, con la possibilità di aprirle ingrandite cliccandovi sopra.

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.
• GrigliaFiglia e CampoFiltroGrigliaFiglia:
  Se NuovoLayout=true è possibile collegare due oggetti VistaDati in modo da mostrare, per ogni riga della prima, le corrispondenti righe della seconda, il cui nome deve essere specificato nella proprietà GrigliaFiglia. I due oggetti sono collegati da una colonna in comune, che deve essere presente nelle query specificate nella proprietà QueryLista. Tale colonna deve inserita nella proprietà CampoFiltroGrigliaFiglia. 
• QueryLista: contiene la query utilizzata per visualizzare i dati. Tale query può contenere parametri i cui nomi, preceduti dal carattere “:”, possono corrispondere a nomi di campi collegati ad oggetti del form o a nomi di oggetti. Al momento dell’apertura del form, la query verrà eseguita e verranno assegnati i parametri ai valori dei campi e/o degli oggetti.
• ScrollVirtuale: assegnare a True per caricare i record dinamicamente in fase di scroll, a False per visualizzare i record a pagine.
• FattoreCacheRigheScrollVirtuale: determina il numero di righe caricato dal server ad ogni operazione di lettura nel caso la proprietà ScrollVirtuale sia assegnata a True. Ad esempio, un fattore di 2 significa che ad ogni lettura vengono caricate 2 volte il numero di righe visualizzate. Lasciare a zero per utilizzare il valore di default. Se NuovoLayout=true viene ignorato.
• 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 oggetto Griglia e implementare il Drag&Drop come spiegato in questo esempio, oppure su un oggetto Calendario come spiegato in questo esempio. 
• 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.
• 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.
• 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 CODICE una freccia verde verso l’alto se il valore è maggiore di 10, una freccia rossa verso il basso altrimenti.

  if (field=='CODICE')
      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#)

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

Nel codice degli eventi è possibile utilizzare i seguenti metodi:

• ClearSelection: rimuove l’eventuale selezione di righe
• Count(): restituisce il numero totale delle righe presenti nella griglia
• EndOfRows(): restituisce true se il puntatore della riga corrente è oltre l’ultima riga
• FilterRows(<condition>): filtra le righe della griglia in base alla condizione SQL passata come argomento. Per annullare tutti i filtri presenti basta passare una stringa vuota. 
• GetCellValue(<Row>,<field>)*: restituisce il valore contenuto nella cella corrispondente alla colonna collegata al campo <field> nella riga <Row>
• GoToRow(<bookmark>): muove il cursore sulla riga corrispondente al segnalibro specificato (*)
• LocateRow(<condition>): muove il cursore sulla prima riga della griglia che soddisfa la condizione SQL passata (*). NOTA: la ricerca parte dalla riga selezionata al momento. Può quindi essere necessario chiamare prima MoveFirst() per ottenere i risultati desiderati.
• MoveFirst(): sposta il puntatore delle righe sulla prima riga, ritornando false se l’operazione non è riuscita, ad esempio perchè non vi sono righe
• MoveLast(): sposta il puntatore delle righe sull’ultima riga, ritornando false se l’operazione non è riuscita, ad esempio perchè non vi sono righe
• MoveNext(): 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(): 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(<field>): restituisce il valore del campo specificato nel parametro, per la riga corrente
• RefreshData(): esegue nuovamente la query aggiornando i valori dei parametri e aggiornando di conseguenza la visualizzazione
• RowBookmark(): 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.
• SetCellStyle(<row>,<field>,<Style>)*: 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(<Style>)*:  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(<field>,<Style>) *: 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.
• SelectedRows(): restituisce un array (dbArray) che contiene i segnalibri delle righe correntemente selezionate nella griglia 
• SelectedRows(<rows>): consente di assegnare le righe selezionate, i cui segnalibri sono definiti nel parametro <rows>, di tipo dbArray
• SetRowStyle(<Row>,<Style>): 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(<Style>): se NuovoLayout=true, assegna lo style definito nel parametro <style> alla riga selezionata.
• 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 <field> è nascosta (parametro <hidden>=true) o meno (parametro <hidden>=false).
• setVisible(<bool>): se richiamato passando il valore false nasconde la griglia, se si passa false la visualizza
• sort(<columns>): ordina la vista in base ai nomi delle colonne indicati come argomento. I nomi delle colonne vanno separati da un comma e possono essere succeduti dalla stringa “DESC” (obbligatoriamente in uppercase) nel caso in cui l’ordinamento debba essere discendente. Esempio di chiamata: form.FindControl("Grid1").sort("Indice, Data DESC")

Metodi utilizzabili da codice lato Client (Javascript)

• show(): visualizza l’oggetto.
• hide(): nasconde l’oggetto.
• readField(<field>): restituisce il valore del campo <field> della riga correntemente selezionata.
• collapseChildGrid(): chiude le righe nascondendo la griglia figlia collegata a ciascuna.
• expandChildGrid(): espande le righe mostrando la griglia figlia collegata a ciascuna.
• getCell(<row>,<field>): restituisce l’oggetto jQuery della cella corrispondente alla riga 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.
• selectedRows(): restituisce un array con i numeri delle righe selezionate. Può essere usato come nel seguente esempio:

  var s;
  s=$('#<DataView1>').selectedRows();
  
  var i;
  for (i=0;i<s.length;i++) 
      $('#<DataView1>').getCell(s[i],"CODICE").css("background-color","red")
  
  

• 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 <field> è nascosta (parametro <hidden>=true) o meno (parametro <hidden>=false).

Migrazione a nuovo layout

Sui form esistenti è possibile utilizzare il nuovo layout dell’oggetto VistaDati, 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.
• I pulsanti che interagiscono con l’oggetto VistaDati, ad esempio per spostare la riga corrente, è 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 all’oggetto 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.