Cómo controlar eventos

En esta página, se describe cómo detectar y controlar los eventos que activa un gráfico.

Contenido

  1. Overview
  2. Cómo registrarse en un evento y manejarlo
  3. Cómo recuperar información de eventos
  4. Evento select
  5. El evento ready
  6. El evento error
  7. Ejemplo de manejo de eventos

Descripción general

Los gráficos de Google pueden activar eventos que puedes escuchar. Los eventos se pueden activar mediante acciones del usuario, como cuando hace clic en un gráfico. Puedes registrar un método de JavaScript para que se llame cada vez que se activen ciertos eventos, posiblemente con datos específicos de ese evento.

Cada gráfico define sus propios eventos y, en la documentación de ese gráfico, se debe describir cuándo se activa cada evento, qué significa y cómo recuperar cualquier información asociada con el evento. En esta página, se describe cómo registrarse para recibir eventos de un gráfico y cómo controlarlos.

Hay un evento que debe activar cualquier gráfico seleccionable: el evento de selección. Sin embargo, cada gráfico define el comportamiento y el significado de este evento.

Es importante tener en cuenta que los eventos del gráfico son independientes y diferentes de los eventos estándares del DOM.

Cómo registrarse en un evento y controlarlo

Para registrar los controladores de eventos, llama a google.visualization.events.addListener() o addOneTimeListener() con el nombre del gráfico que expone el evento, el nombre de la cadena del evento que se debe escuchar y el nombre de la función a la que se debe llamar cuando se activa ese evento. Tu función debe aceptar un solo parámetro, que es el evento que se activó. Este evento puede tener información personalizada sobre el evento, como se describe en la documentación del gráfico.

Importante: Si el gráfico expone un evento listo, siempre debes esperar a que se active ese evento antes de intentar enviar métodos o recibir eventos del gráfico. Estos gráficos pueden funcionar antes de que arrojan un evento listo, pero ese comportamiento no está garantizado.

En el siguiente fragmento de código, se muestra un cuadro de alerta cada vez que el usuario hace clic en una fila de la tabla:

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

Ten en cuenta que esto solo se registrará para escuchar los eventos de este objeto de tabla específico; solo puedes registrarte para recibir eventos de un objeto específico.

También puedes pasar una definición de función, como se muestra aquí:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Cómo recuperar información de eventos

En general, los eventos exponen la información de dos maneras: pasando información a la función del controlador como un parámetro o agregando información a un objeto global. Si el evento expone la información y de qué manera lo hace, se debe describir en la documentación de ese gráfico. A continuación, te mostramos cómo recuperar ambos tipos de información:

Información del evento que se pasa a tu controlador

Si el gráfico pasa datos como parámetro a tu función de manejo, los recuperarías como se muestra a continuación:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

El parámetro que se pase a tu controlador tendrá una propiedad que se debe documentar para el gráfico. Para ver un ejemplo de un gráfico que expone la información del evento de esta manera, consulta el evento de página del gráfico Tabla.

Información del evento que se pasa a un objeto global

En cambio, algunos eventos cambian una propiedad de un objeto global, que luego puedes solicitar. Un ejemplo común de esto es el evento "select", que se activa cuando un usuario selecciona una parte de un gráfico. En este caso, el código debe llamar a getSelection() en el gráfico para saber cuál es la selección actual. A continuación, se brinda más información sobre el evento de selección.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');

El evento select

Como se mencionó anteriormente, cualquier gráfico que se pueda seleccionar debe activar un evento "select" que funcione de manera estándar para que puedas recuperar los valores del elemento seleccionado en el gráfico. (Sin embargo, no hay un requisito absoluto de que un gráfico se comporte de esta manera; consulta la documentación de tu gráfico).

En general, los gráficos que exponen el evento "select" están diseñados con las siguientes especificaciones:

  • El evento de selección no pasa ninguna propiedad ni ningún objeto al controlador (el controlador de tu función no debe esperar que se le pase ningún parámetro).
  • El gráfico debe exponer el método getSelection(), que muestra un array de objetos que describen los elementos de datos seleccionados. Estos objetos tienen las propiedades row y column. row y column son los índices de filas y columnas del elemento seleccionado en DataTable. (Los eventos de selección describen los datos subyacentes en el gráfico, no los elementos HTML del gráfico). Para obtener los datos del elemento seleccionado, deberás llamar a DataTable.getValue() o getFormattedValue().
    Si se especifican row y column, el elemento seleccionado es una celda. Si solo se especifica row, el elemento seleccionado es una fila. Si solo se especifica column, el elemento seleccionado es una columna.
  • El gráfico debe exponer el método setSelection(selection) para cambiar la selección en la tabla subyacente y seleccionar los datos correspondientes en el gráfico. El parámetro selection, que es un array similar al array getSelection(), en el que cada elemento es un objeto con las propiedades row y column. La propiedad row define el índice de la fila seleccionada en DataTable, y la propiedad column define el índice de la columna seleccionada en DataTable. Cuando se llama a este método, el gráfico debe indicar visualmente cuál es la nueva selección. La implementación de setSelection() no debe activar un evento "select".
    Si se especifican row y column, el elemento seleccionado es una celda. Si solo se especifica row, el elemento seleccionado es una fila. Si solo se especifica column, el elemento seleccionado es una columna.

Algunas advertencias:

  • Es posible que el gráfico ignore parte de la selección. Por ejemplo, una tabla que solo puede mostrar filas seleccionadas puede ignorar elementos de celdas o columnas en su implementación de setSelection).
  • Es posible que algunos gráficos no activen un evento de selección y que otros solo admitan la selección de filas completa o de columnas completas. La documentación de cada gráfico define los eventos y métodos que admite.
  • La selección múltiple se controla de manera diferente en los distintos gráficos (algunos ni siquiera lo permiten).
  • Para leer los datos seleccionados, deberás llamar a DataTable.getValue() en tu controlador. La forma más sencilla de habilitarlos es hacer que el objeto DataTable sea global.

En el siguiente ejemplo, se muestra un cuadro de alerta con los elementos seleccionados de la tabla cuando se selecciona un elemento de un gráfico de tabla:

Ten en cuenta que el gráfico de tabla solo activa los eventos de selección de filas. Sin embargo, el código es genérico y se puede usar para eventos de selección de filas, columnas y celdas.

Este es el código del controlador para ese ejemplo:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

El evento ready

La mayoría de los gráficos se renderizan de forma asíncrona. Todos los gráficos de Google muestran un evento listo después de que llamas a draw(), lo que indica que el gráfico se renderiza y está listo para mostrar propiedades o controlar más llamadas de método. Siempre debes escuchar el evento de elemento listo antes de llamar a los métodos después de llamar a draw().

En general, los gráficos que exponen el evento "listo" están diseñados con las siguientes especificaciones:

  • El evento ready no pasa ninguna propiedad al controlador (el controlador de tu función no debe esperar que se le pase ningún parámetro).
  • El gráfico debe activar el evento ready una vez que esté listo para la interacción. Si el dibujo del gráfico es asíncrono, es importante que el evento se active cuando se pueda llamar a los métodos de interacción, y no solo cuando finalice el método draw.
  • Debes agregar un objeto de escucha a este evento antes de llamar al método draw(). De lo contrario, el evento podría activarse antes de que se configure el objeto de escucha y no lo podrás capturar.
  • Si llamas a los métodos de interacción antes de que se active el evento ready, corres el riesgo de que estos métodos no funcionen correctamente.

La convención es que los gráficos que no activan un evento "listo" están listos para la interacción inmediatamente después de que finalice el método draw y le muestre el control al usuario. Si el gráfico sí activa un evento listo, debes esperar a que se muestre antes de llamar a métodos, como se muestra a continuación:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

Sintaxis del controlador de eventos listo

function myReadyHandler(){...}

El controlador de eventos listo no recibe ningún parámetro.

El evento error

Los gráficos deben mostrar un evento de error cuando se encuentran con algún tipo de error para que puedas manejarlo correctamente. Al controlador de eventos se le pasa una descripción del error, así como propiedades del evento personalizadas específicas de cada gráfico. Debes suscribirte a este evento inmediatamente después de crear una instancia del gráfico para capturar cualquier error que pueda ocurrir en pasos posteriores.

Puedes usar las funciones auxiliares goog.visualization.errors para mostrar cualquier error al usuario de forma correcta.

Sintaxis del controlador de eventos de errores

function myErrorHandler(err){...}

El controlador de eventos de error debe pasar un objeto con los siguientes miembros:

  • id (obligatorio): Es el ID del elemento DOM que contiene el gráfico o un mensaje de error que se muestra en lugar del gráfico si no se puede renderizar.
  • message [obligatorio]: Una cadena de mensaje breve que describe el error
  • detailedMessage (opcional): Es una explicación detallada del error.
  • options (opcional): Es un objeto que contiene parámetros personalizados adecuados para este error y tipo de gráfico.

Ejemplo de manejo de eventos

En el siguiente ejemplo, se muestran getSelection() y setSelection(). Sincroniza la selección entre dos gráficos que usan la misma tabla de datos. Haz clic en cualquiera de los gráficos para sincronizar la selección en el otro gráfico.

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Haz clic en los siguientes gráficos en las filas de la tabla o en los elementos de los gráficos para ver la selección en acción: