Gebäudekachel-Erweiterungen

Ab Looker 24.0 können Erweiterungen entwickelt werden, die in einer Kachel in Dashboards ausgeführt werden. Erweiterungen, die als Tile oder Visualisierung ausgeführt werden können, können hinzugefügt werden, während sich das Dashboard im Bearbeitungsmodus befindet, oder als Visualisierung aus einem Explore 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:

• Die Erweiterung für die Kachelvisualisierung zeigt, wie Sie mit dem Erweiterungsframework eine benutzerdefinierte Visualisierung erstellen.
• Die Kachel-SDK-Erweiterung enthält die verfügbaren API-Methoden, die speziell für Kachelerweiterungen gelten.

Achtung :Eingebettete Looker-Inhalte wie Berichte, Dashboards, Looks, Explores, LookML-Dashboards und Visualisierungen von Abfragen können nicht in Kachel-Erweiterungen verwendet werden.

Looker Extension SDK mit Kachel-Erweiterungen verwenden

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

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

• dashboard_vis: Wenn diese Option aktiviert ist, wird die Erweiterung in den Visualisierungsoptionen eines Explores 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 für die Erweiterung verfügbar gemacht. Das funktioniert ähnlich wie bei benutzerdefinierten Visualisierungen. Der Hauptunterschied zwischen einer benutzerdefinierten Visualisierung und einer Erweiterung, die in einer Dashboardkachel mit aktivierter dashboard_vis ausgeführt wird, 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 nach dem Klicken auf die Schaltfläche Hinzufügen die Option Erweiterungen auswählt. Diese Art von Erweiterung ist dafür verantwortlich, eigene Daten abzurufen, anstatt dass die Kachel automatisch Daten für die Erweiterung bereitstellt.

Ein zusätzlicher Bereitstellungspunkt, standalone, bewirkt, dass die Erweiterung im Hauptmenü von Looker unter Anwendungen angezeigt wird. Für eine Erweiterung können mehrere Bereitstellungspunkte definiert werden. Zur Laufzeit wird die Erweiterung darüber informiert, wie sie eingebunden ist, und kann ihr Verhalten entsprechend anpassen. Beispielsweise müssen standalone-Erweiterungen möglicherweise ihre eigene Höhe festlegen, während Kachel-Erweiterungen das nicht tun müssen.

Zusätzliche APIs für Kachel-Erweiterungen

Kachel-Erweiterungen werden zur Laufzeit mit zusätzlichen APIs und Daten bereitgestellt. Diese werden aus dem Erweiterungskontext abgerufen:

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

• tileSDK: Stellt kachelspezifische Funktionen bereit, mit denen die Erweiterung mit dem Looker-Dashboard-Host interagieren kann. Damit die Erweiterung beispielsweise Fehlermeldungen anzeigen und löschen kann.
• tileHostData: Stellt der Erweiterung Ansichtsdaten zur Verfügung. Die Daten werden automatisch auf Grundlage von Interaktionen mit dem Hosting-Dashboard aktualisiert. Ein Beispiel dafür ist der Indikator isDashboardEditing.
• visualizationSDK: Stellt visualisierungsspezifische Funktionen bereit, mit denen die Erweiterung mit dem Looker-Dashboard-Host interagieren kann. Ein Beispiel dafür ist die Funktion updateRowLimit.
• visualizationData: Stellt Visualisierungsdaten für die Erweiterung bereit. Die Daten werden automatisch auf Grundlage von Interaktionen mit dem Hosting-Dashboard aktualisiert. Die Daten ähneln den Daten, 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 die Größe des übergeordneten Looker-Hostfensters ändert. Dies wird automatisch im Inhaltsfenster des iFrames berücksichtigt. Die iFrame-Komponente hat keinen Innen- oder Außenabstand. Die Erweiterung muss also selbst für Innen- und Außenabstand sorgen, damit sie mit der Looker-Anwendung konsistent aussieht. Bei eigenständigen Erweiterungen ist es Aufgabe der Erweiterung, die Höhe der Erweiterung zu steuern. Bei Erweiterungen, die in Dashboard-Kacheln oder Explore-Visualisierungen ausgeführt werden, wird das Inhaltsfenster des iFrames automatisch auf die vom iFrame bereitgestellte Höhe festgelegt.

Überlegungen zum Rendern

Kachel-Erweiterungen 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 sehen Sie ein Beispiel dafür, wie Sie den Renderer benachrichtigen, dass die Kachel gerendert wurde.

  const { extensionSDK } = useContext(ExtensionContext40)

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

Animationen sollten auch beim Rendern deaktiviert werden. Im folgenden Beispiel sind die Animationskonfigurationen beim Rendern 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} />
  }

Tile SDK-Funktionen und -Attribute

Das Tile SDK bietet Funktionen, mit denen eine Kachelerweiterung mit dem zugehörigen Dashboard interagieren kann.

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

Funktion oder Attribut	Beschreibung
tileHostData (Attribut)	Hostdaten, die für die Kachelerweiterung spezifisch sind. Weitere Informationen finden Sie im Abschnitt Tile SDK-Daten.
addError	Wenn der Aufruf erfolgt, wird im Dashboard oder in Explore unter der Visualisierung eine Fehlermeldung angezeigt.
clearError	Wenn diese Funktion aufgerufen wird, werden alle Fehlermeldungen, die unter der Visualisierung angezeigt werden, im Dashboard oder Explore ausgeblendet.
openDrillMenu	Bei Visualisierungserweiterungen wird mit diesem Aufruf ein Drilldown-Menü geöffnet. Dieser Aufruf wird ignoriert, wenn die Erweiterung keine Kachel-Erweiterung ist.
runDashboard	Führt das aktuelle Dashboard aus. Dieser Aufruf wird von einer Kachelvisualisierungserweiterung, die in einem Explore ausgeführt wird, ignoriert.
stopDashboard	Beendet ein laufendes Dashboard. Dieser Aufruf wird von einer Kachelvisualisierungserweiterung, die in einem Explore ausgeführt wird, ignoriert.
updateFilters	Aktualisiert Filter im aktuellen Dashboard oder Explore.
openScheduleDialog	Öffnet das Dialogfeld „Zeitplan“. Dieser Aufruf wird ignoriert, wenn er in einem Explore ausgeführt wird.
toggleCrossFilter	Schaltet Kreuzfilter ein oder aus. Dieser Aufruf wird ignoriert, wenn er in einem Explore ausgeführt wird.

Tile SDK-Daten

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

Attribut	Beschreibung
isExploring	Wenn „true“, 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 Kachel, die gerendert wird. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
queryId	Die Abfrage-ID des Tiles, das gerendert wird, falls es 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 beim Erstellen der Visualisierung im Looker-Explore erstellt wird. Es enthält keine Filter oder Kreuzfilter, die auf das Dashboard angewendet werden können. Damit die Daten im QueryResponse angezeigt werden, müssen Filter und Kreuzfilter angewendet und eine neue Abfrage generiert werden. Daher kann es mehr nützliche Eigenschaften als queryId geben. Ein Abfrageobjekt mit angewendeten Filtern finden Sie unter filteredQuery.
querySlug	Der Slug der Abfrage des Tiles, das gerendert wird, sofern es 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 im Looker-Bereich „Explore“ erstellt wird. Es enthält keine Filter oder Kreuzfilter, die auf das Dashboard angewendet werden. Damit die Daten im QueryResponse angezeigt werden, müssen Filter und Kreuzfilter angewendet und eine neue Abfrage generiert werden. Daher kann es mehr nützliche Eigenschaften als querySlug geben. Ein Abfrageobjekt mit angewendeten Filtern finden Sie unter filteredQuery.
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 das Kachel als Explore konfiguriert wird, ist der Status UNKNOWN. Aus Leistungsgründen wird der Ausführungsstatus im Dashboard möglicherweise nie als „Wird ausgeführt“ angezeigt. Das ist in der Regel der Fall, wenn einer Abfrage keine anderen Kacheln zugeordnet sind, auch nicht die, 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ässige Methode.
isDashboardEditing	Bei „true“ wird das Dashboard bearbeitet. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
isDashboardCrossFilteringEnabled	Wenn „true“ festgelegt ist, ist die Kreuzfilterung für das Dashboard aktiviert. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt.
filteredQuery	Ein Abfrageobjekt, das der Abfrage-ID entspricht, die dem zugrunde liegenden Dashboard-Element zugeordnet ist. Es werden alle Dashboardfilter und Zeitzonenänderungen angewendet, die auf Dashboard-Ebene vorgenommen wurden.
lastRunSourceElementId	Die ID des Kachelerweiterungselements, das den letzten Dashboard-Lauf ausgelöst hat. Die ID ist nicht definiert, wenn der Dashboard-Lauf über die Schaltfläche Ausführen oder Automatisches Aktualisieren im Dashboard ausgelöst wurde oder wenn der Lauf über das Embed SDK ausgelöst wurde. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. lastRunSourceElementId kann mit der Element-ID der aktuellen Erweiterungsinstanz identisch sein. Wenn die Erweiterung beispielsweise einen Dashboard-Lauf auslöst, wird sie benachrichtigt, wenn der Dashboard-Lauf beginnt und endet.
lastRunStartTime	Gibt die Startzeit des letzten Dashboard-Laufs an. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. Die angegebenen Start- und Endzeiten sollten nicht zum Erfassen von Leistungsmesswerten verwendet werden.
lastRunEndTime	Gibt die Endzeit des letzten Dashboard-Laufs an. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. Wenn die Kachel ausgeführt wird, wird diese Property nicht ausgefüllt. Die angegebenen Start- und Endzeiten sollten nicht zum Erfassen von Leistungsmesswerten verwendet werden.
lastRunSuccess	Gibt an, ob der letzte Dashboard-Lauf erfolgreich war. Wenn die Kachel als Explore konfiguriert wird, wird diese Property nicht ausgefüllt. Wenn die Kachel ausgeführt wird, wird diese Property nicht ausgefüllt.

Funktionen und Attribute des Visualization SDK

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

Funktion oder Attribut	Beschreibung
visualizationData (Attribut)	Visualisierung (Kombination aus visConfig- und queryResponse-Daten).
visConfig (Attribut)	Konfigurationsdaten für die Visualisierung: Konfigurationen für Messungen Dimensionskonfigurationen Tabellenkalkulationen Pivot-Konfigurationen Visualisierungskonfigurationen Sie werden verwendet, um das Erscheinungsbild einer Visualisierung in einem Explore anzupassen.
queryResponse (Attribut)	Antwortdaten aus der Anfrage
configureVisualization	Legt die Standardkonfiguration für eine Erweiterungsvisualisierung fest. Die Konfiguration wird im Visualisierungseditor von Explore gerendert. Diese Methode sollte nur einmal aufgerufen werden.
setVisConfig	Aktualisiert die Visualisierungskonfiguration.
updateRowLimit	Aktualisiert die Zeilenbegrenzung der Abfrage.

Daten des Visualization SDK

Das Visualisierungs-SDK besteht aus folgenden Komponenten:

• Konfigurationsdaten für die Visualisierung
• Antwortdaten abfragen

Konfigurationsdaten für die Visualisierung

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 von der Erweiterung gerenderte Visualisierung angewendet werden.

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

Antwortdaten abfragen

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

Embed SDK verwenden

Die Verwendung des Embed SDK in einer Kachel-Erweiterung wird aus folgenden Gründen nicht empfohlen:

• Es ist möglich, dass die Erweiterung ein Dashboard rendert, in dem sie als Kachel angezeigt wird. Das Erweiterungs-Framework kann dies nicht erkennen und der Browser stürzt möglicherweise ab.
• Das Rendern von eingebetteten Inhalten in einer Kachel-Erweiterung als PDF funktioniert nicht.