.

Caricamento e personalizzazione di un grafico generico
prodotto in ambiente WebNir e salvato in formato JSON

Premessa

La quasi totalità delle applicazioni della piattaforma WebNir produce risultati anche sotto forma di uno o più grafici. Come funzionalità di base, è possibile esportare in formato CSV i dati numerici in base ai quali è stato costruito ciascun grafico. I grafici, inoltre, sono personalizzabili in molti aspetti (scale degli assi, etichette, colore delle linee e dei simboli,...) e possono essere salvati come immagini PNG.

Grazie al pulsante con la freccia verde diretta verso il basso (presente in ogni grafico prodotto sulla piattaforma), è anche possibile salvare in un unico documento in formato JSON (un formato di testo in chiaro) sia i dati numerici di base del grafico, sia le informazioni di personalizzazione. Questo consente agli utenti di archiviare in modo pratico ed efficace i risultati delle proprie elaborazioni, condividerli con altri utenti ed utilizzarli per rapporti di prova, pubblicazioni ecc.

Finalità

Questo strumento permette di rileggere, visualizzare, personalizzare ulteriormente, esportare nuovamente in formato PNG, CSV o JSON qualunque grafico precedentemente salvato in quest'ultimo formato da una delle applicazioni della piattaforma WebNir.

Tutto ciò rende i risultati delle proprie elaborazioni fruibili in modo semplice e flessibile, con finalità di archiviazione, personalizzazione, condivisione e pubblicazione pressoché illimitate.

Attraverso la documentazione di questo strumento, vengono inoltre fornite informazioni generali utili alla comprensione e alla gestione dei grafici generati dalle applicazioni della piattaforma.

Ambiti di impiego

Questo strumento, unitamente alla possibilità di salvare in formato JSON i grafici prodotti dalle applicazioni WebNir, consente di:

  • rileggere grafici precedentemente prodotti sulla piattaforma WebNir senza dover eseguire nuovamente le operazioni di calcolo (potenzialmente onerose) che li hanno originariamente prodotti;
  • personalizzare, tramite un'apposita interfaccia utente, le impostazioni di visualizzazione dei grafici;
  • archiviare e condividere i propri grafici con altri utenti in modo da conservare e distribuire tutte le informazioni in essi contenute (relative sia ai dati, sia alla visualizzazione);
  • modificare direttamente, tramite un comune editor di testo, il documento in formato JSON (un formato aperto, semplice e ben documentato), qualora l'utente abbia familiarità con questo tipo di procedura.

Documentazione

La scheda Istruzioni riporta le informazioni operative dettagliate per l'uso di questo strumento.

La scheda Concetti di base contiene la descrizione tecnica degli strumenti software utilizzati per la gestione dei grafici nell'ambiente WebNir e altre informazioni utili alla comprensione del funzionamento di questo strumento.

La scheda Esempi fornisce i riferimenti ad alcuni documenti JSON utilizzabili per mettera alla prova le potenzialità di questo strumento e familiarizzarsi col suo utilizzo.

Interazione con i grafici

I grafici presenti sulla piattaforma WebNir consentono alcune interazioni da parte dell'utente:

  • zoom, cliccando sul grafico e trascinando il cursore sull'area di interesse;
  • ripristino della visualizzazione iniziale, tramite doppio click sull'area del grafico;
  • trascinamento della legenda e del titolo del grafico (solo qualora questi oggetti siano impostati in modo opportuno);
  • possibilità di attivare e spegnere le serie, cliccando sulla relativa voce in legenda;
  • visualizzazione, per default nell'angolo in basso a destra, delle coordinate su cui si trova il cursore (una coppia per ciascuna combinazione di assi X e Y);
  • visualizzazione dei valori associati ai punti delle serie, al passare del mouse su di essi.

Pulsanti

Ad ogni grafico prodotto su WebNir è associata una serie di pulsanti, il cui funzionamento è riportato nel seguito. La presenza di un segno di spunta verde significa che il pulsante è disponibile nei grafici prodotti dalle applicazioni della piattaforma, un segno di spunta azzurro significa che il pulsante è disponibile in questo strumento.

Esporta il grafico in formato PNG e lo visualizza come miniatura in una finestra di pop up. L'immagine completa può essere scaricata tramite click destro del mouse sulla miniatura.
Esporta in formato PNG tutti i grafici visibili sulla pagina e li mostra come miniature in una finestra di pop up. Le immagini complete possono essere scaricate individualmente tramite click destro del mouse sulla miniatura associata.
Nasconde/visualizza la legenda nel grafico.
Nasconde/visualizza le etichette nel grafico.
Alterna la modalità di visualizzazione nella legenda da gruppi a serie, e viceversa.
Esporta il contenuto del grafico, includendo dati e formattazione, in formato JSON. Il file, salvato sulla macchina locale dell'utente, può essere ricaricato in seguito in questa applicazione o condiviso con altri utenti senza perdere alcuna informazione.
Esporta il contenuto del grafico, includendo dati e formattazione, in formato JSON; vengono salvati solo i dati che ricadono entro gli estremi personalizzati degli assi cartesiani. Il file, salvato sulla macchina locale dell'utente, può essere ricaricato in seguito in questa applicazione o condiviso con altri utenti senza perdere alcuna informazione.
Importa il contenuto di un grafico precedentemente salvato in formato JSON, includendo dati e formattazione, in questa pagina.
Inserisci nel grafico corrente una o più serie di un altro grafico precedentemente salvato in formato JSON.
Apre una finestra che permette di gestire il numero di serie dati ed assi nel presente grafico.
Esporta in formato CSV il contenuto numerico delle serie visualizzate nel grafico, ma non la formattazione del grafico stesso. Il documento, salvato sulla macchina locale dell'utente, può essere riletto in un comune foglio elettronico per successive elaborazioni.
Attiva il pulsante di refresh (v. il prossimo pulsante) e visualizza la finestra di personalizzazione del grafico. Se la finestra è già attiva, vengono ripristinati i valori iniziali del grafico in questione, perdendo tutte le modifiche non ancora applicate.
Utilizza i parametri presenti nella finestra di personalizzazione per ridisegnare il grafico secondo la formattazione impostata dall'utente.

Interfaccia di personalizzazione

La finestra di personalizzazione del grafico consente all'utente di impostare i parametri relativi alla caratterizzazione grafica delle serie di dati e ad alcune altre proprietà del grafico. In particolare, sono presenti riquadri relativi ai seguenti elementi:

  • Proprietà: include schede relative allo stile del grafico (dimensioni, animazione, colori e font predefiniti, ecc.), al riempimento (per le serie lineari), al commento (testo e data) e al titolo (testo e formattazione).
  • Assi.
  • Serie dati: per ogni serie vanno specificati il titolo (che compare nella legenda), la modalità di visualizzazione secondo il formato sprintf e i dettagli grafici.
  • Legenda.
  • Griglia.
  • Cursore.
  • Highlighter.
  • Overlay.
  • JSON: questo riquadro è costituito da un campo di testo e da 5 pulsanti che consentono di:
Importare nel campo di testo, in formato JSON, le impostazioni presenti nell'interfaccia di personalizzazione.
Predisporre l'interfaccia di personalizzazione in accordo ai dati JSON presenti nel campo di testo.
Espandere o restringere il campo di testo per i dati JSON in modo da poterli visualizzare nella loro interezza.
Scaricare i dati JSON presenti nel campo di testo in un documento di testo da salvare localmente.
Importare nel campo di testo i dati JSON leggendoli da un documento di testo salvato localmente.

jqPlot

jqPlot è un plugin per la creazione di grafici per il framework Javascript jQuery. È stato scelto in quanto permette di generare grafici di vario tipo:

  • dispersioni;
  • istogrammi;
  • torta;
  • ciambella;
  • curve di Bezier;
  • blocchi;
  • bolle;
  • Mekko;
  • tachimetro;
  • piramide;
  • imbuto;
  • candela.

La tecnologia client-side scelta offre diversi vantaggi. In particolare, i grafici:

  • sono interattivi, offrono possibilità di interrogazione e zoom da parte dell'utente, consentono di attivare o disattivare a piacere le serie visualizzate e in certi casi di trascinare alcuni elementi in essi contenuti;
  • risultano personalizzabili senza dover eseguire più volte le operazioni di calcolo su cui sono basati, che potrebbero risultare onerose;
  • sono esportabili mantenendo intatta tutta l'informazione in essi contenuta;
  • si prestano ad essere esportati sia in formato vettoriale (come il formato SVG), in modo da essere incorporati in documenti PDF mantenendo un'alta risoluzione, sia in formato raster (PNG), per esempio per essere inclusi in un qualunque programma di word processing.

Sono personalizzabili tutti gli elementi costituenti il grafico:

  • la formattazione dei dati, sia lungo gli assi sia in corrispondenza degli elementi visualizzati;
  • il colore e lo spessore delle linee o la dimensione dei simboli delle serie;
  • la griglia sottostante;
  • il cursore.

Sono gestibili fino a 2 assi delle ascisse e 9 assi delle ordinate. Gli assi gestiscono scale di tipo lineare, logaritmico, data e categorizzate.

html2canvas

html2canvas è un plugin Javascript che consente di acquisire schermate di parti di pagine web direttamente sul browser degli utenti, creandone una rappresentazione in base alle proprietà lette nel DOM (Document Object Model), limitatamente alle proprietà CSS (Cascading Style Sheets) da esso comprese.

sprintf

La funzione di libreria jqPlot sprintf viene utilizzata per formattare in modo opportuno una variabile di tipo scalare. Ai fini della presente documentazione:

  • PI = 3.141592653589793
  • sprintf("%.2f", PI) = 3.14
  • sprintf("%d", PI) = 3
  • sprintf("%.3e", PI) = 3.142e+0

Si veda anche il link relativo all'utilizzo in PERL.

HTML

HTML (HyperText Markup Language) è il linguaggio utilizzato per creare pagine web e altri tipi di documenti visualizzabili in un browser.

In HTML si utilizza il markup per annotare testo, immagini e altri contenuti da mostrare in un browser Web. Il markup HTML include elementi speciali come <head>, <title>, <body>, <header>, <p>, <div>, <span>, <img>...

Un elemento HTML viene distinto in un documento dal resto del testo tramite un tag, che consiste nel nome dell'elemento circondato da "<" e ">".

  • Grafico di <i>esempio</i>
  • <span style="margin-left:15px;">Titolo del grafico</span>

I colori in HTML

In HTML i valori dei colori sono rappresentati in formato esadecimale "#RRGGBB" (RR rosso, GG verde e BB blu sono numeri interi esadecimali compresi tra 00 e FF, che specificano l'intensità della rispettiva componente cromatica di base):

  • #FF0000: rosso 100%
  • #00FF00: verde 100%
  • #0000FF: blu 100%

Se i sei valori sono costituiti da tre coppie di numeri uguali, allora si può utilizzare la notazione semplificata:

  • #FF0: giallo
  • #0FF: ciano
  • #F0F: magenta

Esistono inoltre due funzioni CSS per specificare i colori in formato decimale:

  • rgb(255,0,0): rosso;
  • rgba(0,255,0,0.7): verde con trasparenza.

Nell'interfaccia utente viene utilizzato jscolor, un plugin Javascript per la selezione dei colori, per permettere all'utente di selezionare il colore desiderato o in maniera interattiva, o tramite input diretto in formato esadecimale o decimale:

Cliccando nel campo di input riportato come esempio, si apre una palette di selezione suddivisa in due parti: una per la selezione nello spazio saturazione-tonalità e un cursore per impostare la luminosità.

Quando, oltre al colore, vanno riportare anche le informazioni relative all'opacità di un elemento del grafico, accanto al campo relativo al colore ne appare un secondo, di tipo numerico, che accetta valori compresi tra 0 (oggetto completamente trasparente) e 1 (oggetto completamente opaco). Inserendo nel primo campo le informazioni di colore in formato RGBA (es.: rgba(255,0,127,0.5) il valore di opacità viene compilato automaticamente.

JSON

JSON (JavaScript Object Notation) è un semplice formato per lo scambio di dati, indipendente dal linguaggio di programmazione, basato su due strutture:

  • un insieme di coppie nome/valore;
  • un elenco ordinato di valori.

Di seguito viene mostrato il documento JSON relativo al grafico di prova visualizzato nella scheda Gestione grafici di questa applicazione.

{
  "title": 
  {
    "text": "Grafico di esempio"
  },
  "xmin1": 4,
  "xmax1": 5,
  "ymin1": 0,
  "ymax1": 20,
  "formatString_x1": "%.1f",
  "formatString_y1": "%.1f",
  "seriesColors": ["#C00"],
  "labelx1": "Asse X",
  "labely1": "Asse Y",
  "serie1": 
  {
    "titolo": "Serie di esempio",
    "formatString": "%.1f, %.1f",
    "assex": 1,
    "assey": 1,
    "valorx": [4.3,4.5,4.7,4.2,4.8,4.3],
    "valory": [3.3,16.7,3.3,13.3,13.3,3.3]
  },
  "highlighter": 
  {
    "show": true,
    "showMarker": false,
    "lineWidthAdjust": 1,
    "sizeAdjust": 1,
    "showTooltip": true,
    "tooltipLocation": "nw"
  }
}

CSV

Il comma-separated values (abbreviato in CSV) è un formato per documenti di testo utilizzato per l'importazione e l'esportazione di una tabella di dati, ad esempio da o verso fogli elettronici o database.

Ogni riga della tabella è normalmente rappresentata da una linea di testo, che a sua volta è divisa in campi (le singole colonne, separate da un apposito carattere separatore), ciascuno dei quali contiene il valore relativo a una cella della tabella.

Il formato CSV non specifica una codifica di caratteri, né la convenzione per indicare il fine linea (nei sistemi operativi Unix e Unix-like viene usato il carattere ASCII line-feed, nei sistemi operativi Microsoft Windows si usa la sequenza di caratteri ASCII carriage return+line-feed, mentre in altri può essere usato il solo carattere carriage return), né il carattere da usare come separatore tra campi e nemmeno convenzioni per rappresentare date o numeri (tutti i valori sono considerati come semplici stringhe di testo) e se la prima riga sia da considerare di intestazione o meno.

Di seguito viene mostrato il documento CSV relativo al grafico di prova visualizzato nella scheda Gestione grafici di questa applicazione.

"Serie di esempio"
"4.3",	"3.3"
"4.5",	"16.7"
"4.7",	"3.3"
"4.2",	"13.3"
"4.8",	"13.3"
"4.3",	"3.3"