Cómo compilar extensiones de mosaicos

A partir de Looker 24.0, se pueden desarrollar extensiones para que se ejecuten en un mosaico de los paneles. Las extensiones que admiten ejecutarse como un mosaico o una visualización se pueden agregar mientras el panel está en modo de edición o guardar en un panel como una visualización desde 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 disponibles:

Cómo usar el SDK de la extensión 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 está habilitada, la extensión aparecerá en las opciones de visualización de una exploración, en la que se puede seleccionar como visualización y guardar como mosaico del panel. Cuando se ejecuta el panel, este ejecutará la consulta asociada al mosaico y pondrá los datos a disposición de la extensión. Esto es similar a cómo funcionan las visualizaciones personalizadas. La principal diferencia entre una visualización personalizada y una extensión que se ejecuta en un mosaico del panel que tiene habilitado dashboard_vis es que la extensión puede realizar llamadas a la API de Looker.
  • dashboard_tile: Cuando se habilita, la extensión aparece 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 es responsable de recuperar sus propios datos, en lugar de que la tarjeta de consulta proporcione automáticamente los datos a la extensión.

Un punto de activación adicional, standalone, hace que la extensión aparezca en la sección Aplicaciones del menú principal de Looker. Es posible que una extensión tenga definidos varios puntos de activación. En el tiempo de ejecución, se notifica a la extensión cómo está montada y puede ajustar su comportamiento en consecuencia. Por ejemplo, las extensiones de standalone pueden necesitar establecer su propia altura, mientras que las extensiones de tarjetas no.

APIs adicionales de la 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 la tarjeta 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 tarjetas a la extensión. Los datos se actualizan automáticamente en función de las interacciones con el panel de alojamiento. Un ejemplo es el indicador isDashboardEditing.
  • visualizationSDK: Proporciona funciones específicas de 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 alojamiento. Los datos son similares a los que se proporcionan a las visualizaciones personalizadas.

Cómo crear extensiones reactivas

Los iframes en los que se ejecutan las extensiones cambian de tamaño automáticamente a medida que cambia el tamaño de la ventana principal 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 la extensión debe proporcionar su propio padding y margen para que se vea coherente con la aplicación de Looker. En el caso de las extensiones independientes, la extensión es la que controla su altura. En el caso de las extensiones que se ejecutan en tarjetas del panel o en visualizaciones de Explorar, la ventana de contenido del iframe se establecerá automáticamente en la altura que proporcione el iframe.

Consideraciones de renderización

Es importante tener en cuenta que las extensiones de tarjetas se renderizarán cuando se descargue un panel como PDF o imagen. El renderizador espera que la segmentación le notifique cuando se complete la renderización. Si no se hace, el renderizador dejará de responder. A continuación, se muestra un ejemplo de cómo notificar al renderizador que se renderizó la segmentación.

  const { extensionSDK } = useContext(ExtensionContext40)

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

Las animaciones también deben inhabilitarse durante la renderización. A continuación, se muestra un ejemplo en el que se desactivan los parámetros de configuración de la 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 Tiles

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) Son datos del host específicos de la extensión de tarjeta. Consulta la sección Datos del SDK de tarjetas para obtener más detalles.
addError Cuando se llame, el panel o la Exploración mostrarán un mensaje de error debajo de la visualización.
clearError Cuando se llama, el panel o la Exploración ocultarán cualquier mensaje de error que se muestre 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 de carreras. 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 o la exploración actuales.
openScheduleDialog Abre el diálogo de programación. Esta llamada se ignora cuando se ejecuta en Explorar.
toggleCrossFilter Activa o desactiva los filtros cruzados. Esta llamada se ignora cuando se ejecuta en Explorar.

Datos del SDK de Tiles

En la siguiente tabla, se muestran las propiedades de datos disponibles del SDK de Tiles:

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 la tarjeta se configura como Explorar, esta propiedad no se completará.
elementId Es el ID del elemento de la tarjeta que se renderiza. Si la tarjeta se configura como Explorar, esta propiedad no se completará.
queryId Es el ID de la consulta del mosaico que se renderiza si está asociado a 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 se compila en el Explorar de Looker. No contiene ningún filtro ni filtro cruzado que se pueda aplicar al panel. Para reflejar los datos que se muestran en el QueryResponse, se deberán aplicar filtros y filtros cruzados, y se deberá generar una nueva consulta. Como resultado, es posible que haya propiedades más útiles que queryId. Consulta filteredQuery para ver un objeto de consulta con filtros aplicados.
querySlug Es el slug de la consulta del mosaico que se renderiza si está asociado a una visualización. Si la tarjeta se configura como Explorar, esta propiedad no se completará.

querySlug es un slug de la consulta que se crea cuando la visualización se compila en el Explorador de Looker. No contiene ningún filtro ni filtro cruzado que se aplique al panel. Para reflejar los datos que se muestran en QueryResponse, se deberán aplicar filtros y filtros cruzados, y se deberá generar una nueva consulta. Como resultado, es posible que haya propiedades más útiles que querySlug. Consulta filteredQuery para ver un objeto de consulta con filtros aplicados.
dashboardFilters Son los filtros que se aplican al panel. Si la tarjeta se configura como Explorar, esta propiedad no se completará.
dashboardRunState Indica si el panel está en ejecución. Si la tarjeta se configura como Explorar, 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. Por lo general, esto sucede si no hay otras tarjetas asociadas con una búsqueda, incluida la que está asociada con la extensión. Si la extensión necesita saber con certeza que se ejecutó un panel, detectar diferencias en lastRunStartTime es la forma confiable de hacerlo.
isDashboardEditing Cuando es verdadero, se está editando el panel. Si la tarjeta se configura como Explorar, esta propiedad no se completará.
isDashboardCrossFilteringEnabled Cuando es verdadero, se habilita el filtrado cruzado en el panel. Si la tarjeta se configura como Explorar, esta propiedad no se completará.
filteredQuery Es un objeto de consulta que coincide con el ID de la consulta asociada al elemento del panel subyacente que aplica los filtros del panel y los cambios de zona horaria que se realizan a nivel del panel.
lastRunSourceElementId Es el ID del elemento de extensión de tarjeta que activó la última ejecución del panel. El ID no estará definido si el panel se ejecutó con el botón Ejecutar o la actualización automática del panel, o si la ejecución se activó con el SDK de incorporación. Si la tarjeta se configura como Explorar, esta propiedad no se completará.

Ten en cuenta que 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 del 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 Explorar, esta propiedad no se completará.

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

Ten en cuenta que las horas de inicio y finalización que se registran no se deben usar 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 Explorar, esta propiedad no se completará. Si la tarjeta se está ejecutando, esta propiedad no se completará.

Funciones y propiedades del SDK de Visualization

En la siguiente tabla, se muestran las funciones y propiedades disponibles del SDK de visualización:

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:

  • Configuraciones de medición
  • Configuraciones de dimensiones
  • Cálculos basados en tablas
  • Configuraciones de la tabla dinámica
  • Configuraciones de visualización

Se usan para personalizar el aspecto de una visualización en Explorar.
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
  • Datos de respuesta de la consulta

Datos de configuración de la visualización

Propiedad Descripción
queryFieldMeasures Información de la medición
queryFieldDimensions Información de la dimensión
queryFieldTableCalculations Información del cálculo basado en tablas
queryFieldPivots Información de la reorientación
visConfig Son los 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
}

Datos de respuesta de la consulta

Propiedad Descripción
data Es un array de datos de filas.
fieldMeasures Es información de la medida del campo.
fieldDimensions Es la información de la dimensión del campo.
fieldTableCalculations Es información sobre los cálculos basados en tablas de campos.
fieldPivots Es la información de la tabla dinámica del campo.
fieldMeasureLike Es un array concatenado de información de medidas de campo y cálculos basados en tablas que se comportan como medidas.
fieldDimensionLike Es un array concatenado de información de dimensiones de campo y cálculos basados en tablas que se comportan como dimensiones.

Usa el SDK de Embed

No se recomienda usar el SDK de Embed en una extensión de tarjeta por los siguientes motivos:

  • Es posible que la extensión termine renderizando un panel en el que se muestre como una tarjeta. El framework de extensiones no tiene forma de detectar esto y, como resultado, es posible que el navegador falle.
  • No funciona la renderización de PDF del contenido incorporado dentro de una extensión de tarjeta.