Creare tipi di grafici

In questa pagina viene descritto come sviluppare un tipo di grafico e renderlo disponibile agli utenti.

Pubblico

Questa pagina presuppone che tu abbia letto la pagina Utilizzo dei grafici. Presuppone inoltre che tu abbia dimestichezza con JavaScript e la programmazione con oggetti. Sono disponibili molti tutorial JavaScript sul Web.

Creare un grafico

I grafici vengono esposti all'utente tramite una libreria JavaScript creata da te. Per creare una libreria di grafici, procedi nel seguente modo:

  1. Scegli uno spazio dei nomi per il tuo codice. Il codice verrà ospitato in altre pagine; cerca di evitare conflitti di denominazione.
  2. Implementa l'oggetto del grafico. Implementa un oggetto JavaScript che esponi quanto segue:
    • Un costruttore,
    • Un metodo draw() per disegnare l'oggetto all'interno dell'elemento DOM passato al costruttore,
    • Qualsiasi altro metodo standard facoltativo che un client può utilizzare, ad esempio getSelection(), e
    • Qualsiasi metodo personalizzato da mostrare ai tuoi clienti.
  3. [Facoltativo] Implementa gli eventi che vuoi attivare per il client.
  4. Scrivi la documentazione per il grafico. Se non lo documenti, probabilmente le persone non potranno incorporarla.
  5. Pubblica il grafico nella Galleria.

Suggerimento

  • Puoi scaricare la definizione della classe e del metodo goog.visualization per abilitare il completamento automatico nel tuo IDE (editor di codice). Scarica il file da http://www.google.com/uds/modules/gviz/gviz-api.js e salvalo nel tuo progetto. La maggior parte degli IDE lo indicizza automaticamente e abilita il completamento automatico, anche se potrebbe essere diverso. Tieni presente che il file potrebbe non essere sempre aggiornato; consulta le pagine di riferimento per il riferimento API più aggiornato.

Scegli uno spazio dei nomi

Il grafico può essere incorporato in una pagina che ospita altri grafici o altro codice JavaScript non correlato. Per evitare conflitti di denominazione con altri nomi di codice o classe CSS, devi scegliere uno spazio dei nomi univoco per il codice del grafico. Una buona scelta per uno spazio dei nomi è l'URL che utilizzerai per ospitare lo script (meno WW ed eventuali estensioni). Ad esempio, se il grafico viene pubblicato su www.example.com, devi utilizzare example come spazio dei nomi univoco. Puoi aggiungere altri suffissi, separati da . contrassegna, per raggruppare ulteriormente il grafico (tutti i grafici di Google hanno lo spazio dei nomi google.visualization). Utilizza l'oggetto dello spazio dei nomi per archiviare l'oggetto del grafico, nonché eventuali variabili globali di cui potresti aver bisogno.

Ecco un esempio di creazione di un oggetto dello spazio dei nomi per contenere una classe di grafico chiamata MyTable, nonché eventuali variabili globali necessarie:

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

Evitare i conflitti tra CSS

Se utilizzi CSS, assicurati di non scrivere regole CSS che possano influire su altri grafici nella pagina. Ad esempio, sconsigliamo vivamente di utilizzare una regola come td {color: blue;}, perché questa operazione influirà su qualsiasi altro elemento <td> nella pagina, non solo all'interno del grafico. Un modo per risolvere questo problema è racchiudere l'intero grafico in un <div> con un nome di classe e fare in modo che tutte le regole CSS si applichino solo agli elementi discendenti di un elemento con quel nome di classe. Ad esempio, la seguente regola CSS influirà solo sugli elementi <td> il cui predecessore è un elemento il cui nome di classe è "example".

td.example {color: blue;}

Puoi quindi inserire il grafico in un <div> con :

<div class="example">
  ...
</div>

Implementare il grafico

Dovrai implementare il grafico come oggetto JavaScript che espone i metodi standard descritti nella sezione Riferimento. I due metodi obbligatori sono il costruttore e il disegno disegno(). Puoi anche mostrare all'utente altri metodi appropriati per il tuo grafico. Ricorda però che è più facile da usare.

Costruttore

Il grafico dovrebbe esporre un singolo costruttore che accetta un singolo parametro, un elemento DOM in cui disegnerai il grafico. In genere i grafici archiviano una copia locale di questo elemento nel costruttore per un uso successivo:

function example.MyTable(container) {
  this.container = container
}

Il metodo draw()

La classe del grafico deve avere un metodo draw() definito nel prototipo della classe del grafico. Il metodo draw() accetta due parametri:

  1. Un DataTable che contiene i dati da visualizzare.
  2. Una mappa facoltativa di opzioni di nome/valore per il grafico. I nomi e i tipi di valori delle opzioni sono definiti da te per il grafico specifico. Ad esempio, nell'esempio di Hello grafico riportato di seguito, il grafico supporta un'opzione denominata "showLineNumber", con un valore di tipo booleano. Devi supportare un valore predefinito per ogni opzione, nel caso in cui l'utente non superi un valore per un'opzione specifica. Questo parametro è facoltativo; pertanto, devi anche prepararti a utilizzare tutti i valori predefiniti se l'utente non trasmette questo parametro (scopri di più).
example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Un saluto da Google,

Ecco un semplice grafico che mostra un dato DataTable come tabella HTML:

Ecco il codice di implementazione:

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

Includere il grafico in una pagina web

Per utilizzare il grafico precedente, salvalo in un file .js accessibile dal browser. Salva il codice seguente, modificando il parametro sorgente <script> in modo che rimandi al file JavaScript:

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

 

Implementare gli eventi

Se vuoi che il grafico attivi eventi utili (ad esempio, eventi timer o eventi avviati dall'utente, come i clic), devi chiamare la funzione google.visualization.events.trigger con i dettagli dell'evento (nome, proprietà da inviare e così via). Puoi trovare i dettagli nella pagina Eventi. Puoi esporre i dettagli dell'evento al client aggiungendo proprietà all'oggetto dell'evento oppure puoi esporre un metodo get...() di qualsiasi tipo sul grafico e il client può chiamare tale metodo per ottenere i dettagli dell'evento. In entrambi i casi, documenta bene i metodi e le proprietà degli eventi.

Documentare il grafico

Se non documenti il grafico correttamente, probabilmente non otterrai molti utenti. Assicurati di documentare quanto segue:

  • Descrivi tutti i metodi supportati. Il metodo draw() è comune a tutti i grafici, ma ogni grafico può supportare i propri metodi aggiuntivi. Probabilmente non è necessario documentare il costruttore, a meno che non abbia un comportamento non standard. Puoi trovare un elenco dei metodi previsti nella pagina di riferimento.
  • Descrivi tutte le opzioni supportate dal tuo metodo draw(). Sono inclusi il nome di ogni opzione, il tipo di valore previsto e il valore predefinito.
  • Descrivi tutti gli eventi che attivi. Indica il nome e le proprietà di ogni evento e quando ogni evento viene attivato.
  • Elenca l'URL della libreria di grafici che deve essere utilizzato nell'istruzione <script> di inclusione del client e fornisci l'URL per la documentazione.
  • Assegna il nome completo del grafico.
  • Crea pagine di esempio che mostrano come utilizzare il grafico con le opzioni supportate, gli eventi e i metodi personalizzati.
  • Descrivi chiaramente le norme relative ai dati del grafico. La maggior parte dei grafici elabora i dati all'interno del browser, ma alcuni potrebbero inviare dati a un server, ad esempio per creare l'immagine di un grafico o di una mappa. Se invii dati a un server:
    • Definisci in modo chiaro i dati che vengono inviati.
    • Tieni presente per quanto tempo i dati verranno salvati sul server.
    • Documentare quali entità avranno accesso ai dati. Ad esempio, Azienda XYZ ecc.
    • Specifica se i dati verranno registrati e per quanto tempo.

La documentazione verrà ospitata nello stesso punto del codice del grafico (consulta la sezione Inviare il grafico con una galleria).

Una volta scritto il grafico, invialo per la pubblicazione nella sezione "Grafici aggiuntivi" della nostra galleria. Inviare un grafico significa che devi firmare un contratto con noi accettando di non creare software dannosi e di fare un uso improprio dei dati utente. La galleria è solo un elenco di puntatori per i grafici che abbiamo creato o che abbiamo esaminato; puoi scegliere di ospitare la libreria e la documentazione JavaScript reali sul tuo sito oppure puoi lasciare che sia Google a ospitare la libreria e la documentazione. Specifica se vuoi che il grafico venga ospitato quando lo pubblichi nella galleria.

Risolvere i problemi

Se il tuo codice non sembra funzionare, ecco alcuni approcci che potrebbero aiutarti a risolvere i tuoi problemi:

  • Cerca gli errori di battitura. Ricorda che JavaScript è un linguaggio sensibile alle maiuscole.
  • Utilizzare un debugger JavaScript. In Firefox, puoi utilizzare la console JavaScript, il Venkman Debugger o il componente aggiuntivo BeyondCorp. In IE puoi utilizzare Microsoft Script Debugger.
  • Cerca nel gruppo di discussione dell'API Google Chart. Se non riesci a trovare un post che risponda alla tua domanda, pubblica la tua domanda nel gruppo insieme a un link a una pagina web che dimostra il problema.

Localizzazione

Se prevedi che il grafico venga utilizzato da utenti dislocati in diversi paesi, ti consigliamo di progettare il grafico in modo che sia localizzato per lingue e culture diverse. La localizzazione più semplice è tradurre le stringhe di testo standard nell'interfaccia utente in base alle impostazioni del browser dell'utente. Una forma di localizzazione più avanzata potrebbe essere modificare i formati numerici in base alla localizzazione o possibilmente anche alla progettazione dell'interfaccia utente. Se decidi di localizzare il grafico, elenca le lingue supportate nel documento nella documentazione e fornisci un'impostazione predefinita di una lingua di uso comune. È utile anche includere un pulsante "Cambia lingua" nell'interfaccia utente del grafico, nel caso in cui la lingua fosse sbagliata. Generalmente la rilevazione della lingua del browser si basa sull'intestazione HTML Accept-language.