Referenz zur Custom Visualization API 2.0

Ein Aufruf der Funktion looker.plugins.visualizations.add ist der Einstiegspunkt in die Visualization API. Diese Funktion akzeptiert ein Visualisierungsobjekt , das Ihre benutzerdefinierte Visualisierung vollständig definiert.

Hier ist ein Beispiel für eine Visualisierung:

looker.plugins.visualizations.add({
    create: function(element, config){
        element.innerHTML = "<h1>Ready to render!</h1>";
    },
    updateAsync: function(data, element, config, queryResponse, details, doneRendering){
        var html = "";
        for(var row of data) {
            var cell = row[queryResponse.fields.dimensions[0].name];
            html += LookerCharts.Utils.htmlForCell(cell);
        }
        element.innerHTML = html;
        doneRendering()
    }
});

Umgebung

Da die Visualization API reines JavaScript ist, können Sie beliebige JavaScript-Bibliotheken verwenden, um Ihre Daten zu visualisieren.

Ihr JavaScript-Code wird in einem Sandboxed-iFrame ausgeführt, getrennt von Ihrer Looker-Instanz. Dennoch sind die Autoren benutzerdefinierter Visualisierungen dafür verantwortlich, dass der von ihnen geschriebene Code sicher ist.

Wie bei der gesamten Webentwicklung kann die Unterstützung verschiedener Webbrowser (Chrome, Edge, Firefox) gelegentlich ein Problem darstellen. Die Visualization API funktioniert in allen von Looker unterstützten Browsern. Sie müssen jedoch dafür sorgen, dass Ihr benutzerdefinierter Code vom Browser unterstützt wird. Beispielsweise funktionieren ES6-Verwendungen wie let oder ()=> in den meisten Browsern, können aber in IE11 oder beim Rendern von PDFs mit PhantomJS zu Fehlern führen.

Installation

Sie installieren benutzerdefinierte Visualisierungen, indem Sie ein Manifest mit dem Formular „Admin“ > „Plattform“ > „Visualisierungen“ definieren. Ein Manifest besteht aus einer eindeutigen String-ID, einem menschenlesbaren Label, der URI Ihrer Visualisierung und Links zu allen erforderlichen Abhängigkeiten (z. B. d3, jQuery, underscore).

Benutzerdefinierte Visualisierungen sollten extern von Looker als HTTPS-Inhalte bereitgestellt werden. Wenn Sie von der ersten Version der benutzerdefinierten Visualization API migrieren, haben Sie möglicherweise Dateien im Verzeichnis looker/plugins/visualizations. Dieser Speicherort ist weiterhin zugänglich und es kann ein relativer Pfad zu Ihrer Visualisierung angegeben werden. Wir empfehlen jedoch, Ihre Inhalte an einen anderen Speicherort zu migrieren. Da sich das Verzeichnis /plugins nicht im freigegebenen Dateisystem befindet, haben Clusterumgebungen nicht auf allen Knoten Zugriff auf Ihre Visualisierungsdateien.

Das Visualisierungsobjekt

Das Visualisierungsobjekt verwendet die folgenden erforderlichen, optionalen und hinzugefügten Eigenschaften.

Erforderliche Attribute

• create Funktion

  Diese Funktion wird einmal aufgerufen, wenn Ihre Visualisierung zum ersten Mal auf der Seite gezeichnet wird. Sie sollte alles einrichten, was Ihre Visualisierung immer verfügbar haben soll. Sie können eine Bibliothek laden oder eine Reihe von Elementen und Steuerelementen erstellen, die Sie später verwenden.

  Details zur Funktion create ansehen →

• updateAsync / update Funktion

  Diese Funktion wird jedes Mal aufgerufen, wenn sich der Status Ihrer Visualisierung ändern muss. Sie wird immer nach create aufgerufen und kann viele Male aufgerufen werden. Daher sollte sie so schnell wie möglich sein.

  Diese Funktion kann aus vielen Gründen aufgerufen werden, in der Regel jedoch, wenn die zu visualisierende Abfrage geändert wurde, eine Konfigurationsoption geändert wurde oder die Größe der Visualisierung geändert wurde.

  Diese Funktion hat eine synchrone und eine asynchrone Version. Sie müssen nur eine angeben. Es ist ein Fehler, beide zu definieren. Die asynchrone Methode ist aufgrund der Beschaffenheit von iFrames zuverlässiger für das Rendern von PDFs.

  Details zu diesen update-Funktionen ansehen →

Optionale Attribute

• options Objekt

  Ein Objekt mit Details zu den Optionen, die Nutzer für Ihre Visualisierung festlegen können.

  Details zum Bereitstellen einer Konfigurations-UI ansehen →

• destroy Funktion Noch nicht in API V2 implementiert

  Eine Funktion, die aufgerufen wird, kurz bevor die Visualisierung von der Seite entfernt wird. Verwenden Sie diese Funktion, um Event-Listener oder andere Status zu bereinigen. Sie wird möglicherweise nie aufgerufen, wenn der Nutzer beispielsweise das Fenster schließt.

Zusätzliche Attribute

Looker fügt Ihrem Objekt automatisch die folgenden Eigenschaften hinzu, nachdem die Visualisierung an looker.plugins.visualizations.add übergeben wurde. Sie können mit this im Kontext der Funktionen create, update, updateAsync und destroy darauf verweisen.

• addError Funktion

  Eine Funktion, die von Ihrem Visualisierungscode aufgerufen werden kann, um der UI mitzuteilen, dass anstelle der Visualisierung eine Fehlermeldung angezeigt werden soll. Sie verwendet ein error-Objekt.

  Sobald ein Fehler hinzugefügt wurde, bleibt er sichtbar, bis clearErrors aufgerufen wird.

  Beispiel :

  this.addError({
      title: "Two Dimensions Required",
      message: "This really great visualization requires two dimensions."
  });
  

• clearErrors Funktion

  Eine Funktion, die von Ihrem Visualisierungscode aufgerufen werden kann, um alle Fehler zu löschen, die mit addError hinzugefügt wurden.

  Beispiel :

  this.clearErrors();
  

• trigger Funktion

  Eine Funktion, die aufgerufen werden kann, um ein Ereignis außerhalb der Visualisierung auszulösen.

  Details zu Ereignissen ansehen →

  Beispiel :

  this.trigger("limit", [20]);
  

Die Funktion create

An die Funktion create werden zwei Parameter übergeben: element und config.

create: function(element, config){
  // Your update code here.
},

Parameter

• element DOMElement

  Ein DOM-Element, das einen Container darstellt, in dem Ihre Visualisierung gerendert werden soll.

• config Objekt

  Ein Objekt, das die Werte aller Konfigurationsoptionen darstellt, die der Nutzer für dieses Diagramm festgelegt hat.

  Beispiel: {my_configuration_option: "User Value"}

Die updateAsync und update Funktionen

Die bevorzugte Methode zum Aktualisieren Ihrer Visualisierung ist die Methode updateAsync. Mit dieser Methode kann Ihre Visualisierung eine asynchrone Aktion ausführen, z. B. eine Datei laden oder eine Webanfrage senden.

Diese Version der Funktion hat einen zusätzlichen Parameter, nämlich einen Callback, der aufgerufen wird, wenn das Rendering abgeschlossen ist:

updateAsync: function(data, element, config, queryResponse, details, done){
    // An example of an asynchronous update, fetching a file.
    d3.request("https://example.com/fun-file.docx").response(function(xhr) {
        // Your update code here that uses this file.
        done();
    });
}

Wenn Looker benachrichtigt wird, wenn das Rendering der Visualisierung abgeschlossen ist, kann Looker das Rendern von PDFs optimieren und dafür sorgen, dass Bilder von Visualisierungen richtig erfasst werden.

Einige ältere Visualisierungen verwenden die Funktion update. Diese Funktion funktioniert zwar weiterhin, ist aber nicht die bevorzugte Methode, da Looker nicht benachrichtigt wird, wenn eine Visualisierung vollständig gerendert wurde. An die Funktion update werden fünf Parameter übergeben:

update: function(data, element, config, queryResponse, details){
  // Your update code here.
}

Parameter

• data Array

  Ein Array von Zeilen, die die aktuellen Daten in der Abfrage darstellen. Kann null sein.

  Jede Zeile ist ein Objekt mit den Schlüsseln, die Feldnamen darstellen, und dem Wert, der ein „Zellenobjekt“ darstellt. Hier finden Sie Details zum Umgang mit dem Zellenobjekt.

• element DOMElement

  Ein DOM-Element, das einen Container darstellt, in dem Ihre Visualisierung gerendert werden soll.

• config Objekt

  Ein Objekt, das die Werte aller Konfigurationsoptionen darstellt, die der Nutzer für dieses Diagramm festgelegt hat.

  Beispiel: {my_configuration_option: "User Value"}

• queryResponse Objekt

  Ein Objekt, das Metadaten zur aktuellen Abfrage darstellt, z. B. Metadaten zu Feldern. Kann null sein.

• details Objekt

  Details zum aktuellen Renderingkontext. Enthält Informationen dazu, warum das Diagramm gerendert wird und was sich geändert hat. Diese Informationen werden in der Regel nur in erweiterten Fällen verwendet.

  Für Crossfilter in Looker-Dashboards, die die neue Dashboard-Erfahrung verwenden, sind die zulässigen Attribute crossfilterEnabled und crossfilters.

  Das Attribut print kann in Verbindung mit der Funktion done verwendet werden, um das Rendern von PDFs für benutzerdefinierte Visualisierungen zu verbessern, insbesondere für solche mit Animationen. Beispiel:

  if (details.print) {
          done();
  }
  

• done Funktion

  Ein Callback, um anzugeben, dass die Visualisierung vollständig gerendert wurde. Diese Funktion muss unbedingt aufgerufen werden, wenn Ihre Visualisierung asynchrone Aufrufe ausführen oder als PDF gerendert werden muss.

Daten rendern

Looker bietet in LookML eine Vielzahl von Tools zur Datenformatierung, mit denen Sie das Erscheinungsbild und das Verhalten von Datenpunkten anpassen können. Zu diesen Tools gehören LookML-Einstellungen auf Feldebene wie benutzerdefinierte Wertformate, HTML, Drill-Links und Datenaktionen.

Zellen haben eine value-Eigenschaft, die die einzige Eigenschaft ist, die in allen Fällen vorhanden ist. Diese Eigenschaft ist ein JavaScript-Typ, der dem Typ des Felds entspricht, zu dem die Zelle gehört. Es ist jedoch nicht sicher, eine value-Eigenschaft direkt in HTML oder SVG einzufügen, da keine HTML-Escapes durchgeführt wurden. Einige Feldwerte sind komplexe JavaScript-Objekte oder -Arrays, die auf unerwünschte oder verwirrende Weise gerendert werden.

Damit alle Visualisierungen diese Elemente einheitlich und sicher rendern, gibt es eine Reihe von Dienstfunktionen, mit denen die Zellenmetadaten, die in data an Ihr Diagramm übergeben werden, in verschiedene Darstellungen für verschiedene Zwecke umgewandelt werden können. Die Zellenmetadaten können in einigen Fällen bestimmte Felder komprimieren oder auslassen. Mit diesen Hilfsfunktionen können Sie eine einheitliche Nutzererfahrung bieten.

Alle diese Hilfsfunktionen sind im globalen LookerCharts.Utils-Objekt verfügbar.

• LookerCharts.Utils.textForCell(cell)

  Diese Funktion akzeptiert eine Zelle und gibt eine Stringdarstellung zurück, die für die Anzeige geeignet ist. Es ist immer ein String. Diese Funktion gibt nie null oder einen anderen Typ zurück.

• LookerCharts.Utils.htmlForCell(cell)

  Diese Funktion akzeptiert eine Zelle und gibt einen String mit HTML zurück. Es ist immer ein String. Diese Funktion gibt nie null oder einen anderen Typ zurück.

  Die Ausgabe dieser Funktion ist korrekt escaped und kann direkt in das HTML Ihres Elements eingefügt werden. Das Ausgabe-HTML zeigt auch das Drill-Menü korrekt an, wenn es für die Daten geeignet ist.

• LookerCharts.Utils.filterableValueForCell(cell)

  Diese Funktion akzeptiert eine Zelle und gibt einen Looker-String mit erweiterter Filtersyntax zurück, der mit dem Wert dieser Zelle übereinstimmt.

• LookerCharts.Utils.toggleCrossfilter({row, pivot, event})

  Diese Funktion akzeptiert eine Zeile, einen Pivot oder ein Ereignis und wird verwendet, um zu prüfen, ob die Crossfilterung für eine Visualisierung aktiviert ist. Im folgenden Beispiel wird gezeigt, wie einem Element ein Event-Listener hinzugefügt wird, der prüft, ob die Crossfilterung aktiviert ist, wenn das Ereignis eintritt:

  d3.select("#myElement")
  .on("click", function (d) {
      if (details.crossfilterEnabled) {
              LookerCharts.Utils.toggleCrossfilter({
                  row: d.row,
                  event: d3.event,
              });
      } else {
        // ... handle click when cross-filtering is not enabled
      }
  });
  

• LookerCharts.Utils.getCrossfilterSelection(row, pivot?)

  Diese Funktion akzeptiert eine Zeile oder einen Pivot und wird verwendet, um zu prüfen, ob diese Zeile oder dieser Pivot in einer benutzerdefinierten Visualisierung ausgewählt ist. Die Funktion gibt eine Enumeration für CrossfilterSelection {NONE, SELECTED, UNSELECTED} zurück: 0 für NONE, 1 für SELECTED und 2 für UNSELECTED.

  Im folgenden Beispiel wird bedingt eine Füllfarbe auf eine Zeile angewendet, wenn sie crossgefiltert wird. Standardfarben werden angewendet, wenn die Crossfilterung für diese Zeile nicht aktiviert ist:

  d3.select("#myElement")
  .attr("fill", function (d) {
      const crossfilter = LookerCharts.Utils.getCrossfilterSelection(d.row)
      if (details.crossfilterEnabled && crossfilter === 1) {
              return d.color
      } else {
              return "#DEE1E5" //Hex used for unselected elements in native visualizations
  ...
  

• LookerCharts.Utils.openDrillMenu(options)

  Die Ausgabe von htmlForCell zeigt bei Bedarf automatisch das Drill-Menü an. Das ist jedoch möglicherweise nicht für bestimmte Arten des Renderings geeignet. Beispielsweise kann SVG kein HTML rendern, aber Sie möchten möglicherweise ein Klickereignis erfassen, um einen Drill zu starten.

  Das Objekt options hat die folgenden Parameter:

  • links Erforderlich Array

    Ein Array der Objekte, die von der Eigenschaft links einer Zelle zurückgegeben werden. Wenn Sie Links für mehrere Zellen gleichzeitig anzeigen möchten, können Sie diese Arrays zuerst verketten. Geben Sie für benutzerdefinierte Links ein Array von Objekten im folgenden Format an:

    { label: string, type: 'drill', type_label: string, url: url }

  • event HTML-DOM-Ereignis

    Das Klickereignis (oder ein anderes Ereignis), das das Drill-Ereignis verursacht hat. Looker verwendet dies, um festzulegen, wo das Drill-Menü platziert werden soll. Wenn Sie keines haben, übergeben Sie ein Objekt mit den Koordinaten pageX und pageY.

  Beispiel :

  for (var row of data) {
      var cell = row[queryResponse.fields.dimensions[0].name];
      var cellElement = myBuildElementFunction(cell);
      cellElement.onclick = function(event) {
          LookerCharts.Utils.openDrillMenu({
              links: cell.links,
              event: event
          });
      };
      // ... more visualization stuff...
  }
  

Konfigurations-UI präsentieren

Der Parameter options ist ein Objekt, bei dem die Schlüssel eine beliebige ID für einen Optionsnamen sind und der Wert ein Objekt ist, das Informationen zur Option beschreibt.

Beispiel:

options: {
    color_range: {
      type: "array",
      label: "Color Range",
      display: "colors"
    },
   top_label: {
      type: "string",
      label: "Label (for top)",
      placeholder: "My Great Chart"
    },
    transport_mode: {
      type: "string",
      label: "Mode of Transport",
      display: "select",
      values: [
         {"Airplane": "airplane"},
         {"Car": "car"},
         {"Unicycle": "unicycle"}
      ],
      default: "unicycle"
    }
}

Parameter des Optionsobjekts

Das Objekt option hat die folgenden grundlegenden Parameter, anzeigespezifischen Eigenschaften und Organisationsoptionen.

Grundlegende Parameter

• type String

  Der Datentyp der Option.

  Zulässige Werte:string (Standard), number, boolean, array

• label String

  Das menschenlesbare Label der Option, das dem Nutzer angezeigt wird.

• default

  Der Standardwert der Option. Wenn kein Wert angegeben ist, ist der Wert der Option null. Dies sollte ein Wert desselben Typs wie type sein.

• display String

  Bestimmte type-Werte können in der UI auf verschiedene Arten dargestellt werden.

  • wenn type gleich string ist:

    Zulässige Werte:text (Standard), select, radio

  • wenn type gleich number ist:

    Zulässige Werte:number (Standard), range

  • wenn type gleich array ist:

    Zulässige Werte: text (Standard), color, colors

• placeholder String

  Für display-Werte, die dies unterstützen, ein Beispielwert oder eine Erklärung, um dem Nutzer einen Hinweis darauf zu geben, was er eingeben soll.

Anzeigespezifische Eigenschaften

• values Array von Objekten

  Wenn display gleich radio oder select ist, ein Array mit Labels und Werten, die in der Benutzeroberfläche aufgeführt werden.

  Jedes Element im Array sollte ein Objekt mit einem einzelnen Schlüssel/Wert-Paar sein, das das Label und den Wert der Option darstellt. Das Label wird nur in der UI präsentiert. Zur Renderingzeit erhalten Sie nur den Wert.

  Beispiel :

  values: [
      {"Center": "c"},
      {"Left": "l"},
      {"Right": "r"}
  ]
  

  Wenn display gleich radio ist, kann jeder Option zusätzlich eine description gegeben werden:

  values: [
      {"Cool": "c"},
      {"Uncool": {
              value: "unc",
              description: "Only choose this if the data is very uncool."
          }
      }
  ]
  

• max Zahl

  Wenn display gleich range ist, die maximale Zahl, die mit dem Bereichsschieberegler ausgewählt werden kann.

• min Zahl

  Wenn display gleich range ist, die minimale Zahl, die mit dem Bereichsschieberegler ausgewählt werden kann.

• step Zahl

  Wenn display gleich range ist, der Wert, den jeder Schritt des Bereichsschiebereglers darstellt.

Organisationsoptionen

• section String

  Für Diagramme mit vielen Optionen ein Label für den Abschnitt, in dem eine Option angezeigt werden soll. Die Optionen werden in der UI nach ihren section-Werten gruppiert. Wenn es nur einen Abschnitt gibt, wird die Abschnitts-UI nicht angezeigt.

  Wenn Sie section verwenden, muss es für jede Option festgelegt werden.

• order Zahl

  Eine Zahl, die die Reihenfolge der Optionen für die Präsentation in der UI darstellt. Wenn angegeben, werden die Optionen entsprechend dieser Reihenfolge sortiert.

• display_size String

  Eine Größenklasse, die die Breite der Option in der UI darstellt. Wenn Sie beispielsweise eine Option „Minimum“ und eine Option „Maximum“ nebeneinander anzeigen möchten, können Sie die Anzeigegröße für beide auf half festlegen.

  Zulässige Werte:normal (Standard), half, third

Ereignisse

Ereignisse können vom Diagramm ausgelöst werden (in der Regel als Reaktion auf die Nutzerinteraktion), wodurch Eigenschaften der Visualisierung oder Abfrage aktualisiert werden können.

Sie können ausgelöst werden, indem die Funktion trigger für das Visualisierungsobjekt aufgerufen wird. Der erste Parameter ist immer der Ereignisname und der zweite Parameter ist ein Array von Argumenten.

this.trigger("limit", [20]);

Verfügbare Ereignisse

• updateConfig

  Aktualisieren Sie die aktuellen Konfigurationseinstellungen des Diagramms.

  Argument:Ein Objekt mit Konfigurationsschlüsseln, die aktualisiert werden sollen. Nicht angegebene Schlüssel werden nicht geändert.

  Beispiel :

  var vis = this;
  $(element).find(".axis").click(function(){
      vis.trigger("updateConfig", [{axis_hidden: true}]);
  });
  

• limit

  Aktualisieren Sie das Limit der zugrunde liegenden Abfrage:

  Argument:Eine Ganzzahl, die ein neues Limit für die Abfrage darstellt.

  var vis = this;
  $(element).find(".show-all").click(function(){
      vis.trigger("limit", [500]);
  });
  

• filter

  Aktualisieren Sie den Wert eines Filters für die zugrunde liegende Abfrage:

  var vis = this;
  $(element).find(".show-all-tommys").click(function(){
      vis.trigger("filter", [{
          field: "users.name", // the name of the field to filter
          value: "%tommy%", // the "advanced syntax" for the filter
          run: true, // whether to re-run the query with the new filter
      }]);
  });
  

• loadingStart

  Markieren Sie die Visualisierung als wird geladen. Meistens ist das nicht erforderlich. Wenn Ihre Visualisierung jedoch ein Objekt von einem Remote-Standort lädt oder eine lange Berechnung durchführt, können Sie damit die Ladeanzeige weiterhin anzeigen.

  Sie wird als „Wird geladen“ angezeigt, bis loadingEnd ausgelöst wird.

• loadingEnd

  Markieren Sie die Visualisierung als nicht mehr geladen.

• printSize (Looker 26.0+)

  Ermöglicht es Visualisierungen, die Option „Tabellen für die Anzeige aller Zeilen maximieren“ zu nutzen, wenn Dashboards in PDFs gerendert werden. Mit diesem Ereignis kann die Anwendung die Höhe des gerenderten Inhalts ermitteln und die Dashboard-Kachel entsprechend maximieren, damit alle Informationen für den Druck sichtbar sind.

    this.trigger('printSize', {
      heightExpanded: FULL_HEIGHT_IN_PIXELS
    });
  

• registerOptions (Looker 5.24+)

  Ermöglicht es Visualisierungen, zusätzliche Optionen zu registrieren, nachdem die Visualisierung registriert wurde:

    update: function(data, element, config, queryResponse, details){
      options = {}
      // Create an option for each measure in your query
      queryResponse.fields.measure_like.forEach(function(field) {
        id = "color_" + field.name
        options[id] =
        {
      label: field.label_short + " Color",
      default: "#8B7DA8",
      section: "Style",
      type: "string",
      display: "color"
        }
      })
      this.trigger('registerOptions', options) // register options with parent page to update visConfig
      ...
    }
  });