Crea tipos de gráficos

En esta página, se describe cómo desarrollar tu propio tipo de gráfico y ponerlo a disposición de los usuarios.

Público

En esta página, se supone que leíste la página Cómo usar gráficos. También se supone que estás familiarizado con JavaScript y la programación orientada a objetos. Hay muchos instructivos de JavaScript disponibles en la Web.

Cómo crear un gráfico

Los gráficos se exponen al usuario a través de una biblioteca de JavaScript que creas. Estos son los pasos para crear una biblioteca de gráficos:

1. Elige un espacio de nombres para tu código. Tu código se alojará en otras páginas. Evita conflictos de nombres.
2. Implementa el objeto de gráfico. Implementa un objeto JavaScript que exponga lo siguiente:
   • Un constructor,
   • Un método draw() para dibujar tu objeto dentro del elemento del DOM que se pasa al constructor.
   • Cualquier otro método estándar opcional que use un cliente, como getSelection()
   • Cualquier método personalizado que quieras exponer a tus clientes
3. [Opcional] Implementa cualquier evento que quieras activar para que el cliente detecte.
4. Escribe la documentación para el gráfico. Si no lo documentas, es probable que las personas no puedan incorporarlo.
5. Publica el gráfico en la Galería de gráficos.

Elige un espacio de nombres

Tu gráfico puede incorporarse en una página que aloje otros gráficos o cualquier otro JavaScript no relacionado. Para evitar conflictos de nombres con otros nombres de código o clases de CSS, debes elegir un espacio de nombres único para el código del gráfico. Una buena opción para un espacio de nombres es la URL que usarás para alojar tu secuencia de comandos (sin WWW y cualquier extensión). Por ejemplo, si tu gráfico se publicará en www.example.com, debes usar example como tu espacio de nombres único. Puedes agregar sufijos adicionales separados por caracteres . marcas para agrupar aún más tu gráfico (todos los gráficos de Google tienen el espacio de nombres google.visualization). Usa tu objeto de espacio de nombres para almacenar el objeto de gráfico, así como cualquier variable global que puedas necesitar.

A continuación, se muestra un ejemplo de cómo crear un objeto de espacio de nombres para conservar una clase de gráfico llamada MyTable, así como cualquier variable global necesaria:

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

Cómo evitar conflictos de CSS

Si usas CSS, asegúrate de no escribir reglas de CSS que puedan afectar otros gráficos de la página. Por ejemplo, no se recomienda usar una regla como td {color: blue;}, ya que afectará a cualquier otro elemento <td> de la página, no solo al gráfico. Una forma de solucionar esto es encerrar todo tu gráfico en una <div> con un nombre de clase y hacer que todas tus reglas de CSS se apliquen solo a los elementos que sean subordinados de un elemento con ese nombre de clase. Por ejemplo, la siguiente regla de CSS afectará solo a los elementos <td> que tengan un elemento con el nombre de clase "example" como principal.

td.example {color: blue;}

Luego, puedes unir tu gráfico en una <div> con lo siguiente :

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

Cómo implementar el gráfico

Deberás implementar el gráfico como un objeto JavaScript que expone los métodos estándar descritos en la sección de referencia. Los dos métodos obligatorios son el constructor y los métodos draw(). También puedes exponer cualquier método adicional a tu usuario que sea apropiado para tu gráfico. Solo recuerda que más fácil de usar es mejor.

El constructor

El gráfico debe exponer un solo constructor que tome un solo parámetro, un elemento del DOM en el que dibujarás el gráfico. Por lo general, los gráficos almacenan una copia local de este elemento en el constructor para su uso posterior:

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

El método draw()

Tu clase de gráfico debe tener un método draw() definido en el prototipo de la clase de gráfico. El método draw() acepta dos parámetros:

1. Un DataTable que contiene los datos que se mostrarán.
2. Un mapa opcional de opciones de nombre/valor para tu gráfico. Tú defines los nombres y tipos de valores de las opciones para tu gráfico específico. Por ejemplo, en el siguiente ejemplo del gráfico de Hello, el gráfico admite una opción llamada “showLineNumber” con un valor de tipo booleano. Debes admitir un valor predeterminado para cada opción, en caso de que el usuario no pase un valor para una opción específica. Este parámetro es opcional, por lo que también debes prepararte para usar todos los valores predeterminados si el usuario no lo pasa (más información).

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Hola gráfico:

A continuación, se muestra un gráfico simple que muestra datos de DataTable como una tabla HTML:

Este es el código de implementación:

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

Cómo incluir tu gráfico en una página web

Para usar el gráfico anterior, guárdalo en un archivo .js al que se pueda acceder desde tu navegador. Luego, guarda el siguiente código y cambia el parámetro de origen <script> para que apunte a tu archivo 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>

 

Cómo implementar tus eventos

Si deseas que el gráfico active eventos útiles (por ejemplo, eventos de temporizador o eventos iniciados por el usuario, como clics), deberás llamar a la función google.visualization.events.trigger con los detalles del evento (nombre, propiedades que se enviarán, etc.). Puedes encontrar más detalles en la página Eventos. Puedes exponer los detalles de tu evento al cliente agregando propiedades al objeto de evento o puedes exponer un método get...() de algún tipo en tu gráfico, y el cliente puede llamar a ese método para obtener los detalles del evento. En cualquier caso, documenta bien tus métodos o propiedades de eventos.

Documenta tu gráfico

Si no documentas correctamente tu gráfico, es probable que no tengas muchos usuarios. Asegúrate de documentar la siguiente información:

• Describe todos los métodos que admites. El método draw() es común a todos los gráficos, pero cada gráfico puede admitir sus propios métodos adicionales. (Es probable que no necesites documentar tu constructor, a menos que tenga un comportamiento no estándar). Puedes encontrar una lista de los métodos esperados en la página de referencia.
• Describe todas las opciones que admite tu método draw(). Esto incluye el nombre de cada opción, el tipo de valor esperado y su valor predeterminado.
• Describe todos los eventos que activas. Esto significa el nombre y las propiedades de cada evento, y cuándo se activa cada uno.
• Indica la URL de la biblioteca de gráficos que se debe usar en la sentencia de inclusión <script> del cliente, y proporciona la URL de la documentación.
• Proporciona el nombre completamente calificado de tu gráfico.
• Crea páginas de muestra que demuestren cómo usar tu gráfico con las opciones que admite, sus eventos y métodos personalizados.
• Describe con claridad la política de datos de tu gráfico. La mayoría de los gráficos procesan los datos dentro del navegador, pero algunos pueden enviar datos a un servidor, por ejemplo, para crear una imagen de un gráfico o un mapa. Si envías datos a un servidor, sigue estos pasos:
  • Define claramente qué datos se envían.
  • Ten en cuenta cuánto tiempo se guardarán los datos en el servidor.
  • Documenta qué entidades tendrán acceso a los datos. Por ejemplo, la empresa XYZ, etcétera.
  • Especifica si los datos se registrarán y por cuánto tiempo.

La documentación se alojará en el mismo lugar que el código de tu gráfico (consulta Enviar tu gráfico a la galería a continuación).

Cómo enviar tu gráfico a la galería

Después de escribir el gráfico, envíalo para publicarlo en la sección "Gráficos adicionales" de nuestra galería. Si envías un gráfico, deberás firmar un acuerdo con nosotros que aceptes no crear software malicioso o hacer un uso inadecuado de los datos del usuario. La galería es solo una lista de punteros a los gráficos que creamos o que revisamos. Puedes elegir alojar la biblioteca y la documentación de JavaScript en tu propio sitio, o puedes hacer que Google aloje la biblioteca y la documentación por ti. Especifica si quieres que alojemos tu gráfico cuando lo publiques en la galería.

Solución de problemas

Si parece que tu código no funciona, a continuación, se incluyen algunos enfoques que pueden ayudarte a resolver los problemas:

• Busca errores de ortografía. Recuerda que JavaScript es un lenguaje en el que se distinguen mayúsculas y minúsculas.
• Usar un depurador de JavaScript En Firefox, puedes usar la consola de JavaScript, Venkman Debugger o el complemento de FireEye. En IE, puedes usar el Microsoft Script Debugger.
• Busca en el grupo de discusión de la API de Google Chart. Si no encuentras una publicación que responda a tu pregunta, publícala en el grupo junto con un vínculo a una página web que demuestre el problema.

Localización

Si esperas que personas de diferentes países usen tu gráfico, te recomendamos que diseñes tu gráfico con el fin de localizarlo a diferentes idiomas y culturas. La localización más básica consiste en traducir las cadenas de texto estándar en la IU según la configuración del navegador del usuario. Una forma más avanzada de localización sería cambiar los formatos de número según la localización o, posiblemente, incluso el diseño de la IU. Si decides localizar tu gráfico, enumera los idiomas que admite el gráfico en tu documentación y proporciona una configuración predeterminada de un idioma de uso común. También es útil incluir un botón "cambiar idioma" en la IU de tu gráfico, en caso de que no escribas el idioma correcto. La forma común de detectar el idioma del navegador es mirar el encabezado HTML Accept-Language.