Questa pagina è stata tradotta dall'API Cloud Translation.

Creare estensioni dei riquadri degli edifici

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

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

L'estensione di visualizzazione delle riquadri mostra come creare una visualizzazione personalizzata utilizzando il framework di estensioni.
L'estensione SDK riquadro mostra i metodi API disponibili specifici per le estensioni riquadro.

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

Le estensioni dei riquadri richiedono che il parametro mount_points sia definito nel file manifest del progetto LookML affinché le estensioni vengano caricate come riquadri in una dashboard. Esistono due tipi di mount_points relativi alle estensioni dei riquadri:

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }

dashboard_vis: se è attiva, 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 esegue la query associata al riquadro e rende i dati disponibili per l'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 in cui è attivata l'opzione dashboard_vis è che l'estensione può effettuare chiamate all'API Looker.
dashboard_tile: se l'estensione è attiva, viene visualizzata nel riquadro Estensioni che viene visualizzato quando un utente modifica una dashboard e seleziona l'opzione Estensioni dopo aver fatto clic sul pulsante Aggiungi. Questo tipo di estensione è responsabile del recupero dei propri dati, anziché lasciare che la query del riquadro fornisca 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 esecuzione, l'estensione viene informata della modalità di montaggio e può modificare il proprio comportamento di conseguenza. Ad esempio, le estensioni standalone potrebbero dover impostare la propria altezza, mentre le estensioni riquadro no.

API aggiuntive per l'estensione dei riquadri

Le estensioni riquadro vengono fornite con API e dati aggiuntivi in fase di esecuzione. 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 di 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 di 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 in base alle dimensioni della finestra dell'host Looker principale. Questo viene applicato automaticamente nella finestra dei contenuti dell'iframe. Il componente iframe non ha spaziatura interna o margini, quindi è compito dell'estensione fornire la propria spaziatura interna e i propri margini in modo che sia coerente con l'applicazione Looker. Per le estensioni autonome, è compito dell'estensione controllare l'altezza. Per le estensioni che vengono eseguite nei riquadri della dashboard o nelle visualizzazioni di Esplora, la finestra dei contenuti dell'iframe verrà impostata automaticamente sull'altezza resa disponibile dall'iframe.

Considerazioni sul rendering

È importante notare che le estensioni dei riquadri verranno visualizzate quando una dashboard viene scaricata come PDF o immagine. Il visualizzatore si aspetta che la scheda lo avvisi al termine del rendering. In caso contrario, il renderer smetterà di rispondere. Di seguito è riportato un esempio di come notificare al renderer che il riquadro è stato visualizzato.

  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 di 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 dei riquadri fornisce funzioni che consentono a un'estensione dei riquadri 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 Tile.
`addError`	Quando viene chiamata, la dashboard o l'esplorazione mostra un messaggio di errore sotto la visualizzazione.
`clearError`	Quando viene chiamata, la dashboard o l'esplorazione nasconde qualsiasi messaggio di errore visualizzato sotto la visualizzazione.
`openDrillMenu`	Per le estensioni di visualizzazione, questa chiamata apre un menu di visualizzazione dettagliata. Questa chiamata viene ignorata se l'estensione non è una visualizzazione dell'estensione 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 o nell'esplorazione corrente.
`openScheduleDialog`	Viene visualizzata la finestra di dialogo della 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 Tile

Le proprietà dei dati dell'SDK dei riquadri disponibili sono riportate nella tabella seguente:

Proprietà	Descrizione
`isExploring`	Se true, indica che il riquadro viene configurato come visualizzazione all'interno di un'esplorazione.
`dashboardId`	L'ID della dashboard del riquadro in fase di rendering. Se il riquadro viene configurato come esplorazione, questa proprietà non verrà compilata.
`elementId`	L'ID elemento della scheda in fase di rendering. Se il riquadro viene configurato come esplorazione, questa proprietà non verrà compilata.
`queryId`	L'ID query del riquadro in fase di rendering, se è associato a una visualizzazione. Se il riquadro viene configurato come esplorazione, questa proprietà non verrà compilata. `queryId` è l'ID della query creata quando la visualizzazione è integrata nell'esplorazione 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 proprietà più utili di `queryId`. Consulta `filteredQuery` per un oggetto query con i filtri applicati.
`querySlug`	Lo slug della query del riquadro che viene visualizzato se è associato a una visualizzazione. Se il riquadro viene configurato come esplorazione, questa proprietà non verrà compilata. `querySlug` è uno slug della query creato quando la visualizzazione è integrata nell'esplorazione 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 proprietà più 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 esplorazione, questa proprietà non verrà compilata.
`dashboardRunState`	Indica se la dashboard è in esecuzione. Se il riquadro viene configurato come esplorazione, lo stato sarà `UNKNOWN`. Per motivi di prestazioni della dashboard, lo stato di esecuzione potrebbe non essere mai visualizzato come in esecuzione. Questo accade in genere se non sono presenti altri riquadri associati a una query, inclusa quella a cui è associata l'estensione. Se l'estensione deve sapere con certezza che è stata eseguita una dashboard, 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 esplorazione, questa proprietà non verrà compilata.
`isDashboardCrossFilteringEnabled`	Se è true, i filtri incrociati sono attivati nella dashboard. Se il riquadro viene configurato come esplorazione, 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 ai fusi orari apportate a livello di dashboard.
`lastRunSourceElementId`	L'ID dell'elemento dell'estensione 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 di incorporamento. Se il riquadro viene configurato come esplorazione, 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 alla fine dell'esecuzione.
`lastRunStartTime`	Indica l'ora di inizio dell'ultima esecuzione della dashboard. Se il riquadro viene configurato come esplorazione, questa proprietà non verrà compilata. Tieni presente che le ore di inizio e di fine registrate non devono essere utilizzate per acquisire le metriche sul rendimento.
`lastRunEndTime`	Indica l'ora di fine dell'ultima esecuzione della dashboard. Se il riquadro viene configurato come esplorazione, questa proprietà non verrà compilata. Se il riquadro è in esecuzione, questa proprietà non verrà compilata. Tieni presente che le ore di inizio e di fine registrate non devono essere utilizzate 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 esplorazione, 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 dei 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
Dati della risposta alla query

Dati di configurazione della visualizzazione

Proprietà	Descrizione
`queryFieldMeasures`	Informazioni sulle misurazioni
`queryFieldDimensions`	Informazioni sulle dimensioni
`queryFieldTableCalculations`	Informazioni sul calcolo tabulare
`queryFieldPivots`	Informazioni sul pivot
`visConfig`	Dati di configurazione visiva. Questo deve essere unito alla configurazione predefinita e applicato alla visualizzazione visualizzata dall'estensione.

export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Dati della risposta alla query

Proprietà	Descrizione
`data`	Array di dati di riga
`fieldMeasures`	Informazioni sulla misurazione del campo.
`fieldDimensions`	Informazioni sulle dimensioni dei campi.
`fieldTableCalculations`	Informazioni sui calcoli della tabella dei campi.
`fieldPivots`	Informazioni sul pivot dei campi.
`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 Embed in un'estensione dei riquadri non è consigliato per i seguenti motivi:

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