Como criar tipos de gráfico

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

Público

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

Criar um gráfico

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

  1. Escolha um namespace para seu código. Outras páginas hospedarão seu código. Evite conflitos de nomenclatura.
  2. Implemente seu objeto gráfico. Implemente um objeto JavaScript que exponha o seguinte:
    • Um construtor,
    • Um método draw() para desenhar o objeto dentro do elemento DOM transmitido ao construtor,
    • Todos os outros métodos padrão opcionais que um cliente pode usar, como getSelection().
    • Todos os métodos personalizados que você quer expor aos seus clientes.
  3. [Opcional] Implemente todos os eventos que você quer disparar para que o cliente capture.
  4. Escreva a documentação do gráfico. Se você não documentá-lo, as pessoas provavelmente não poderão incorporá-lo.
  5. Publique seu gráfico na Galeria de gráficos.

Dica

  • É possível fazer o download das definições da classe e do 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 projeto. A maioria dos ambientes de desenvolvimento integrado o indexará automaticamente e ativará o preenchimento automático, embora o ambiente de desenvolvimento integrado possa ser diferente. O arquivo nem sempre estará atualizado. Consulte as páginas de referência para ver a referência mais recente da API.

Escolher um namespace

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

Veja um exemplo de como criar um objeto de namespace para armazenar uma classe de gráfico chamada MyTable, bem como qualquer variável global necessária:

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

Evitar conflitos de CSS

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

td.example {color: blue;}

Em seguida, envolva o gráfico em uma <div> com :

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

Implementar o gráfico

É necessário 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 necessários são os construtores e os métodos draw(). Você também pode expor ao usuário outros métodos apropriados para o gráfico. Mas não se esqueça de que é mais fácil usar os serviços.

O construtor

Seu gráfico precisa expor um único construtor que use um único parâmetro, um elemento DOM em que 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 do gráfico precisa ter um método draw() definido no protótipo da classe do 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 com opções de nome/valor para seu gráfico. Os nomes e tipos de valor das opções são definidos por você no gráfico específico. No exemplo "Hello Chart" abaixo, o gráfico aceita uma opção chamada "showLineNumber" com um valor do tipo booleano. Ofereça compatibilidade com 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 deve estar preparado para usar todos os valores padrão se o usuário não transmitir esse parâmetro (mais informações).
example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Olá, gráfico!

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

Veja 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 acessível no 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 timer ou eventos iniciados pelo usuário, como cliques), você precisará chamar a função google.visualization.events.trigger com os detalhes do evento (nome, propriedades a serem enviadas etc.). Veja detalhes na página Eventos. É possível expor os detalhes do evento ao cliente adicionando propriedades ao objeto, ou ainda expor um método get...() de algum tipo no gráfico, e o cliente pode chamar esse método para coletar os detalhes do evento. Em ambos os casos, documente bem seus métodos ou propriedades de evento.

Documentar seu gráfico

Se você não documentar corretamente o gráfico, provavelmente não terá muitos usuários. Não se esqueça de documentar o seguinte:

  • Descreva todos os métodos compatíveis. O método draw() é comum para todos os gráficos, mas cada gráfico é compatível com os próprios métodos. Provavelmente, não será necessário documentar o construtor, a menos que ele tenha um comportamento diferente do padrão. Encontre 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 que você aciona. Isso significa o nome e as propriedades de cada evento e quando cada um é acionado.
  • Liste o URL da biblioteca de gráficos que precisa ser usado na instrução de inclusão <script> do cliente e forneça o URL da documentação.
  • Escolha o nome totalmente qualificado do gráfico.
  • Crie páginas de amostra que demonstrem como usar seu gráfico com as opções aceitas por ele, seus eventos e 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 para um servidor, por exemplo, para criar uma imagem de um gráfico ou um 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, 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 postagem na seção "Gráficos adicionais" da galeria. O envio de um gráfico significa que 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 os gráficos que criamos ou que analisamos. Você pode hospedar a biblioteca JavaScript e a documentação reais no seu próprio site ou o Google pode hospedar a biblioteca e a documentação para você. Especifique se você quer que seu gráfico seja hospedado ao publicá-lo na galeria.

Solução de problemas

Se o código parece não estar funcionando, veja algumas abordagens que podem ajudar a resolver os 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, use o console JavaScript, o depurador Venkman ou o complemento Kubeflow. No IE, é possível usar o Depurador de scripts da Microsoft.
  • Pesquise o grupo de discussão da API Google Chart. Se você não encontrar uma postagem que responda à sua pergunta, poste-a 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, procure criar um gráfico localizado para diferentes idiomas e culturas. A localização mais básica é traduzir as strings de texto padrão na IU de acordo com as configurações do navegador do usuário. Uma forma mais avançada de localização seria mudar os formatos de número de acordo com a localização ou até mesmo o design da IU. Se você decidir localizar o gráfico, liste os idiomas compatíveis com a documentação e defina a configuração padrão dos idiomas mais usados. Também é útil incluir um botão "Alterar idioma" na IU do gráfico, caso o idioma esteja incorreto. A maneira comum de detectar o idioma do navegador é analisar o cabeçalho HTML Accept-Language.