Cómo compilar extensiones de mosaicos

A partir de Looker 24.0, las extensiones se pueden desarrollar para ejecutarse en un mosaico en los paneles. Las extensiones que se pueden ejecutar como mosaico o visualización se pueden agregar mientras el panel está en modo de edición o guardarse en un panel como una visualización de una exploración. Las extensiones también se pueden configurar como tarjetas en los paneles de LookML.

Hay ejemplos de extensiones que se pueden usar como tarjetas de panel:

Cómo usar el SDK de extensiones de Looker con extensiones de tarjetas

Las extensiones de tarjetas requieren que se defina el parámetro mount_points en el archivo de manifiesto del proyecto de LookML para que las extensiones se carguen como tarjetas en un panel. Existen dos tipos de mount_points relacionados con las extensiones de tarjetas:

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }
  • dashboard_vis: Cuando se habilita, la extensión aparecerá en las opciones de visualización de una exploración, donde se puede seleccionar como una visualización y guardar como tarjeta de panel. Cuando se ejecute el panel, este ejecutará la consulta asociada con la tarjeta y pondrá los datos a disposición de la extensión. Esto es similar a la forma en que funcionan las visualizaciones personalizadas. La principal diferencia entre una visualización personalizada y una extensión que se ejecuta en una tarjeta de panel que tiene habilitada dashboard_vis es que la extensión puede realizar llamadas a la API de Looker.
  • dashboard_tile: Si se habilita, la extensión aparecerá en el panel Extensiones que se muestra cuando un usuario edita un panel y selecciona la opción Extensiones después de hacer clic en el botón Agregar. Este tipo de extensión se encarga de recuperar sus propios datos, en lugar de hacer que la consulta de mosaicos le proporcione datos automáticamente a la extensión.

Un punto de activación adicional, standalone, hace que la extensión aparezca en la sección Applications del menú principal de Looker. Es posible que una extensión tenga varios puntos de activación definidos. Durante el tiempo de ejecución, la extensión recibe una notificación sobre cómo se activa y puede ajustar su comportamiento en consecuencia. Por ejemplo, es posible que las extensiones standalone deban establecer su propia altura, mientras que las extensiones de tarjetas no.

APIs adicionales de extensión de tarjetas

Las extensiones de tarjetas se proporcionan con APIs y datos adicionales en el tiempo de ejecución. Estos se obtienen del contexto de la extensión:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)
  • tileSDK: Proporciona funciones específicas de mosaicos para permitir que la extensión interactúe con el host del panel de Looker. Por ejemplo, para permitir que la extensión muestre y borre mensajes de error.
  • tileHostData: Proporciona datos de mosaicos a la extensión. Los datos se actualizan automáticamente en función de las interacciones con el panel de hosting. Un ejemplo es el indicador isDashboardEditing.
  • visualizationSDK: Proporciona funciones específicas de la visualización para permitir que la extensión interactúe con el host del panel de Looker. Un ejemplo es la función updateRowLimit.
  • visualizationData: Proporciona datos de visualización a la extensión. Los datos se actualizan automáticamente en función de las interacciones con el panel de hosting. Los datos son similares a los que se proporcionan a las visualizaciones personalizadas.

Cómo compilar extensiones reactivas

Los iframes en los que se ejecutan las extensiones cambian automáticamente a medida que cambia el tamaño de la ventana superior del host de Looker. Esto se refleja automáticamente en la ventana de contenido del iframe. El componente iframe no tiene padding ni margen, por lo que depende de la extensión proporcionar su propio padding y margen para que se vea coherente con la aplicación de Looker. En el caso de las extensiones independientes, depende de la extensión controlar la altura. En el caso de las extensiones que se ejecutan en tarjetas de panel o visualizaciones de Explorar, la ventana de contenido del iframe se establecerá automáticamente en la altura que el iframe pone a disposición.

Consideraciones de renderización

Es importante tener en cuenta que las extensiones de mosaicos se renderizarán cuando se descargue un panel como PDF o una imagen. El renderizador espera que la tarjeta le notifique cuando se complete la renderización. De lo contrario, el procesador dejará de responder. El siguiente es un ejemplo de cómo notificar al renderizador que se renderizó la tarjeta.

  const { extensionSDK } = useContext(ExtensionContext40)

  useEffect(() => {
    extensionSDK.rendered()
  }, [])

Las animaciones también deben inhabilitarse durante la renderización. El siguiente es un ejemplo en el que se desactivan las configuraciones de animación durante la renderización:

  const { lookerHostData} = useContext(ExtensionContext40)
  const isRendering = lookerHostData?.isRendering

  const config = isRendering
    ? {
        ...visConfig,
        valueCountUp: false,
        waveAnimateTime: 0,
        waveRiseTime: 0,
        waveAnimate: false,
        waveRise: false,
      }
    : visConfig

  if (mountPoint === MountPoint.dashboardVisualization) {
    return <VisualizationTile config={config} />
  }

Funciones y propiedades del SDK de tarjetas

El SDK de tarjetas proporciona funciones que permiten que una extensión de tarjeta interactúe con su panel de hosting.

Las funciones y propiedades disponibles se muestran en la siguiente tabla:

Función o propiedad Descripción
tileHostData (propiedad) Aloja datos específicos de la extensión de la tarjeta. Consulta la sección Datos del SDK de tarjetas para obtener más información.
addError Cuando se los llama, el panel o Explorar mostrará un mensaje de error debajo de la visualización.
clearError Cuando se los llama, el panel o Explorar ocultarán los mensajes de error que se muestren debajo de la visualización.
openDrillMenu En el caso de las extensiones de visualización, esta llamada abre un menú de desglose. Esta llamada se ignora si la extensión no es una visualización de extensión de tarjeta.
runDashboard Ejecuta el panel actual. Una extensión de visualización de tarjetas que se ejecuta en una exploración ignora esta llamada.
stopDashboard Detiene un panel en ejecución. Una extensión de visualización de tarjetas que se ejecuta en una exploración ignora esta llamada.
updateFilters Actualiza los filtros en el panel actual o en Explorar.
openScheduleDialog Abre el diálogo de programación. Esta llamada se ignora cuando se ejecuta en una exploración.
toggleCrossFilter Activa o desactiva los filtros cruzados. Esta llamada se ignora cuando se ejecuta en una exploración.

Datos del SDK de tarjetas

Las propiedades de datos del SDK de tarjetas disponibles se muestran en la siguiente tabla:

Propiedad Descripción
isExploring Cuando es verdadero, indica que la tarjeta se está configurando como una visualización dentro de una exploración.
dashboardId Es el ID del panel de la tarjeta que se renderiza. Si el mosaico se configura como Explorar, esta propiedad no se propagará.
elementId Es el ID del elemento de la tarjeta que se renderiza. Si la tarjeta se configura como una de exploración, no se propagará esta propiedad.
queryId Es el ID de consulta del mosaico que se renderiza si está asociado con una visualización. Si el mosaico se configura como Explorar, esta propiedad no se propagará.

El queryId es el ID de la consulta que se crea cuando la visualización está integrada en la exploración de Looker. No contiene ningún filtro ni filtrado cruzado que se pueda aplicar al panel. Para reflejar los datos que se muestran en QueryResponse, se deben aplicar filtros y filtros cruzados, y se debe generar una consulta nueva. Como resultado, es posible que haya propiedades más útiles que queryId. Consulta filteredQuery para ver un objeto de consulta con filtros aplicados.
querySlug El slug de consulta del mosaico que se renderiza si está asociado con una visualización. Si la tarjeta se configura como una de exploración, no se propagará esta propiedad.

querySlug es un fragmento de la consulta que se crea cuando la visualización está integrada en Explorar de Looker. No contiene ningún filtro ni filtrado cruzado que se aplique al panel. Para reflejar los datos que se muestran en el QueryResponse, se deben aplicar filtros y filtros cruzados, y se debe generar una consulta nueva. Como resultado, puede haber propiedades más útiles que querySlug. Consulta filteredQuery para ver un objeto de consulta con filtros aplicados.
dashboardFilters Los filtros que se aplican al panel. Si el mosaico se configura como Explorar, esta propiedad no se propagará.
dashboardRunState Indica si el panel está en ejecución. Si la tarjeta se configura como una exploración, el estado será UNKNOWN.

Por motivos de rendimiento del panel, es posible que el estado de ejecución nunca se muestre como en ejecución. Esto generalmente sucede si no hay otros mosaicos asociados con una consulta, incluido aquel con el que está asociada la extensión. Si la extensión necesita saber con certeza que se ejecutó un panel, la forma confiable es detectar diferencias en lastRunStartTime.
isDashboardEditing Cuando es verdadero, el panel se está editando. Si la tarjeta se configura como una de exploración, no se propagará esta propiedad.
isDashboardCrossFilteringEnabled Si es verdadero, se habilita el filtrado cruzado en el panel. Si el mosaico se configura como Explorar, esta propiedad no se propagará.
filteredQuery Un objeto de consulta que coincide con el ID de consulta asociado al elemento de panel subyacente que aplica los filtros de panel y los cambios de zona horaria que se realizan a nivel del panel.
lastRunSourceElementId El ID del elemento de extensión de mosaico que activó la última ejecución del panel. El ID no estará definido si la ejecución del panel se activó mediante el botón Ejecutar o la autorefresh del panel, o bien si la ejecución se activó con el SDK incorporado. Si el mosaico se configura como Explorar, esta propiedad no se propagará.

Ten en cuenta que el lastRunSourceElementId puede ser el mismo que el ID del elemento de la instancia de extensión actual. Por ejemplo, si la extensión activa una ejecución de panel, recibirá una notificación cuando comience y finalice la ejecución del panel.
lastRunStartTime Indica la hora de inicio de la última ejecución del panel. Si la tarjeta se configura como una de exploración, no se propagará esta propiedad.

Ten en cuenta que no se deben usar las horas de inicio y finalización informadas para capturar métricas de rendimiento.
lastRunEndTime Indica la hora de finalización de la última ejecución del panel. Si el mosaico se configura como Explorar, esta propiedad no se propagará. Si se está ejecutando el mosaico, esta propiedad no se propagará.

Ten en cuenta que no se deben usar las horas de inicio y finalización registradas para capturar métricas de rendimiento.
lastRunSuccess Indica si la última ejecución del panel se realizó correctamente o no. Si la tarjeta se configura como una de exploración, no se propagará esta propiedad. Si se está ejecutando el mosaico, esta propiedad no se propagará.

Funciones y propiedades del SDK de visualización

Las funciones y propiedades del SDK de visualización disponibles se muestran en la siguiente tabla:

Función o propiedad Descripción
visualizationData (propiedad) Visualización (combinación de datos de visConfig y queryResponse)
visConfig (propiedad) Datos de configuración de la visualización:

  • Mide los parámetros de configuración
  • Configuraciones de las dimensiones
  • Hacer cálculos de tablas
  • Configuraciones de reorientación
  • Configuraciones de visualización

Se usan para personalizar el estilo y la apariencia de una visualización en una exploración.
queryResponse (propiedad) Datos de respuesta de la consulta
configureVisualization Establece la configuración predeterminada para una visualización de extensión. La configuración se renderizará dentro del editor de visualización de Explorar. Solo se debe llamar una vez.
setVisConfig Actualiza la configuración de la visualización.
updateRowLimit Actualiza el límite de filas de la consulta.

Datos del SDK de Visualization

El SDK de visualización consta de lo siguiente:

  • Datos de configuración de la visualización
  • Cómo consultar datos de respuesta

Datos de configuración de la visualización

Propiedad Descripción
queryFieldMeasures Medir información
queryFieldDimensions Información de dimensiones
queryFieldTableCalculations Información sobre el cálculo basado en tablas
queryFieldPivots Información de Pivot
visConfig Datos de configuración visual. Se debe combinar con la configuración predeterminada y aplicarse a la visualización que renderiza la extensión. 
export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Cómo consultar datos de respuesta

Propiedad Descripción
data Array de datos de fila
fieldMeasures Información de la medición de campo
fieldDimensions Información sobre las dimensiones del campo.
fieldTableCalculations Información de los cálculos de la tabla de campos
fieldPivots Información del eje de campo
fieldMeasureLike Es un array concatenado de información de medición de campo y cálculos de tablas que se comportan como medidas.
fieldDimensionLike Es un array concatenado de información de las dimensiones de campos y cálculos en tablas que se comportan como dimensiones.