Gebäudekachel-Erweiterungen

Ab Looker 24.0 können Erweiterungen so entwickelt werden, dass sie in einer Kachel in Dashboards ausgeführt werden. Erweiterungen, die als Kachel oder Visualisierung ausgeführt werden können, können im Bearbeitungsmodus des Dashboards hinzugefügt oder aus einem Explore als Visualisierung in einem Dashboard gespeichert werden. Erweiterungen können auch als Kacheln in LookML-Dashboards konfiguriert werden.

Beispiele für Erweiterungen, die als Dashboard-Kacheln verwendet werden können:

• In der Erweiterung für die Ansicht mit Kacheln wird gezeigt, wie Sie mit dem Erweiterungs-Framework eine benutzerdefinierte Visualisierung erstellen.
• In der Erweiterung „Kacheln SDK“ werden die verfügbaren API-Methoden angezeigt, die speziell für Erweiterungen für Kacheln gelten.

Looker Extension SDK mit Kachelnerweiterungen verwenden

Für Kachelnerweiterungen muss der Parameter mount_points in der LookML-Manifestdatei des Projekts definiert sein, damit die Erweiterungen als Kacheln in ein Dashboard geladen werden können. Es gibt zwei Arten von mount_points im Zusammenhang mit Kachelnerweiterungen:

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

• dashboard_vis – Wenn diese Option aktiviert ist, wird die Erweiterung in den Visualisierungsoptionen eines Explore angezeigt. Dort kann sie als Visualisierung ausgewählt und als Dashboard-Kachel gespeichert werden. Wenn das Dashboard ausgeführt wird, wird die mit der Kachel verknüpfte Abfrage ausgeführt und die Daten werden der Erweiterung zur Verfügung gestellt. Das funktioniert ähnlich wie bei benutzerdefinierten Visualisierungen. Der Hauptunterschied zwischen einer benutzerdefinierten Visualisierung und einer Erweiterung, die in einer Dashboard-Kachel ausgeführt wird, für die dashboard_vis aktiviert ist, besteht darin, dass die Erweiterung Looker API-Aufrufe ausführen kann.
• dashboard_tile – Wenn diese Option aktiviert ist, wird die Erweiterung im Bereich Erweiterungen angezeigt, der eingeblendet wird, wenn ein Nutzer ein Dashboard bearbeitet und die Option Erweiterungen auswählt, nachdem er auf die Schaltfläche Hinzufügen geklickt hat. Diese Art von Erweiterung ist für das Abrufen eigener Daten verantwortlich, anstatt dass die Erweiterung automatisch über die Kachelnanfrage mit Daten versorgt wird.

Durch einen zusätzlichen Bereitstellungspunkt, standalone, wird die Erweiterung im Looker-Hauptmenü im Bereich Anwendungen angezeigt. Für eine Erweiterung können mehrere Bereitstellungspunkte definiert werden. Während der Laufzeit wird der Erweiterung mitgeteilt, wie sie bereitgestellt wird, und sie kann ihr Verhalten entsprechend anpassen. Beispielsweise müssen für standalone-Erweiterungen möglicherweise eigene Höhen festgelegt werden, während dies bei Kachelnerweiterungen nicht der Fall ist.

Zusätzliche APIs für die Erweiterung von Kacheln

Für Erweiterungen von Kacheln werden während der Laufzeit zusätzliche APIs und Daten bereitgestellt. Diese werden aus dem Erweiterungskontext abgerufen:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)

• tileSDK: Bietet kachelspezifische Funktionen, mit denen die Erweiterung mit dem Looker-Dashboard-Host interagieren kann. Beispielsweise können Sie festlegen, dass die Erweiterung Fehlermeldungen anzeigen und löschen darf.
• tileHostData – Stellt der Erweiterung Ansichtsdaten bereit. Die Daten werden automatisch anhand von Interaktionen mit dem Hosting-Dashboard aktualisiert. Ein Beispiel ist der Indikator isDashboardEditing.
• visualizationSDK: Bietet visualisierungsspezifische Funktionen, mit denen die Erweiterung mit dem Looker-Dashboard-Host interagieren kann. Ein Beispiel ist die updateRowLimit-Funktion.
• visualizationData – Stellt der Erweiterung Visualisierungsdaten bereit. Die Daten werden automatisch anhand von Interaktionen mit dem Hosting-Dashboard aktualisiert. Die Daten ähneln denen, die für benutzerdefinierte Visualisierungen bereitgestellt werden.

Reaktive Erweiterungen erstellen

Die Größe der Iframes, in denen Erweiterungen ausgeführt werden, wird automatisch angepasst, wenn sich das übergeordnete Looker-Hostfenster ändert. Das wird automatisch im Iframe-Inhaltsfenster berücksichtigt. Die Iframe-Komponente hat keinen Abstand oder Rand. Daher muss die Erweiterung eigene Abstände und Ränder festlegen, damit sie mit der Looker-Anwendung übereinstimmt. Bei eigenständigen Erweiterungen wird die Höhe von der Erweiterung selbst gesteuert. Bei Erweiterungen, die in Dashboard-Kacheln oder Explore-Visualisierungen ausgeführt werden, wird das Fenster für den IFrame automatisch auf die vom IFrame bereitgestellte Höhe festgelegt.

Überlegungen zum Rendering

Hinweis: Kachelnerweiterungen werden gerendert, wenn ein Dashboard als PDF oder Bild heruntergeladen wird. Der Renderer erwartet, dass die Kachel ihn benachrichtigt, wenn das Rendern abgeschlossen ist. Andernfalls reagiert der Renderer nicht mehr. Im Folgenden finden Sie ein Beispiel dafür, wie der Renderer darüber informiert wird, dass die Kachel gerendert wurde.

  const { extensionSDK } = useContext(ExtensionContext40)

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

Animationen sollten beim Rendern ebenfalls deaktiviert werden. Im folgenden Beispiel werden beim Rendern die Animationskonfigurationen deaktiviert:

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

Funktionen und Eigenschaften des Tile SDK

Das Kachel-SDK bietet Funktionen, mit denen eine Kachelerweiterung mit dem Hosting-Dashboard interagieren kann.

Die verfügbaren Funktionen und Eigenschaften sind in der folgenden Tabelle aufgeführt:

Funktion oder Property	Beschreibung
tileHostData (property)	Daten, die speziell für die Kachelerweiterung gehostet werden. Weitere Informationen finden Sie im Abschnitt Tile SDK-Daten.
addError	Wenn Sie die Funktion aufrufen, wird im Dashboard oder Explore unter der Visualisierung eine Fehlermeldung angezeigt.
clearError	Wenn das Dashboard oder Explore aufgerufen wird, werden alle Fehlermeldungen unter der Visualisierung ausgeblendet.
openDrillMenu	Bei Visualisierungserweiterungen wird durch diesen Aufruf ein Drilldown-Menü geöffnet. Dieser Aufruf wird ignoriert, wenn es sich bei der Erweiterung nicht um eine Visualisierung einer Kachelnerweiterung handelt.
runDashboard	Führt das aktuelle Dashboard aus. Dieser Aufruf wird von einer Erweiterung für die Ansicht mit Kacheln ignoriert, die in einem Explore ausgeführt wird.
stopDashboard	Beendet ein laufendes Dashboard. Dieser Aufruf wird von einer Erweiterung für die Ansicht mit Kacheln ignoriert, die in einem Explore ausgeführt wird.
updateFilters	Aktualisiert die Filter im aktuellen Dashboard oder Explore.
openScheduleDialog	Das Dialogfeld „Zeitplan“ wird geöffnet. Dieser Aufruf wird ignoriert, wenn er in einem Explore ausgeführt wird.
toggleCrossFilter	Aktiviert oder deaktiviert Kreuzfilter. Dieser Aufruf wird ignoriert, wenn er in einem Explore ausgeführt wird.

Tile SDK-Daten

Die verfügbaren Dateneigenschaften des Tile SDK sind in der folgenden Tabelle aufgeführt:

Attribut	Beschreibung
isExploring	Wenn „true“ festgelegt ist, wird die Kachel als Visualisierung in einem Explore konfiguriert.
dashboardId	Die Dashboard-ID der Kachel, die gerendert wird. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
elementId	Die Element-ID der gerenderten Kachel. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
queryId	Die Abfrage-ID der gerenderten Kachel, falls sie mit einer Visualisierung verknüpft ist. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. queryId ist die ID der Abfrage, die erstellt wird, wenn die Visualisierung in das Looker-Explore eingebunden wird. Es enthält keine Filter oder Kreuzfilterung, die auf das Dashboard angewendet werden können. Damit die in der QueryResponse angezeigten Daten berücksichtigt werden, müssen Filter und Kreuzfilter angewendet und eine neue Abfrage generiert werden. Daher gibt es möglicherweise mehr nützliche Properties als queryId. In filteredQuery finden Sie ein Abfrageobjekt mit angewendeten Filtern.
querySlug	Der Slug der Abfrage der gerenderten Kachel, wenn sie mit einer Visualisierung verknüpft ist. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. querySlug ist ein Slug der Abfrage, der erstellt wird, wenn die Visualisierung in den Looker-Explore eingebettet wird. Es enthält keine Filter oder Kreuzfilterung, die auf das Dashboard angewendet werden. Damit die in der QueryResponse angezeigten Daten berücksichtigt werden, müssen Filter und Kreuzfilter angewendet und eine neue Abfrage generiert werden. Daher gibt es möglicherweise mehr nützliche Properties als querySlug. In filteredQuery finden Sie ein Abfrageobjekt mit angewendeten Filtern.
dashboardFilters	Die Filter, die auf das Dashboard angewendet werden. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
dashboardRunState	Gibt an, ob das Dashboard ausgeführt wird. Wenn die Kachel als Explore konfiguriert wird, lautet der Status UNKNOWN. Aus Gründen der Dashboard-Leistung wird der Laufstatus möglicherweise nie als „Aktiv“ angezeigt. Das ist in der Regel der Fall, wenn mit einer Abfrage keine anderen Kacheln verknüpft sind, einschließlich derjenigen, mit der die Erweiterung verknüpft ist. Wenn die Erweiterung sicher wissen muss, dass ein Dashboard ausgeführt wurde, ist das Erkennen von Unterschieden in lastRunStartTime die zuverlässigste Methode.
isDashboardEditing	Wenn dieser Wert auf „wahr“ gesetzt ist, wird das Dashboard bearbeitet. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
isDashboardCrossFilteringEnabled	Wenn „wahr“ festgelegt ist, ist die Kreuzfilterung im Dashboard aktiviert. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
filteredQuery	Ein Abfrageobjekt, das mit der Abfrage-ID übereinstimmt, die dem zugrunde liegenden Dashboard-Element zugeordnet ist. Auf dieses Objekt werden alle Dashboardfilter und Zeitzonenänderungen angewendet, die auf Dashboardebene vorgenommen werden.
lastRunSourceElementId	Die ID des Elements der Kachelnerweiterung, das die letzte Ausführung des Dashboards ausgelöst hat. Die ID ist nicht definiert, wenn die Ausführung des Dashboards über die Schaltfläche Ausführen oder die automatische Aktualisierung des Dashboards oder über das Einbettungs-SDK ausgelöst wurde. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. Hinweis: lastRunSourceElementId kann mit der Element-ID der aktuellen Erweiterungs-Instanz übereinstimmen. Wenn die Erweiterung beispielsweise einen Dashboard-Lauf auslöst, wird sie benachrichtigt, wenn der Dashboard-Lauf beginnt und endet.
lastRunStartTime	Gibt den Startzeitpunkt der letzten Dashboard-Ausführung an. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. Die angegebenen Start- und Endzeiten sollten nicht für die Erfassung von Leistungsmesswerten verwendet werden.
lastRunEndTime	Gibt die Endzeit der letzten Dashboard-Ausführung an. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. Wenn die Kachel aktiv ist, wird diese Property nicht ausgefüllt. Die angegebenen Start- und Endzeiten sollten nicht für die Erfassung von Leistungsmesswerten verwendet werden.
lastRunSuccess	Gibt an, ob die letzte Ausführung des Dashboards erfolgreich war. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. Wenn die Kachel aktiv ist, wird diese Property nicht ausgefüllt.

Funktionen und Eigenschaften des Visualisierungs-SDK

Die verfügbaren Funktionen und Eigenschaften des Visualisierungs-SDKs sind in der folgenden Tabelle aufgeführt:

Funktion oder Property	Beschreibung
visualizationData (property)	Visualisierung (Kombination von visConfig- und queryResponse-Daten)
visConfig (property)	Daten zur Visualisierungskonfiguration: Messkonfigurationen Dimensionskonfigurationen Tabellenkalkulationen Pivot-Konfigurationen Visualisierungskonfigurationen Mit diesen Einstellungen können Sie das Erscheinungsbild einer Visualisierung in einem Explore anpassen.
queryResponse (property)	Antwortdaten aus der Abfrage
configureVisualization	Legt die Standardkonfiguration für eine Erweiterungsvisualisierung fest. Die Konfiguration wird im Editor für Explore-Visualisierungen gerendert. Diese Methode sollte nur einmal aufgerufen werden.
setVisConfig	Aktualisiert die Visualisierungskonfiguration.
updateRowLimit	Aktualisiert die Zeilenbegrenzung der Abfrage.

Daten des Visualisierungs-SDK

Das Visualisierungs-SDK besteht aus folgenden Elementen:

• Konfigurationsdaten für Visualisierungen
• Antwortdaten abfragen

Konfigurationsdaten für Visualisierungen

Attribut	Beschreibung
queryFieldMeasures	Messinformationen
queryFieldDimensions	Dimensionsinformationen
queryFieldTableCalculations	Informationen zu Tabellenkalkulationen
queryFieldPivots	Pivot-Informationen
visConfig	Daten zur visuellen Konfiguration Diese sollte mit der Standardkonfiguration zusammengeführt und auf die Visualisierung angewendet werden, die von der Erweiterung gerendert wird.

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

Antwortdaten abfragen

Attribut	Beschreibung
data	Array mit Zeilendaten
fieldMeasures	Informationen zu Feldmesswerten.
fieldDimensions	Informationen zur Felddimension.
fieldTableCalculations	Informationen zu Tabellenkalkulationen für Felder.
fieldPivots	Informationen zum Pivot-Feld.
fieldMeasureLike	Ein verkettetes Array von Informationen zu Feldmesswerten und Tabellenkalkulationen, die sich wie Messwerte verhalten.
fieldDimensionLike	Ein verkettetes Array von Informationen zu Felddimensionen und Tabellenkalkulationen, die sich wie Dimensionen verhalten.