Riferimento API 2.0 per la visualizzazione personalizzata

Una chiamata alla funzione looker.plugins.visualizations.add è il punto di ingresso nell'API Visualization. Questa funzione accetta un oggetto di visualizzazione che definisce completamente la visualizzazione personalizzata.

Ecco un esempio di visualizzazione:

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()
    }
});

Ambiente

Poiché l'API Visualization è in JavaScript semplice, puoi utilizzare qualsiasi libreria JavaScript per visualizzare i dati.

Il codice JavaScript verrà eseguito in un iframe in sandbox, separato dall'istanza di Looker. Tuttavia, gli autori delle visualizzazioni personalizzate sono responsabili di garantire la sicurezza del codice che scrivono.

Come per tutto lo sviluppo web, il supporto di diversi browser web (Chrome, Edge, Firefox) può occasionalmente essere un problema. L'API Visualization funziona su tutti i browser supportati da Looker, ma è tua responsabilità garantire il supporto del browser per il codice personalizzato. Ad esempio, l'utilizzo di ES6 come let o ()=> funzionerà nella maggior parte dei browser, ma potrebbe causare errori in IE11 o durante il rendering dei PDF utilizzando PhantomJS.

Installazione

Per installare le visualizzazioni personalizzate, devi definire un manifest utilizzando il modulo Amministrazione > Piattaforma > Visualizzazioni. Un manifest è costituito da un ID stringa univoco, un'etichetta leggibile, l'URI della visualizzazione e i link a eventuali dipendenze richieste (ad es. d3, jQuery, underscore).

Le visualizzazioni personalizzate devono essere pubblicate come contenuti HTTPS esternamente a Looker. Se stai eseguendo la migrazione dalla prima versione dell'API per le visualizzazioni personalizzate, potresti avere file nella directory looker/plugins/visualizations. Questa posizione è ancora accessibile e puoi fornire un percorso relativo alla visualizzazione, ma ti consigliamo di eseguire la migrazione dei contenuti in un'altra posizione. Poiché la directory /plugins non si trova nel file system condiviso, gli ambienti in cluster non avranno accesso ai file di visualizzazione su tutti i nodi.

L'oggetto di visualizzazione

L'oggetto di visualizzazione utilizza le seguenti proprietà obbligatorie, facoltative e aggiunte.

Proprietà obbligatorie

• create funzione

  Questa funzione viene chiamata una sola volta, quando la visualizzazione viene disegnata per la prima volta sulla pagina. È previsto che tu configuri tutto ciò che vuoi che la visualizzazione abbia sempre a disposizione. Potresti caricare una libreria o creare un insieme di elementi e controlli da utilizzare in un secondo momento.

  Scopri di più sulla funzione create →

• updateAsync / update funzione

  Questa funzione viene chiamata ogni volta che lo stato della visualizzazione potrebbe dover essere modificato. Viene sempre chiamata dopo create e può essere chiamata più volte, quindi deve essere il più veloce possibile.

  Questa funzione può essere chiamata per molti motivi, ma in genere quando la query da visualizzare è stata modificata, un'opzione di configurazione è stata modificata o la visualizzazione è stata ridimensionata.

  Questa funzione ha una versione sincrona e asincrona :emdash; devi specificarne solo una. (È un errore definire entrambe.) Il metodo asincrono è più affidabile per il rendering dei PDF a causa della natura degli iframe.

  Scopri di più su queste funzioni update →

Proprietà facoltative

• options oggetto

  Un oggetto che descrive in dettaglio le opzioni che gli utenti possono impostare nella visualizzazione.

  Scopri di più sull'esposizione di un'interfaccia utente di configurazione →

• destroy funzione Non ancora implementata nell'API V2

  Una funzione chiamata appena prima che la visualizzazione venga rimossa dalla pagina. Utilizza questa funzione per pulire eventuali listener di eventi o altri stati. Potrebbe non essere mai chiamata se, ad esempio, l'utente chiude la finestra.

Proprietà annuncio aggiunte

Looker aggiunge automaticamente le seguenti proprietà all'oggetto dopo che la visualizzazione viene passata a looker.plugins.visualizations.add. Puoi farvi riferimento utilizzando this nel contesto delle funzioni create, update, updateAsync e destroy.

• addError funzione

  Una funzione che il codice di visualizzazione può chiamare per indicare all'UI di visualizzare un messaggio di errore anziché la visualizzazione. Accetta un oggetto error.

  Una volta aggiunto un errore, rimarrà visibile finché non viene chiamata clearErrors.

  Esempio:

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

• clearErrors funzione

  Una funzione che il codice di visualizzazione può chiamare per cancellare eventuali errori aggiunti utilizzando addError.

  Esempio:

  this.clearErrors();
  

• trigger funzione

  Una funzione che può essere chiamata per attivare un evento al di fuori della visualizzazione.

  Scopri di più sugli eventi →

  Esempio:

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

La funzione create

Alla funzione create verranno passati due parametri, element e config.

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

Parametri

• element DOMElement

  Un elemento DOM che rappresenta un contenitore in cui eseguire il rendering della visualizzazione.

• config oggetto

  Un oggetto che rappresenta i valori di tutte le opzioni di configurazione impostate dall'utente per questo grafico.

  Esempio: {my_configuration_option: "User Value"}

Le funzioni updateAsync e update

Il metodo preferito per aggiornare la visualizzazione è updateAsync. Questo metodo consente alla visualizzazione di eseguire un'azione asincrona, ad esempio caricare un file o inviare una richiesta web.

Questa versione della funzione ha un parametro aggiuntivo, ovvero un callback da chiamare al termine del rendering:

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();
    });
}

Se avvisi Looker quando il rendering della visualizzazione è terminato, Looker può ottimizzare il rendering dei PDF e assicurarsi che le immagini delle visualizzazioni vengano acquisite correttamente.

Alcune visualizzazioni precedenti utilizzano la funzione update. Questa funzione funziona ancora, ma non è il metodo preferito, poiché il suo utilizzo significa che Looker non verrà avvisato quando il rendering di una visualizzazione è completo. Alla funzione update verranno passati cinque parametri:

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

Parametri

• data array

  Un array di righe che rappresentano i dati correnti nella query. Può essere null.

  Ogni riga è un oggetto con le chiavi che rappresentano i nomi dei campi e il valore che rappresenta un oggetto "cella". Ecco i dettagli sulla gestione dell'oggetto cella.

• element DOMElement

  Un elemento DOM che rappresenta un contenitore in cui eseguire il rendering della visualizzazione.

• config oggetto

  Un oggetto che rappresenta i valori di tutte le opzioni di configurazione impostate dall'utente per questo grafico.

  Esempio: {my_configuration_option: "User Value"}

• queryResponse oggetto

  Un oggetto che rappresenta i metadati della query corrente, ad esempio i metadati dei campi. Può essere null.

• details oggetto

  Dettagli sul contesto di rendering corrente. Contiene informazioni sul motivo per cui il grafico viene sottoposto a rendering e su cosa è cambiato. In genere queste informazioni vengono utilizzate solo in casi avanzati.

  Per quanto riguarda i filtri incrociati nelle dashboard di Looker che utilizzano la nuova esperienza dashboard, gli attributi consentiti includono crossfilterEnabled e crossfilters.

  L'attributo print può essere utilizzato insieme alla funzione done per migliorare il rendering dei PDF per le visualizzazioni personalizzate, in particolare quelle che includono animazioni. Ad esempio:

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

• done funzione

  Un callback per indicare che il rendering della visualizzazione è completo. È particolarmente importante chiamare questa funzione se la visualizzazione deve eseguire chiamate asincrone o deve essere sottoposta a rendering come PDF.

Rendering dei dati

Looker dispone di un ricco set di strumenti di formattazione dei dati in LookML che possono essere utilizzati per personalizzare l'aspetto e il comportamento dei punti dati. Questi strumenti includono impostazioni LookML a livello di campo come formati di valori personalizzati, HTML, link di drill e azioni sui dati.

Le celle hanno una proprietà value, che è l'unica proprietà esistente in tutti i casi. Questa proprietà è un tipo JavaScript che corrisponde al tipo di campo a cui appartiene la cella. Tuttavia, non è sicuro inserire una proprietà value direttamente in HTML o SVG, poiché non è stata eseguita alcuna escape HTML e alcuni valori dei campi sono oggetti o array JavaScript complessi che verranno sottoposti a rendering in modi indesiderati o confusi.

Per garantire che tutte le visualizzazioni eseguano il rendering di questi elementi in modo coerente e sicuro, esistono diverse funzioni di utilità per trasformare i metadati delle celle passati al grafico in data in rappresentazioni diverse per scopi diversi. In alcuni casi, i metadati delle celle possono comprimere o omettere determinati campi e queste funzioni helper ti consentono di offrire un'esperienza coerente.

Queste funzioni helper sono tutte disponibili nell'oggetto globale LookerCharts.Utils.

• LookerCharts.Utils.textForCell(cell)

  Questa funzione accetta una cella e restituisce una rappresentazione stringa adatta alla visualizzazione. Sarà sempre una stringa: questa funzione non restituisce mai null o qualsiasi altro tipo.

• LookerCharts.Utils.htmlForCell(cell)

  Questa funzione accetta una cella e restituisce una stringa contenente HTML. Sarà sempre una stringa: questa funzione non restituisce mai null o qualsiasi altro tipo.

  L'output di questa funzione è sottoposto a escape correttamente ed è adatto per l'inserimento diretto nell'HTML dell'elemento. L'HTML di output visualizzerà correttamente anche il menu di drill al clic quando è appropriato per i dati.

• LookerCharts.Utils.filterableValueForCell(cell)

  Questa funzione accetta una cella e restituisce una stringa di sintassi di filtro avanzato di Looker che corrisponde al valore di questa cella.

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

  Questa funzione accetta una riga, una tabella pivot o un evento e viene utilizzata per verificare se il filtro incrociato è abilitato per una visualizzazione. L'esempio seguente mostra come aggiungere un listener di eventi a un elemento che verifica se il filtro incrociato è abilitato quando si verifica l'evento:

  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?)

  Questa funzione accetta una riga o una tabella pivot e viene utilizzata per verificare se la riga o la tabella pivot è selezionata in una visualizzazione personalizzata. La funzione restituisce un'enumerazione per CrossfilterSelection {NONE, SELECTED, UNSELECTED} di 0 se NONE, 1 se SELECTED e 2 se UNSELECTED.

  L'esempio seguente applica in modo condizionale un colore di riempimento a una riga se viene filtrata incrociatamente e applica i colori predefiniti se il filtro incrociato non è abilitato per quella riga:

  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)

  L'output di htmlForCell mostrerà automaticamente il menu di drill, se necessario, ma potrebbe non essere appropriato per determinati tipi di rendering. Ad esempio, SVG non può eseguire il rendering di HTML, ma potresti voler acquisire un evento di clic per avviare un drill.

  L'oggetto options ha i seguenti parametri:

  • links Obbligatorio array

    Un array degli oggetti restituiti dalla proprietà links di una cella. Se vuoi visualizzare i link per più celle contemporaneamente, puoi concatenare prima questi array. Per i link personalizzati, fornisci un array di oggetti con il seguente formato:

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

  • event Evento DOM HTML

    L'evento di clic (o altro) che ha causato l'evento di drill. Looker lo utilizzerà per determinare dove posizionare il menu di drill. Se non ne hai uno, prova a passare un oggetto con le coordinate pageX e pageY.

  Esempio:

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

Presentazione dell'interfaccia utente di configurazione

Il parametro options è un oggetto in cui le chiavi sono un identificatore arbitrario per un nome di opzione e il valore è un oggetto che descrive le informazioni sull'opzione.

Ecco un esempio:

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

Parametri dell'oggetto opzione

L'oggetto option ha i seguenti parametri di base, proprietà specifiche per la visualizzazione e opzioni di organizzazione.

Parametri base

• type stringa

  Il tipo di dati dell'opzione.

  Valori consentiti: string (valore predefinito), number, boolean, array

• label stringa

  L'etichetta leggibile dell'opzione che verrà visualizzata all'utente.

• default

  Il valore predefinito dell'opzione. Se non specificato, il valore dell'opzione è null. Questo deve essere un valore dello stesso tipo di type.

• display stringa

  Alcuni valori type possono essere presentati nell'UI in modi diversi.

  • quando type è string:

    Valori consentiti: text (valore predefinito), select, radio

  • quando type è number:

    Valori consentiti: number (valore predefinito), range

  • quando type è array:

    Valori consentiti: text (valore predefinito), color, colors

• placeholder stringa

  Per i valori display che lo supportano, un valore o una spiegazione di esempio per dare all'utente un suggerimento su cosa digitare.

Proprietà specifiche per la visualizzazione

• values array di oggetti

  Quando display è radio o select, un array contenente etichette e valori che verranno elencati nell'interfaccia.

  Ogni elemento dell'array deve essere un oggetto con una singola coppia chiave-valore, che rappresenta l'etichetta e il valore dell'opzione. L'etichetta verrà presentata solo nell'UI; al tempo di rendering, riceverai solo il valore.

  Esempio:

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

  Se display è radio, a ogni opzione può essere assegnata anche una description:

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

• max numero

  Quando display è range, il numero massimo consentito per la selezione tramite il cursore dell'intervallo.

• min numero

  Quando display è range, il numero minimo consentito per la selezione tramite il cursore dell'intervallo.

• step numero

  Quando display è range, la quantità rappresentata da ogni segno di graduazione del cursore dell'intervallo.

Opzioni di organizzazione

• section stringa

  Per i grafici con molte opzioni, un'etichetta per la sezione in cui deve essere visualizzata un'opzione. L'UI raggrupperà le opzioni in base ai relativi valori section. Se è presente una sola sezione, l'UI della sezione non verrà visualizzata.

  Se utilizzi section, devi impostarlo su ogni opzione.

• order numero

  Un numero che rappresenta l'ordine delle opzioni per la presentazione nell'UI. Se specificate, le opzioni verranno ordinate in base a questo ordine.

• display_size stringa

  Una classe di dimensioni che rappresenta la larghezza dell'opzione nell'UI. Ad esempio, se vuoi mostrare un'opzione "Minimo" e un'opzione "Massimo" una accanto all'altra, puoi impostare le dimensioni di visualizzazione di ciascuna su half.

  Valori consentiti: normal (valore predefinito), half, third

Eventi

Gli eventi possono essere attivati dal grafico (in genere in risposta all'interazione dell'utente) e possono aggiornare le proprietà della visualizzazione o della query.

Possono essere attivati chiamando la funzione trigger sull'oggetto di visualizzazione. Il primo parametro è sempre il nome dell'evento e il secondo parametro è un array di argomenti.

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

Eventi disponibili

• updateConfig

  Aggiorna le impostazioni di configurazione correnti del grafico.

  Argomento: un oggetto contenente le chiavi di configurazione da aggiornare. Le chiavi non specificate non vengono modificate.

  Esempio:

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

• limit

  Aggiorna il limite della query sottostante:

  Argomento: un numero intero che rappresenta un nuovo limite per la query.

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

• filter

  Aggiorna il valore di un filtro nella query sottostante:

  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

  Contrassegna la visualizzazione come in caricamento. Nella maggior parte dei casi non è necessario, ma se la visualizzazione carica un oggetto da una località remota o esegue un calcolo lungo, puoi utilizzare questa opzione per continuare a visualizzare l'indicatore di caricamento.

  Verrà visualizzato il caricamento finché non viene attivato loadingEnd.

• loadingEnd

  Contrassegna la visualizzazione come non più in caricamento.

• printSize (Looker 26.0+)

  Consente alle visualizzazioni di sfruttare l'opzione "Espandi le tabelle per mostrare tutte le righe" durante il rendering delle dashboard in PDF. L'utilizzo di questo evento consente all'applicazione di conoscere l'altezza dei contenuti sottoposti a rendering e di espandere il riquadro della dashboard in modo appropriato in modo che tutte le informazioni siano visibili per la stampa.

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

• registerOptions (Looker 5.24+)

  Consente alle visualizzazioni di registrare opzioni aggiuntive dopo la registrazione della visualizzazione:

    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
      ...
    }
  });