Referencia de la API de visualización personalizada 2.0

Una llamada a la función looker.plugins.visualizations.add es el punto de entrada a la API de Visualization. Esta función acepta un objeto de visualización que define por completo tu visualización personalizada.

Esta es una visualización de ejemplo:

looker.plugins.visualizations.add({
    create: function(element, config){
        element.innerHTML = "<h1>Ready to render!</h1>";
    },
    updateAsync: function(data, element, config, queryResponse, details, doneRendering){
        var html = "";
        for(var row of data) {
            var cell = row[queryResponse.fields.dimensions[0].name];
            html += LookerCharts.Utils.htmlForCell(cell);
        }
        element.innerHTML = html;
        doneRendering()
    }
});

Entorno

Dado que la API de Visualization es JavaScript simple, puedes usar cualquier biblioteca de JavaScript para visualizar tus datos.

Tu código de JavaScript se ejecutará en un iframe en un entorno de pruebas, separado de tu instancia de Looker. De todos modos, los autores de visualizaciones personalizadas son responsables de garantizar que el código que escriban sea seguro.

Al igual que en todo el desarrollo web, la compatibilidad con diferentes navegadores web (Chrome, Edge, Firefox) puede ser un problema en ocasiones. La API de Visualization funciona en todos los navegadores compatibles con Looker, pero depende de ti garantizar la compatibilidad del navegador con tu código personalizado. Por ejemplo, los usos de ES6, como let o ()=>, funcionarán en la mayoría de los navegadores, pero pueden causar fallas en IE11 o cuando se renderizan archivos PDF con PhantomJS.

Instalación

Para instalar visualizaciones personalizadas, define un manifiesto con el formulario Administrador > Plataforma > Visualizaciones. Un manifiesto consta de un ID de cadena único, una etiqueta legible por humanos, el URI de tu visualización y vínculos a las dependencias que necesites (p. ej., d3, jQuery, underscore).

Las visualizaciones personalizadas deben entregarse como contenido HTTPS de forma externa a Looker. Si realizas la migración desde la primera versión de la API de visualización personalizada, es posible que tengas archivos en tu directorio looker/plugins/visualizations. Aún se puede acceder a esta ubicación y se puede proporcionar una ruta de acceso relativa a tu visualización, pero te recomendamos que migres tu contenido a una ubicación diferente. Dado que el directorio /plugins no está en el sistema de archivos compartidos, los entornos agrupados no tendrán acceso a tus archivos de visualización en todos los nodos.

El objeto de visualización

El objeto de visualización usa las siguientes propiedades obligatorias, opcionales y agregadas.

Propiedades obligatorias

• create función

  Se llama a esta función una vez, cuando se dibuja tu visualización por primera vez en la página. Se espera que configures todo lo que quieras que tu visualización siempre tenga disponible. Puedes cargar una biblioteca o crear un conjunto de elementos y controles que usarás más adelante.

  Consulta los detalles de la función create →

• updateAsync / update función

  Se llama a esta función cada vez que es posible que deba cambiar el estado de tu visualización. Siempre se llamará después de create y se puede llamar muchas veces, por lo que debe ser lo más rápido posible.

  Se puede llamar a esta función por muchos motivos, pero, por lo general, es cuando se cambió la consulta para visualizar, se cambió una opción de configuración o se cambió el tamaño de la visualización.

  Esta función tiene una versión síncrona y asíncrona :emdash; solo deberás especificar una. (Es un error definir ambas). El método asíncrono es más confiable para la renderización de PDF debido a la naturaleza de los iframes.

  Consulta los detalles de estas funciones update →

Propiedades opcionales

• options objeto

  Un objeto que detalla las opciones que los usuarios pueden configurar en tu visualización.

  Consulta los detalles para exponer una IU de configuración →

• destroy función Aún no se implementó en la API V2

  Una función a la que se llama justo antes de que se quite la visualización de la página. Usa esta función para limpiar los objetos de escucha de eventos o cualquier otro estado. Es posible que nunca se llame si, por ejemplo, el usuario cierra la ventana.

Propiedades agregadas

Looker agrega las siguientes propiedades a tu objeto automáticamente después de que la visualización se pasa a looker.plugins.visualizations.add. Puedes hacer referencia a ellas con this en el contexto de las funciones create, update, updateAsync y destroy.

• addError función

  Una función a la que puede llamar el código de visualización para indicarle a la IU que muestre un mensaje de error en lugar de la visualización. Toma un objeto error.

  Una vez que se agrega un error, permanecerá visible hasta que se llame a clearErrors.

  Ejemplo:

  this.addError({
      title: "Two Dimensions Required",
      message: "This really great visualization requires two dimensions."
  });
  

• clearErrors función

  Una función a la que puede llamar el código de visualización para borrar los errores que se agregaron con addError.

  Ejemplo:

  this.clearErrors();
  

• trigger función

  Una función a la que se puede llamar para activar un evento fuera de la visualización.

  Consulta los detalles sobre los eventos →

  Ejemplo:

  this.trigger("limit", [20]);
  

La función create

La función create recibirá dos parámetros: element y config.

create: function(element, config){
  // Your update code here.
},

Parámetros

• element DOMElement

  Un elemento DOM que representa un contenedor para renderizar tu visualización.

• config objeto

  Un objeto que representa los valores de las opciones de configuración que el usuario estableció para este gráfico.

  Ejemplo: {my_configuration_option: "User Value"}

Las funciones updateAsync y update

El método preferido para actualizar tu visualización es el método updateAsync. Este método permite que tu visualización realice una acción asíncrona, como cargar un archivo o enviar una solicitud web.

Esta versión de la función tiene un parámetro adicional, que es una devolución de llamada a la que se llamará cuando se complete la renderización:

updateAsync: function(data, element, config, queryResponse, details, done){
    // An example of an asynchronous update, fetching a file.
    d3.request("https://example.com/fun-file.docx").response(function(xhr) {
        // Your update code here that uses this file.
        done();
    });
}

Alertar a Looker cuando la visualización termina de renderizarse permite que Looker optimice la renderización de PDF y garantiza que las imágenes de las visualizaciones se capturen correctamente.

Algunas visualizaciones más antiguas usan la función update. Esta función aún funciona, pero no es el método preferido, ya que su uso significa que Looker no recibirá alertas cuando una visualización se renderice por completo. La función update recibirá cinco parámetros:

update: function(data, element, config, queryResponse, details){
  // Your update code here.
}

Parámetros

• data array

  Un array de filas que representan los datos actuales de la consulta. Tal vez null.

  Cada fila es un objeto con las claves que representan nombres de campos y el valor que representa un objeto "celda". Aquí encontrarás detalles sobre cómo trabajar con el objeto de celda.

• element DOMElement

  Un elemento DOM que representa un contenedor para renderizar tu visualización.

• config objeto

  Un objeto que representa los valores de las opciones de configuración que el usuario estableció para este gráfico.

  Ejemplo: {my_configuration_option: "User Value"}

• queryResponse objeto

  Un objeto que representa metadatos sobre la consulta actual, como metadatos sobre campos. Tal vez null.

• details objeto

  Detalles sobre el contexto de renderización actual. Contiene información sobre por qué se renderiza el gráfico y qué cambió. Por lo general, esta información solo se usa en casos avanzados.

  En relación con los filtros cruzados en los paneles de Looker que usan la nueva experiencia del panel, los atributos permitidos incluyen crossfilterEnabled y crossfilters.

  El atributo print se puede usar junto con la función done para mejorar la renderización de PDF para visualizaciones personalizadas, en especial aquellas que incluyen animación. Por ejemplo:

  if (details.print) {
          done();
  }
  

• done función

  Una devolución de llamada para indicar que la visualización se renderizó por completo. Es muy importante llamar a esta función si tu visualización necesita realizar llamadas asíncronas o debe renderizarse como un PDF.

Renderizar datos

Looker tiene un conjunto enriquecido de herramientas de formato de datos en LookML que se pueden usar para personalizar la apariencia y el comportamiento de los puntos de datos. Estas herramientas incluyen parámetros de configuración de LookML a nivel de campo, como formatos de valores personalizados, HTML, vínculos de desglose y acciones de datos.

Las celdas tienen una propiedad value, que es la única propiedad que existe en todos los casos. Esta propiedad es un tipo de JavaScript que coincide con el tipo de campo al que pertenece la celda. Sin embargo, no es seguro insertar una propiedad value directamente en HTML o SVG, ya que no se realizó ningún escape de HTML, y algunos valores de campo son objetos de JavaScript o arrays complejos que se renderizarán de formas no deseadas o confusas.

Para garantizar que todas las visualizaciones rendericen estos elementos de manera coherente y segura, existen varias funciones de utilidad para convertir los metadatos de la celda que se pasan a tu gráfico en data en diferentes representaciones para diferentes propósitos. En algunos casos, los metadatos de la celda pueden comprimir o omitir ciertos campos, y estas funciones auxiliares te permitirán proporcionar una experiencia coherente.

Todas estas funciones auxiliares están disponibles en el objeto global LookerCharts.Utils.

• LookerCharts.Utils.textForCell(cell)

  Esta función acepta una celda y muestra una representación de cadena de ella que es adecuada para mostrarse. Siempre será una cadena. Esta función nunca muestra null ni ningún otro tipo.

• LookerCharts.Utils.htmlForCell(cell)

  Esta función acepta una celda y muestra una cadena que contiene HTML. Siempre será una cadena. Esta función nunca muestra null ni ningún otro tipo.

  El resultado de esta función se escapa correctamente y es adecuado para insertarse directamente en el HTML de tu elemento. El HTML de salida también mostrará correctamente el menú de desglose cuando se haga clic en él cuando sea adecuado para los datos.

• LookerCharts.Utils.filterableValueForCell(cell)

  Esta función acepta una celda y muestra una cadena de sintaxis de filtro avanzado de Looker que coincidiría con el valor de esta celda.

• LookerCharts.Utils.toggleCrossfilter({row, pivot, event})

  Esta función acepta una fila, un pivote o un evento y se usa para verificar si el filtro cruzado está habilitado para una visualización. En el siguiente ejemplo, se muestra cómo agregar un objeto de escucha de eventos a un elemento que verifica si el filtro cruzado está habilitado cuando se produce el evento:

  d3.select("#myElement")
  .on("click", function (d) {
      if (details.crossfilterEnabled) {
              LookerCharts.Utils.toggleCrossfilter({
                  row: d.row,
                  event: d3.event,
              });
      } else {
        // ... handle click when cross-filtering is not enabled
      }
  });
  

• LookerCharts.Utils.getCrossfilterSelection(row, pivot?)

  Esta función acepta una fila o un pivote y se usa para verificar si esa fila o pivote está seleccionado en una visualización personalizada. La función muestra una enumeración para CrossfilterSelection {NONE, SELECTED, UNSELECTED} de 0 si NONE, 1 si SELECTED y 2 si UNSELECTED.

  En el siguiente ejemplo, se aplica condicionalmente un color de relleno a una fila si se filtra de forma cruzada y se aplican colores predeterminados si el filtro cruzado no está habilitado para esa fila:

  d3.select("#myElement")
  .attr("fill", function (d) {
      const crossfilter = LookerCharts.Utils.getCrossfilterSelection(d.row)
      if (details.crossfilterEnabled && crossfilter === 1) {
              return d.color
      } else {
              return "#DEE1E5" //Hex used for unselected elements in native visualizations
  ...
  

• LookerCharts.Utils.openDrillMenu(options)

  El resultado de htmlForCell mostrará automáticamente el menú de desglose si es necesario, pero es posible que no sea adecuado para ciertos tipos de renderización. (Por ejemplo, SVG no puede renderizar HTML, pero es posible que quieras capturar un evento de clic para iniciar un desglose).

  El objeto options tiene los siguientes parámetros:

  • links Obligatorio array

    Un array de los objetos que se muestran desde la propiedad links de una celda. Si deseas mostrar vínculos para varias celdas a la vez, puedes concatenar estos arrays primero. Para los vínculos personalizados, proporciona un array de objetos con el siguiente formulario:

    { label: string, type: 'drill', type_label: string, url: url }

  • event Evento DOM de HTML

    El evento de clic (o de otro tipo) que causó el evento de desglose. Looker lo usará para determinar dónde colocar el menú de desglose. Si no tienes uno, intenta pasar un objeto con las coordenadas pageX y pageY.

  Ejemplo:

  for (var row of data) {
      var cell = row[queryResponse.fields.dimensions[0].name];
      var cellElement = myBuildElementFunction(cell);
      cellElement.onclick = function(event) {
          LookerCharts.Utils.openDrillMenu({
              links: cell.links,
              event: event
          });
      };
      // ... more visualization stuff...
  }
  

Presentar la IU de configuración

El parámetro options es un objeto en el que las claves son un identificador arbitrario para un nombre de opción, y el valor es un objeto que describe información sobre la opción.

Por ejemplo:

options: {
    color_range: {
      type: "array",
      label: "Color Range",
      display: "colors"
    },
   top_label: {
      type: "string",
      label: "Label (for top)",
      placeholder: "My Great Chart"
    },
    transport_mode: {
      type: "string",
      label: "Mode of Transport",
      display: "select",
      values: [
         {"Airplane": "airplane"},
         {"Car": "car"},
         {"Unicycle": "unicycle"}
      ],
      default: "unicycle"
    }
}

Parámetros del objeto de opción

El objeto option tiene los siguientes parámetros básicos, propiedades específicas de la pantalla y opciones de organización.

Parámetros básicos

• type string

  El tipo de datos de la opción.

  Valores permitidos: string (predeterminado), number, boolean, array

• label string

  La etiqueta legible por humanos de la opción que se mostrará al usuario.

• default

  El valor predeterminado de la opción. Si no se especifica, el valor de la opción es null. Debe ser un valor del mismo tipo que type.

• display string

  Ciertos valores type se pueden presentar en la IU de diferentes maneras.

  • cuando type es string:

    Valores permitidos: text (predeterminado), select, radio

  • cuando type es number:

    Valores permitidos: number (predeterminado), range

  • cuando type es array:

    Valores permitidos: text (predeterminado), color, colors

• placeholder string

  Para los valores display que lo admiten, un valor o una explicación de ejemplo para darle al usuario una sugerencia sobre qué escribir.

Propiedades específicas de la pantalla

• values array de objetos

  Cuando display es radio o select, un array que contiene etiquetas y valores que se mostrarán en la interfaz.

  Cada elemento del array debe ser un objeto con un solo par clave-valor, que representa la etiqueta y el valor de la opción. La etiqueta se presentará solo en la IU; en el momento de la renderización, solo recibirás el valor.

  Ejemplo:

  values: [
      {"Center": "c"},
      {"Left": "l"},
      {"Right": "r"}
  ]
  

  Si display es radio, cada opción puede recibir una description adicional:

  values: [
      {"Cool": "c"},
      {"Uncool": {
              value: "unc",
              description: "Only choose this if the data is very uncool."
          }
      }
  ]
  

• max number

  Cuando display es range, es el número máximo que puede seleccionar el control deslizante de rango.

• min number

  Cuando display es range, es el número mínimo que puede seleccionar el control deslizante de rango.

• step number

  Cuando display es range, es la cantidad que representa cada marca del control deslizante de rango.

Opciones de organización

• section string

  Para los gráficos con muchas opciones, una etiqueta para la sección en la que debe aparecer una opción. La IU agrupará las opciones por sus valores section. Si solo hay una sección, no se mostrará la IU de la sección.

  Si usas section, debes configurarlo en cada opción.

• order number

  Un número que representa el orden de las opciones para la presentación en la IU. Si se especifica, las opciones se ordenarán según este orden.

• display_size string

  Una clase de tamaño que representa el ancho de la opción en la IU. Por ejemplo, si deseas mostrar una opción "Mínimo" y una "Máximo" una al lado de la otra, puedes establecer cada uno de sus tamaños de visualización en half.

  Valores permitidos: normal (predeterminado), half, third

Eventos

El gráfico puede activar eventos (por lo general, en respuesta a la interacción del usuario) que pueden actualizar las propiedades de la visualización o la consulta.

Se pueden activar llamando a la función trigger en el objeto de visualización. El primer parámetro siempre es el nombre del evento y el segundo parámetro es un array de argumentos.

this.trigger("limit", [20]);

Eventos disponibles

• updateConfig

  Actualiza la configuración actual del gráfico.

  Argumento: Un objeto que contiene claves de configuración para actualizar. Las claves no especificadas no se cambian.

  Ejemplo:

  var vis = this;
  $(element).find(".axis").click(function(){
      vis.trigger("updateConfig", [{axis_hidden: true}]);
  });
  

• limit

  Actualiza el límite de la consulta subyacente:

  Argumento: Un número entero que representa un nuevo límite para la consulta.

  var vis = this;
  $(element).find(".show-all").click(function(){
      vis.trigger("limit", [500]);
  });
  

• filter

  Actualiza el valor de un filtro en la consulta subyacente:

  var vis = this;
  $(element).find(".show-all-tommys").click(function(){
      vis.trigger("filter", [{
          field: "users.name", // the name of the field to filter
          value: "%tommy%", // the "advanced syntax" for the filter
          run: true, // whether to re-run the query with the new filter
      }]);
  });
  

• loadingStart

  Marca la visualización como cargando. La mayoría de las veces, esto no es necesario, pero, si tu visualización carga un objeto desde una ubicación remota o realiza un cálculo largo, puedes usarlo para seguir mostrando el indicador de carga.

  Aparecerá cargando hasta que se active loadingEnd.

• loadingEnd

  Marca la visualización como que ya no se está cargando.

• printSize (Looker 26.0+)

  Permite que las visualizaciones aprovechen la opción "Expandir las tablas para mostrar todas las filas" cuando se renderizan paneles en PDF. El uso de este evento permite que la aplicación sepa qué tan alto es el contenido renderizado y pueda expandir la tarjeta del panel de forma adecuada para que toda la información sea visible para la impresión.

    this.trigger('printSize', {
      heightExpanded: FULL_HEIGHT_IN_PIXELS
    });
  

• registerOptions (Looker 5.24+)

  Permite que las visualizaciones registren opciones adicionales después de que se haya registrado la visualización:

    update: function(data, element, config, queryResponse, details){
      options = {}
      // Create an option for each measure in your query
      queryResponse.fields.measure_like.forEach(function(field) {
        id = "color_" + field.name
        options[id] =
        {
      label: field.label_short + " Color",
      default: "#8B7DA8",
      section: "Style",
      type: "string",
      display: "color"
        }
      })
      this.trigger('registerOptions', options) // register options with parent page to update visConfig
      ...
    }
  });