Criação de tipos de gráficos

Esta página descreve como desenvolver seu próprio tipo de gráfico e disponibilizá-lo para os usuários.

Público

Esta página pressupõe que você leu a página Como usar gráficos. Também pressupomos que você esteja familiarizado com JavaScript e programação orientada a objetos. Existem muitos tutoriais de JavaScript disponíveis na Web.

Como criar um gráfico

Os gráficos são expostos ao usuário por uma biblioteca JavaScript criada por você. Siga estas etapas para criar uma biblioteca de gráficos:

  1. Escolha um namespace para seu código. O código será hospedado em outras páginas. Tente evitar conflitos de nomenclatura.
  2. Implemente seu objeto de gráfico. Implemente um objeto JavaScript que exponha o seguinte:
    • Um construtor
    • Um método draw() para desenhar seu objeto dentro do elemento DOM transmitido ao construtor.
    • Quaisquer outros métodos padrão opcionais para um cliente usar, como getSelection() e
    • Quaisquer métodos personalizados que você queira expor aos seus clientes.
  3. [Opcional] Implemente todos os eventos que você quer disparar para o cliente capturar.
  4. Escreva a documentação do gráfico. Se você não documentá-la, as pessoas provavelmente não conseguirão incorporá-la.
  5. Poste seu gráfico na Galeria de gráficos.

Dica

  • Você pode fazer o download das definições de classe e método da API goog.visualization para ativar o preenchimento automático no seu ambiente de desenvolvimento integrado (editor de código). Faça o download do arquivo em http://www.google.com/uds/modules/gviz/gviz-api.js e salve-o no seu projeto. A maioria dos ambientes de desenvolvimento integrado o indexa automaticamente e ativa o preenchimento automático, embora seu IDE possa ser diferente. Observe que o arquivo nem sempre está atualizado. Verifique as páginas de referência para ver a referência da API mais atualizada.

Escolher um namespace

O gráfico pode ser incorporado em uma página que hospeda outros gráficos ou outro JavaScript não relacionado. Para evitar conflitos de nomenclatura com outro código ou nomes de classe CSS, escolha um namespace exclusivo para o código do gráfico. Uma boa opção de namespace é o URL que você usará para hospedar seu script (menos o WWW e todas as extensões). Por exemplo, se o gráfico for publicado em www.example.com, use example como o namespace exclusivo. É possível adicionar outros sufixos, separados por . marcas, para agrupar ainda mais o gráfico (todos os gráficos do Google têm o namespace google.visualization). Use o objeto de namespace para armazenar o objeto de gráfico, bem como qualquer variável global que possa ser necessária.

Este é um exemplo de como criar um objeto de namespace para armazenar uma classe de gráfico chamada MyTable, bem como todas as variáveis globais necessárias:

// 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) {
  // ...
}

Como evitar conflitos de CSS

Se você usa CSS, não escreva regras CSS que possam afetar outros gráficos na página. Por exemplo, uma regra como td {color: blue;} não é recomendada, já que ela afeta qualquer outro elemento <td> na página, não apenas no gráfico. Uma maneira de resolver isso é incluir todo o gráfico em uma <div> com um nome de classe, e fazer com que todas as regras de CSS sejam aplicadas apenas aos elementos descendentes de um elemento com esse nome de classe. Por exemplo, a regra CSS a seguir afetará somente elementos <td> que tenham um elemento com o nome de classe "example" como ancestral.

td.example {color: blue;}

Em seguida, você pode unir o gráfico a uma <div> com :

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

Implementar o gráfico

Você precisa implementar o gráfico como um objeto JavaScript que expõe os métodos padrão descritos na Seção de referência. Os dois métodos obrigatórios são o construtor e os métodosdraw(). Você também pode expor outros métodos ao usuário que sejam apropriados para o gráfico. Mas lembre-se: quanto mais fácil de usar, melhor.

O construtor

Seu gráfico deve expor um único construtor que usa um único parâmetro, um elemento DOM no qual você desenhará o gráfico. Normalmente, os gráficos armazenam uma cópia local desse elemento no construtor para uso posterior:

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

O método draw()

A classe de gráfico precisa ter um método draw() definido no protótipo da classe de gráfico. O método draw() aceita dois parâmetros:

  1. Um DataTable que contém os dados a serem exibidos.
  2. Um mapa opcional de opções de nome/valor para seu gráfico. Os nomes e tipos de valor das opções são definidos por você para o gráfico específico. No exemplo do Hello Chart abaixo, o gráfico aceita uma opção chamada "showLineNumber" com um valor do tipo booleano. Ofereça um valor padrão para cada opção, caso o usuário não transmita um valor para uma opção específica. Esse parâmetro é opcional, então você também precisa estar preparado para usar todos os valores padrão caso o usuário não o transmita (mais informações).
example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Hello Chart!

Veja um gráfico simples que exibe dados de DataTable como uma tabela HTML:

E este é o código de implementação:

// 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, '"');
}

Como incluir seu gráfico em uma página da Web

Para usar o gráfico anterior, salve-o em um arquivo .js que pode ser acessado no seu navegador. Em seguida, salve o código a seguir, alterando o parâmetro de origem <script> para apontar para o arquivo 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>

 

Implementar seus eventos

Se você quiser que o gráfico dispare eventos úteis (por exemplo, eventos de tempo ou eventos iniciados pelo usuário, como cliques), chame a função google.visualization.events.trigger com os detalhes do evento (nome, propriedades a serem enviadas etc.). Confira os detalhes na página Eventos. É possível expor os detalhes do evento ao cliente adicionando propriedades ao objeto do evento ou expor um método get...() de algum tipo no gráfico, e o cliente pode chamar esse método para acessar os detalhes do evento. De qualquer forma, documente bem os métodos ou as propriedades do evento.

Documentar seu gráfico

Se você não documentar adequadamente seu gráfico, provavelmente não terá muitos usuários. Certifique-se de documentar o seguinte:

  • Descreva todos os métodos aos quais você oferece suporte. O método draw() é comum a todos os gráficos, mas cada gráfico aceita os próprios métodos adicionais. Você provavelmente não precisará documentar seu construtor, a menos que ele tenha um comportamento não padrão. Veja uma lista de métodos esperados na Página de referência.
  • Descreva todas as opções compatíveis com o método draw(). Isso inclui o nome de cada opção, o tipo de valor esperado e o valor padrão.
  • Descreva todos os eventos acionados. Isso significa o nome e as propriedades de cada evento e quando cada evento é acionado.
  • Liste o URL da biblioteca de gráficos que será usada na instrução <script> do cliente e forneça o URL da documentação.
  • Dê o nome totalmente qualificado do gráfico.
  • Crie páginas de amostra que demonstrem como usar o gráfico com as opções compatíveis, os eventos e os métodos personalizados.
  • Descreva claramente a política de dados do seu gráfico. A maioria dos gráficos processa os dados no navegador, mas alguns podem enviar dados a um servidor, por exemplo, para criar a imagem de um gráfico ou mapa. Se você enviar dados para um servidor:
    • Defina claramente quais dados são enviados.
    • Observe por quanto tempo os dados ficarão salvos no servidor.
    • Documente quais entidades terão acesso aos dados. Por exemplo, a Empresa XYZ etc.
    • Especifique se os dados serão registrados e por quanto tempo.

A documentação será hospedada no mesmo local que o código do gráfico (consulte Enviar seu gráfico para a galeria abaixo).

Depois de escrever o gráfico, envie-o para publicação na seção "Gráficos adicionais" da nossa galeria. Ao enviar um gráfico, você precisará assinar um contrato conosco, concordando em não criar software malicioso ou fazer uso indevido dos dados do usuário. A galeria é apenas uma lista de ponteiros para gráficos que criamos ou revisamos. É possível hospedar a biblioteca e a documentação JavaScript no seu próprio site ou permitir que o Google hospede a biblioteca e a documentação para você. Especifique se você quer que seu gráfico seja hospedado quando você postá-lo na galeria.

Solução de problemas

Se o código parece não estar funcionando, aqui estão algumas abordagens que podem ajudar a resolver seus problemas:

  • Procure erros de digitação. Lembre-se de que a linguagem JavaScript diferencia maiúsculas de minúsculas.
  • Use um depurador JavaScript. No Firefox, é possível usar o Console JavaScript, o venkman Debugger ou o complemento Firebug. No IE, use o Depurador de scripts da Microsoft.
  • Pesquise o grupo de discussão da API de gráficos do Google. Se você não encontrar uma postagem que responda à sua pergunta, publique a pergunta no grupo com um link para uma página da Web que demonstre o problema.

Localização

Se você espera que seu gráfico seja usado por pessoas em vários países, convém projetá-lo para ser localizado para diferentes idiomas e culturas. A localização mais básica é traduzir as strings de texto padrão na interface de acordo com as configurações do navegador do usuário. Uma forma mais avançada de localização seria alterar os formatos de número dependendo da localização ou, possivelmente, do design da IU. Se você decidir localizar seu gráfico, liste os idiomas compatíveis na documentação e defina uma configuração padrão para um idioma usado com frequência. Também é útil incluir um botão "Alterar idioma" na interface do seu gráfico, caso o idioma esteja errado. A maneira comum de detectar o idioma do navegador é observando o cabeçalho HTML Accept-Language.