Creare estensioni dei riquadri degli edifici

A partire da Looker 24.0, le estensioni possono essere sviluppate per essere eseguite in un riquadro delle dashboard. Le estensioni che supportano l'esecuzione come riquadro o visualizzazione possono essere aggiunte mentre la dashboard è in modalità di modifica o salvate in una dashboard come visualizzazione da un'esplorazione. Le estensioni possono anche essere configurate come riquadri nelle dashboard LookML.

Sono disponibili esempi di estensioni che possono essere utilizzate come riquadri della dashboard:

Utilizzare l'SDK per le estensioni di Looker con le estensioni dei riquadri

Perché le estensioni vengano caricate come riquadri in una dashboard, è necessario definire il parametro mount_points nel file manifest del progetto LookML. Esistono due tipi di mount_points correlate alle estensioni dei riquadri:

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }
  • dashboard_vis: se abilitata, l'estensione viene visualizzata nelle opzioni di visualizzazione di un'esplorazione, dove può essere selezionata come visualizzazione e salvata come riquadro della dashboard. Quando viene eseguita la dashboard, viene eseguita la query associata al riquadro e i dati vengono resi disponibili all'estensione. Questo è simile al funzionamento delle visualizzazioni personalizzate. La differenza principale tra una visualizzazione personalizzata e un'estensione in esecuzione in un riquadro della dashboard con dashboard_vis abilitato è che l'estensione può effettuare chiamate all'API Looker.
  • dashboard_tile: se attivata, l'estensione verrà visualizzata nel riquadro Estensioni visualizzato quando un utente modifica un dashboard e seleziona l'opzione Estensioni dopo aver fatto clic sul pulsante Aggiungi. Questo tipo di estensione è responsabile del recupero dei propri dati, anziché della query del riquadro che fornisce automaticamente i dati all'estensione.

Un punto di montaggio aggiuntivo, standalone, fa sì che l'estensione venga visualizzata nella sezione Applicazioni del menu principale di Looker. È possibile che un'estensione abbia più punti di montaggio definiti. In fase di runtime, l'estensione viene informata di come è montata e può modificare il suo comportamento di conseguenza. Ad esempio, le estensioni standalone potrebbero dover impostare la propria altezza, mentre le estensioni a riquadri no.

API aggiuntive per l'estensione delle tessere

Le estensioni riquadro vengono fornite con API e dati aggiuntivi in fase di runtime. Questi vengono ottenuti dal contesto dell'estensione:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)
  • tileSDK: fornisce funzioni specifiche per i riquadri per consentire all'estensione di interagire con l'host della dashboard Looker. Ad esempio, per consentire all'estensione di visualizzare e cancellare i messaggi di errore.
  • tileHostData: fornisce i dati delle schede all'estensione. I dati vengono aggiornati automaticamente in base alle interazioni con la dashboard di hosting. Un esempio è l'indicatore isDashboardEditing.
  • visualizationSDK: fornisce funzioni specifiche per la visualizzazione per consentire all'estensione di interagire con l'host della dashboard Looker. Un esempio è la funzione updateRowLimit.
  • visualizationData: fornisce i dati di visualizzazione all'estensione. I dati vengono aggiornati automaticamente in base alle interazioni con la dashboard di hosting. I dati sono simili a quelli forniti alle visualizzazioni personalizzate.

Creazione di estensioni reattive

Gli iframe in cui vengono eseguite le estensioni vengono ridimensionati automaticamente man mano che viene ridimensionata la finestra host di Looker principale. Questo valore viene automaticamente visualizzato nella finestra dei contenuti dell'iframe. Il componente iframe non ha spaziatura interna o margine, quindi spetta all'estensione fornire la propria spaziatura interna e il proprio margine in modo che l'aspetto sia coerente con l'applicazione Looker. Per le estensioni autonome, spetta all'estensione controllare la sua altezza. Per le estensioni eseguite nei riquadri della dashboard o nelle visualizzazioni di Esplora, la finestra dei contenuti iframe verrà impostata automaticamente sull'altezza resa disponibile dall'iframe.

Considerazioni sul rendering

È importante notare che le estensioni dei riquadri vengono visualizzate quando un prospetto viene scaricato come PDF o immagine. Il renderer prevede che il riquadro lo avvisi al termine del rendering. Se non lo fai, il renderer smetterà di rispondere. Di seguito è riportato un esempio di come notificare al renderer che il riquadro è stato eseguito.

  const { extensionSDK } = useContext(ExtensionContext40)

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

Le animazioni devono essere disattivate anche durante il rendering. Di seguito è riportato un esempio in cui le configurazioni dell'animazione vengono disattivate durante il rendering:

  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} />
  }

Funzioni e proprietà dell'SDK Tile

L'SDK per i riquadri fornisce funzioni che consentono a un'estensione di interagire con la dashboard di hosting.

Le funzioni e le proprietà disponibili sono riportate nella tabella seguente:

Funzione o proprietà Descrizione
tileHostData (proprietà) Dati host specifici per l'estensione del riquadro. Per maggiori dettagli, consulta la sezione Dati dell'SDK per le tessere.
addError Quando viene chiamato, il dashboard o l'esplorazione mostrerà un messaggio di errore sotto la visualizzazione.
clearError Quando viene chiamato, il messaggio di errore visualizzato sotto la visualizzazione viene nascosto nella dashboard o nell'esplorazione.
openDrillMenu Per le estensioni di visualizzazione, questa chiamata apre un menu di analisi in dettaglio. Questa chiamata viene ignorata se l'estensione non è una visualizzazione di estensione a riquadro.
runDashboard Esegue la dashboard corrente. Questa chiamata viene ignorata da un'estensione di visualizzazione dei riquadri in esecuzione in un'esplorazione.
stopDashboard Arresta una dashboard in esecuzione. Questa chiamata viene ignorata da un'estensione di visualizzazione dei riquadri in esecuzione in un'esplorazione.
updateFilters Aggiorna i filtri nella dashboard corrente o in Esplora.
openScheduleDialog Apre la finestra di dialogo per la pianificazione. Questa chiamata viene ignorata quando viene eseguita in un'esplorazione.
toggleCrossFilter Attiva/disattiva i filtri incrociati. Questa chiamata viene ignorata quando viene eseguita in un'esplorazione.

Dati dell'SDK per le tessere

Le proprietà dei dati dell'SDK per i riquadri disponibili sono mostrate nella tabella seguente:

Proprietà Descrizione
isExploring Se true, indica che il riquadro viene configurato come visualizzazione all'interno di un'esplorazione.
dashboardId L'ID del dashboard del riquadro di cui viene eseguito il rendering. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.
elementId L'ID elemento del riquadro di cui viene eseguito il rendering. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.
queryId L'ID query del riquadro di cui viene eseguito il rendering, se è associato a una visualizzazione. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.

queryId è l'ID della query creata quando la visualizzazione viene incorporata in Esplora di Looker. Non contiene filtri o filtri incrociati da applicare alla dashboard. Per riflettere i dati mostrati in QueryResponse, è necessario applicare filtri e filtri incrociati e generare una nuova query. Di conseguenza, potrebbero esserci più proprietà utili di queryId. Consulta filteredQuery per un oggetto query con i filtri applicati.
querySlug La query slug del riquadro di cui viene eseguito il rendering, se è associata a una visualizzazione. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.

querySlug è uno slug della query creato quando la visualizzazione viene creata in Esplora di Looker. Non contiene filtri o filtri incrociati applicati alla dashboard. Per riflettere i dati mostrati in QueryResponse, è necessario applicare filtri e filtri incrociati e generare una nuova query. Di conseguenza, potrebbero esserci più proprietà utili di querySlug. Consulta filteredQuery per un oggetto query con i filtri applicati.
dashboardFilters I filtri applicati alla dashboard. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.
dashboardRunState Indica se la dashboard è in esecuzione. Se il riquadro viene configurato come Esplora, lo stato sarà UNKNOWN.

Per motivi di prestazioni della dashboard, lo stato di esecuzione potrebbe non essere mai visualizzato come in esecuzione. Ciò accade in genere se non sono presenti altri riquadri associati a una query, incluso quello a cui è associata l'estensione. Se l'estensione deve sapere con certezza che una dashboard è stata eseguita, il rilevamento delle differenze in lastRunStartTime è il modo più affidabile.
isDashboardEditing Se true, la dashboard è in fase di modifica. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.
isDashboardCrossFilteringEnabled Se è true, i filtri incrociati sono attivati nella dashboard. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.
filteredQuery Un oggetto query che corrisponde all'ID query associato all'elemento della dashboard sottostante che applica eventuali filtri della dashboard e modifiche del fuso orario apportate a livello di dashboard.
lastRunSourceElementId L'ID dell'elemento dell'estensione del riquadro che ha attivato l'ultima esecuzione della dashboard. L'ID non sarà definito se l'esecuzione della dashboard è stata attivata dal pulsante Esegui o dall'aggiornamento automatico della dashboard oppure se l'esecuzione è stata attivata utilizzando l'SDK per l'incorporamento. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.

Tieni presente che lastRunSourceElementId può essere uguale all'ID elemento dell'istanza dell'estensione corrente. Ad esempio, se l'estensione attiva l'esecuzione di una dashboard, riceverà una notifica all'inizio e al termine dell'esecuzione.
lastRunStartTime Indica l'ora di inizio dell'ultima esecuzione della dashboard. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata.

Tieni presente che gli orari di inizio e di fine riportati non devono essere utilizzati per acquisire le metriche sul rendimento.
lastRunEndTime Indica l'ora di fine dell'ultima esecuzione della dashboard. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata. Se il riquadro è in esecuzione, questa proprietà non verrà compilata.

Tieni presente che gli orari di inizio e di fine riportati non devono essere utilizzati per acquisire le metriche sul rendimento.
lastRunSuccess Indica se l'ultima esecuzione della dashboard è andata a buon fine o meno. Se il riquadro viene configurato come Esplora, questa proprietà non verrà compilata. Se il riquadro è in esecuzione, questa proprietà non verrà compilata.

Funzioni e proprietà dell'SDK di visualizzazione

Le funzioni e le proprietà dell'SDK di visualizzazione disponibili sono riportate nella tabella seguente:

Funzione o proprietà Descrizione
visualizationData (proprietà) Visualizzazione (combinazione di dati visConfig e queryResponse).
visConfig (proprietà) Dati di configurazione della visualizzazione:

  • Configurazioni di misurazione
  • Configurazioni delle dimensioni
  • Calcoli tabulari
  • Configurazioni pivot
  • Configurazioni di visualizzazione

Vengono utilizzati per personalizzare l'aspetto di una visualizzazione in un'esplorazione.
queryResponse (proprietà) Dati di risposta della query
configureVisualization Imposta la configurazione predefinita per una visualizzazione dell'estensione. La configurazione verrà visualizzata all'interno dell'editor di visualizzazione Esplora. Questo metodo deve essere chiamato una sola volta.
setVisConfig Aggiorna la configurazione della visualizzazione.
updateRowLimit Aggiorna il limite di righe della query.

Dati dell'SDK di visualizzazione

L'SDK di visualizzazione è costituito da quanto segue:

  • Dati di configurazione della visualizzazione
  • Query sui dati delle risposte

Dati di configurazione della visualizzazione

Proprietà Descrizione
queryFieldMeasures Informazioni sulla misura
queryFieldDimensions Informazioni sulle dimensioni
queryFieldTableCalculations Informazioni sul calcolo tabulare
queryFieldPivots Informazioni pivot
visConfig Dati di configurazione visiva. Deve essere unito alla configurazione predefinita e applicato alla visualizzazione sottoposta a rendering dall'estensione.
export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Query sui dati delle risposte

Proprietà Descrizione
data Array di dati delle righe
fieldMeasures Informazioni sulla misura del campo.
fieldDimensions Informazioni sulla dimensione del campo.
fieldTableCalculations Informazioni sui calcoli tabulari dei campi.
fieldPivots Informazioni sul pivot del campo.
fieldMeasureLike Un array concatenato di informazioni sulle misure dei campi e calcoli tabulari che si comportano come misure.
fieldDimensionLike Un array concatenato di informazioni sulle dimensioni dei campi e calcoli tabulari che si comportano come dimensioni.

Utilizzo dell'SDK Embed

L'utilizzo dell'SDK per l'incorporamento in un'estensione riquadro non è consigliato per i seguenti motivi:

  • È possibile che l'estensione finisca per eseguire il rendering di una dashboard in cui è un riquadro. Il framework delle estensioni non ha modo di rilevarlo e, di conseguenza, il browser potrebbe arrestarsi in modo anomalo.
  • Il rendering PDF dei contenuti incorporati all'interno di un'estensione riquadro non funziona.