Creazione di tipi di grafico

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

Pubblico

In questa pagina si presuppone che tu abbia letto la pagina Utilizzo dei grafici. Inoltre, presuppone che tu abbia familiarità con JavaScript e la programmazione orientata agli oggetti. Sul Web sono disponibili numerosi tutorial JavaScript.

Creare un grafico

I grafici sono esposti all'utente tramite una libreria JavaScript creata da te. Per creare una libreria di grafici:

1. Scegli uno spazio dei nomi per il codice. Il tuo codice verrà ospitato sulle altre pagine, quindi dovresti evitare conflitti di denominazione.
2. Implementa l'oggetto grafico. Implementa un oggetto JavaScript che mostri 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
   • Eventuali metodi personalizzati che vuoi esporre ai 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 saranno in grado di incorporarlo.
5. Pubblicare il grafico nella Galleria grafici.

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 classi 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 (tranne il WWW e le eventuali estensioni). Ad esempio, se il grafico verrà pubblicato su www.example.com, utilizzerai example come spazio dei nomi univoco. Puoi aggiungere ulteriori suffissi, separati da . per raggruppare ulteriormente il grafico (tutti i grafici di Google hanno lo spazio dei nomi google.visualization). Utilizza l'oggetto spazio dei nomi per archiviare l'oggetto del grafico, oltre a eventuali variabili globali di cui potresti avere bisogno.

Di seguito è riportato un esempio di creazione di un oggetto dello spazio dei nomi in cui inserire una classe di grafico denominata 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 CSS

Se utilizzi CSS, assicurati di non scrivere regole CSS che possano influire sugli altri grafici sulla pagina. Ad esempio, una regola come td {color: blue;} è altamente sconsigliata, perché influirà su qualsiasi altro elemento <td> della pagina, non solo all'interno del grafico. Un modo per risolvere questo problema è racchiudere l'intero grafico in un <div> con il nome di una classe e fare in modo che tutte le regole CSS vengano applicate solo agli elementi che sono discendenti di un elemento con quel nome di classe. Ad esempio, la seguente regola CSS avrà effetto solo sugli elementi <td> che hanno un elemento con il nome di classe "example" come predecessore.

td.example {color: blue;}

Quindi puoi racchiudere il grafico in un <div> con :

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

Implementare il grafico

Devi implementare il grafico come oggetto JavaScript che espone i metodi standard descritti nella sezione Riferimenti. I due metodi obbligatori sono il costruttore e i metodi draw(). Puoi anche esporre all'utente anche metodi aggiuntivi appropriati per il grafico. Ricorda che più facile da usare è meglio.

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 memorizzano una copia locale di questo elemento nel costruttore per un utilizzo futuro:

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. Una DataTable contenente i dati da visualizzare.
2. Una mappa facoltativa delle opzioni di nome/valore per il grafico. I nomi e i tipi di valore delle opzioni sono definiti da te per il grafico specifico. Ad esempio, nell'esempio Hello Chart riportato di seguito, il grafico supporta un'opzione denominata "showLineNumber" con valore di tipo booleano. Devi supportare un valore predefinito per ogni opzione, nel caso in cui l'utente non passi un valore per un'opzione specifica. Questo parametro è facoltativo, quindi devi anche prepararti a utilizzare tutti i valori predefiniti se l'utente non lo trasmette (ulteriori informazioni).

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 i dati DataTable sotto forma di 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, '"');
}

Inclusione del grafico in una pagina web

Per utilizzare il grafico precedente, salvalo in un file .js accessibile dal browser. Poi salva il seguente codice, modificando il parametro sorgente <script> in modo che punti 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 informazioni dettagliate nella pagina Eventi. Puoi esporre i dettagli dell'evento al client aggiungendo proprietà all'oggetto evento oppure esporre nel grafico un metodo get...() di qualche tipo, che il client può chiamare per ottenere i dettagli dell'evento. In entrambi i casi, documenta bene i tuoi metodi o le proprietà degli eventi.

Documenta il grafico

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

• Descrivi tutti i metodi che supporti. Il metodo draw() è comune a tutti i grafici, ma ogni grafico può supportare metodi aggiuntivi propri. (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(). Ciò include il nome di ogni opzione, il tipo di valore previsto e il relativo 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 da utilizzare nell'istruzione di inclusione <script> del client e fornisci l'URL per la documentazione.
• Assegna il nome completo del grafico.
• Crea pagine di esempio che dimostrano come utilizzare il grafico con le opzioni supportate, i relativi eventi e i metodi personalizzati.
• Descrivi chiaramente le norme sui 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 chiaramente quali dati vengono inviati.
  • Annota per quanto tempo i dati verranno salvati sul server.
  • Documenta quali entità avranno accesso ai dati. Ad esempio, Azienda XYZ e così via.
  • Specifica se i dati verranno registrati e per quanto tempo.

La documentazione sarà ospitata nello stesso posto del codice del grafico (vedi Inviare il grafico alla galleria di seguito).

Inviare il grafico alla Galleria

Dopo aver creato il grafico, invialo nella sezione "Grafici aggiuntivi" della nostra galleria. L'invio di un grafico implica che dovrai firmare un contratto con noi accettando di non creare software dannoso o di non usare in modo improprio i dati utente. La galleria è solo un elenco di puntatori ai grafici che abbiamo creato o che abbiamo rivisto; puoi scegliere di ospitare la libreria JavaScript e la documentazione effettive sul tuo sito oppure puoi chiedere a Google di ospitare la libreria e la documentazione per te. Specifica se vuoi che ospitiamo il grafico quando lo pubblichi nella galleria.

Risoluzione dei problemi

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

• Controlla che non ci siano errori di battitura. Ricorda che JavaScript è una lingua che fa distinzione tra maiuscole e minuscole.
• Utilizzare un debugger JavaScript. In Firefox, puoi utilizzare la console JavaScript, il Venkman Debugger o il componente aggiuntivo Firebug. 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, pubblicala nel gruppo insieme a un link a una pagina web che dimostri il problema.

Localizzazione

Se prevedi che il grafico verrà utilizzato da utenti in diversi paesi, ti consigliamo di progettarlo in modo che sia localizzato per le diverse lingue e culture. La localizzazione più semplice consiste nella traduzione delle stringhe di testo standard nell'interfaccia utente in base alle impostazioni del browser dell'utente. Una forma di localizzazione più avanzata è la modifica dei formati numerici a seconda della localizzazione o, possibilmente, anche la progettazione dell'interfaccia utente. Se decidi di localizzare il grafico, elenca nella documentazione le lingue supportate da quest'ultimo e fornisci l'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 non sia corretta. Un modo comune per rilevare la lingua del browser è esaminare l'intestazione HTML Accetta-Language.