Documentation de référence sur l'API de visualisation personnalisée 2.0

Un appel à la fonction looker.plugins.visualizations.add est le point d'entrée de l'API Visualization. Cette fonction accepte un objet de visualisation qui définit entièrement votre visualisation personnalisée.

Voici un exemple de visualisation :

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

Environnement

Comme l'API Visualization est en JavaScript simple, vous pouvez utiliser n'importe quelle bibliothèque JavaScript pour visualiser vos données.

Votre code JavaScript s'exécutera dans un iframe en bac à sable, distinct de votre instance Looker. Les auteurs de visualisations personnalisées sont toutefois responsables de la sécurité du code qu'ils écrivent.

Comme pour tout développement Web, la prise en charge de différents navigateurs Web (Chrome, Edge, Firefox) peut parfois poser problème. L'API Visualization fonctionne sur tous les navigateurs compatibles avec Looker, mais il vous appartient de vous assurer que votre code personnalisé est compatible avec les navigateurs. Par exemple, les utilisations d'ES6 telles que let ou ()=> fonctionneront dans la plupart des navigateurs, mais peuvent entraîner des échecs dans IE11 ou lors du rendu de fichiers PDF à l'aide de PhantomJS.

Installation

Vous installez des visualisations personnalisées en définissant un fichier manifeste à l'aide du formulaire Admin > Platform > Visualizations (Administration > Plate-forme > Visualisations). Un fichier manifeste se compose d'un ID de chaîne unique, d'un libellé lisible par l'humain, de l'URI de votre visualisation et de liens vers toutes les dépendances dont vous avez besoin (par exemple, d3, jQuery, underscore).

Les visualisations personnalisées doivent être diffusées en tant que contenu HTTPS en dehors de Looker. Si vous effectuez une migration depuis la première version de l'API de visualisation personnalisée, vous pouvez avoir des fichiers dans votre répertoire looker/plugins/visualizations. Cet emplacement reste accessible et un chemin relatif à votre visualisation peut être fourni, mais nous vous recommandons de migrer votre contenu vers un autre emplacement. Étant donné que le répertoire /plugins ne se trouve pas dans le système de fichiers partagé, les environnements en cluster n'auront pas accès à vos fichiers de visualisation sur tous les nœuds.

Objet de visualisation

L'objet de visualisation utilise les propriétés obligatoires, facultatives et ajoutées suivantes.

Propriétés obligatoires

• create fonction

  Cette fonction est appelée une seule fois, lorsque votre visualisation est dessinée pour la première fois sur la page. Elle est censée configurer tout ce que vous souhaitez que votre visualisation ait toujours à disposition. Vous pouvez charger une bibliothèque ou créer un ensemble d'éléments et de commandes que vous utiliserez ultérieurement.

  En savoir plus sur la fonction create →

• updateAsync / update fonction

  Cette fonction est appelée chaque fois que l'état de votre visualisation doit changer. Elle est toujours appelée après create et peut être appelée plusieurs fois. Elle doit donc être aussi rapide que possible.

  Cette fonction peut être appelée pour de nombreuses raisons, mais généralement lorsque la requête à visualiser a été modifiée, qu'une option de configuration a été modifiée ou que la visualisation a été redimensionnée.

  Cette fonction comporte une version synchrone et une version asynchrone :emdash; vous n'aurez besoin d'en spécifier qu'une seule. (Il est impossible de définir les deux.) La méthode asynchrone est plus fiable pour le rendu PDF en raison de la nature des iframes.

  En savoir plus sur ces fonctions update →

Propriétés facultatives

• options objet

  Objet qui détaille les options que les utilisateurs peuvent définir sur votre visualisation.

  En savoir plus sur l'exposition d'une interface utilisateur de configuration →

• destroy fonction Non encore implémentée dans l'API V2

  Fonction appelée juste avant la suppression de la visualisation de la page. Utilisez cette fonction pour nettoyer les écouteurs d'événements ou d'autres états. Elle ne sera peut-être jamais appelée si, par exemple, l'utilisateur ferme la fenêtre.

Propriétés ajoutées

Looker ajoute automatiquement les propriétés suivantes à votre objet une fois la visualisation transmise à looker.plugins.visualizations.add. Vous pouvez y faire référence à l'aide de this dans le contexte des fonctions create, update, updateAsync et destroy.

• addError fonction

  Fonction que le code de votre visualisation peut appeler pour indiquer à l'UI d'afficher un message d'erreur au lieu de la visualisation. Elle accepte un objet error.

  Une fois une erreur ajoutée, elle reste visible jusqu'à ce que clearErrors soit appelé.

  Exemple :

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

• clearErrors fonction

  Fonction que le code de votre visualisation peut appeler pour effacer les erreurs ajoutées à l'aide de addError.

  Exemple :

  this.clearErrors();
  

• trigger fonction

  Fonction qui peut être appelée pour déclencher un événement en dehors de la visualisation.

  En savoir plus sur les événements →

  Exemple :

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

Fonction create

La fonction create reçoit deux paramètres : element et config.

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

Paramètres

• element DOMElement

  Élément DOM qui représente un conteneur dans lequel afficher votre visualisation.

• config objet

  Objet qui représente les valeurs de toutes les options de configuration options définies par l'utilisateur pour ce graphique.

  Exemple : {my_configuration_option: "User Value"}

Fonctions updateAsync et update

La méthode préférée pour mettre à jour votre visualisation est la méthode updateAsync. Cette méthode permet à votre visualisation d'effectuer une action asynchrone, comme le chargement d'un fichier ou l'envoi d'une requête Web.

Cette version de la fonction comporte un paramètre supplémentaire, qui est un rappel à appeler une fois le rendu terminé :

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

Avertir Looker lorsque le rendu de la visualisation est terminé permet à Looker d'optimiser le rendu PDF et de s'assurer que les images des visualisations sont correctement capturées.

Certaines visualisations plus anciennes utilisent la fonction update. Cette fonction fonctionne toujours, mais elle n'est pas la méthode préférée, car son utilisation signifie que Looker ne sera pas averti lorsqu'une visualisation est entièrement rendue. La fonction update reçoit cinq paramètres :

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

Paramètres

• data tableau

  Tableau de lignes représentant les données actuelles de la requête. La valeur peut être null.

  Chaque ligne est un objet avec les clés qui représentent les noms de champs et la valeur qui représente un objet "cellule". Voici des informations sur la gestion de l'objet de cellule.

• element DOMElement

  Élément DOM qui représente un conteneur dans lequel afficher votre visualisation.

• config objet

  Objet qui représente les valeurs de toutes les options de configuration options définies par l'utilisateur pour ce graphique.

  Exemple : {my_configuration_option: "User Value"}

• queryResponse objet

  Objet qui représente les métadonnées de la requête actuelle, telles que les métadonnées sur les champs. La valeur peut être null.

• details objet

  Détails sur le contexte de rendu actuel. Contient des informations sur la raison pour laquelle le graphique est rendu et sur ce qui a changé. En règle générale, ces informations ne sont utilisées que dans les cas avancés.

  En ce qui concerne les filtres croisés dans les tableaux de bord Looker qui utilisent la nouvelle expérience de tableau de bord, les attributs autorisés incluent crossfilterEnabled et crossfilters.

  L'attribut print peut être utilisé conjointement avec la fonction done pour améliorer le rendu PDF des visualisations personnalisées, en particulier celles qui incluent une animation. Exemple :

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

• done fonction

  Rappel indiquant que le rendu de la visualisation est terminé. Il est particulièrement important d'appeler cette fonction si votre visualisation doit effectuer des appels asynchrones ou doit être rendue au format PDF.

Rendu des données

Looker dispose d'un ensemble complet d'outils de mise en forme des données dans LookML, qui peuvent être utilisés pour personnaliser l'apparence et le comportement des points de données. Ces outils incluent des paramètres LookML au niveau du champ, tels que des formats de valeurs personnalisés, du code HTML, des liens d'exploration et des actions sur les données.

Les cellules ont une propriété value, qui est la seule propriété qui existe dans tous les cas. Cette propriété est un type JavaScript qui correspond au type de champ auquel appartient la cellule. Toutefois, il n'est pas sûr d'insérer une propriété value directement dans du code HTML ou SVG, car aucune échappement HTML n'a été effectué, et certaines valeurs de champ sont des objets ou des tableaux JavaScript complexes qui seront rendus de manière indésirable ou déroutante.

Pour s'assurer que toutes les visualisations rendent ces éléments de manière cohérente et sécurisée, il existe un certain nombre de fonctions utilitaires permettant de transformer les métadonnées de cellule transmises à votre graphique dans data en différentes représentations à des fins différentes. Les métadonnées de cellule peuvent compresser ou omettre certains champs dans certains cas, et ces fonctions d'assistance vous permettront de fournir une expérience cohérente.

Ces fonctions d'assistance sont toutes disponibles sur l'objet global LookerCharts.Utils.

• LookerCharts.Utils.textForCell(cell)

  Cette fonction accepte une cellule et renvoie une représentation sous forme de chaîne adaptée à l'affichage. Il s'agira toujours d'une chaîne. Cette fonction ne renvoie jamais null ni aucun autre type.

• LookerCharts.Utils.htmlForCell(cell)

  Cette fonction accepte une cellule et renvoie une chaîne contenant du code HTML. Il s'agira toujours d'une chaîne. Cette fonction ne renvoie jamais null ni aucun autre type.

  La sortie de cette fonction est correctement échappée et peut être insérée directement dans le code HTML de votre élément. Le code HTML de sortie affichera également correctement le menu d'exploration lorsque cela est approprié pour les données.

• LookerCharts.Utils.filterableValueForCell(cell)

  Cette fonction accepte une cellule et renvoie une chaîne de syntaxe de filtre avancé Looker qui correspondrait à la valeur de cette cellule.

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

  Cette fonction accepte une ligne, un tableau croisé dynamique ou un événement, et permet de vérifier si le filtrage croisé est activé pour une visualisation. L'exemple suivant montre comment ajouter un écouteur d'événements à un élément qui vérifie si le filtrage croisé est activé lorsque l'événement se produit :

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

  Cette fonction accepte une ligne ou un tableau croisé dynamique et permet de vérifier si cette ligne ou ce tableau croisé dynamique est sélectionné dans une visualisation personnalisée. La fonction renvoie une énumération pour CrossfilterSelection {NONE, SELECTED, UNSELECTED} de 0 si NONE, 1 si SELECTED et 2 si UNSELECTED.

  L'exemple suivant applique conditionnellement une couleur de remplissage à une ligne si elle est filtrée croisée et applique des couleurs par défaut si le filtrage croisé n'est pas activé pour cette ligne :

  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)

  La sortie de htmlForCell affiche automatiquement le menu d'exploration si nécessaire, mais cela peut ne pas être approprié pour certains types de rendu. (Par exemple, SVG ne peut pas afficher de code HTML, mais vous pouvez capturer un événement de clic pour commencer une exploration.)

  L'objet options comporte les paramètres suivants :

  • links Obligatoire tableau

    Tableau des objets renvoyés par la propriété links d'une cellule. Si vous souhaitez afficher des liens pour plusieurs cellules à la fois, vous pouvez d'abord concaténer ces tableaux. Pour les liens personnalisés, fournissez un tableau d'objets au format suivant :

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

  • event Événement DOM HTML

    Événement de clic (ou autre) qui a provoqué l'événement d'exploration. Looker l'utilisera pour déterminer où placer le menu d'exploration. Si vous n'en avez pas, essayez de transmettre un objet avec les coordonnées pageX et pageY.

  Exemple :

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

Présentation de l'interface utilisateur de configuration

Le paramètre options est un objet dont les clés sont un identifiant arbitraire pour un nom d'option, et la valeur est un objet décrivant des informations sur l'option.

Exemple :

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

Paramètres de l'objet d'option

L'objet option comporte les paramètres de base, les propriétés spécifiques à l'affichage et les options d'organisation suivants.

Paramètres de base

• type chaîne

  Type de données de l'option.

  Valeurs autorisées : string (par défaut), number, boolean, array

• label chaîne

  Libellé lisible par l'humain de l'option qui sera affiché à l'utilisateur.

• default

  Valeur par défaut de l'option. Si elle n'est pas spécifiée, la valeur de l'option est null. Il doit s'agir d'une valeur du même type que type.

• display chaîne

  Certaines valeurs type peuvent être présentées de différentes manières dans l'UI.

  • lorsque type est string :

    Valeurs autorisées : text (par défaut), select, radio

  • lorsque type est number :

    Valeurs autorisées : number (par défaut), range

  • lorsque type est array :

    Valeurs autorisées : text (par défaut), color, colors

• placeholder chaîne

  Pour les valeurs display qui le prennent en charge, une valeur ou une explication d'exemple pour donner à l'utilisateur une idée de ce qu'il doit saisir.

Propriétés spécifiques à l'affichage

• values tableau d'objets

  Lorsque display est radio ou select, un tableau contenant des libellés et des valeurs qui seront listés dans l'interface.

  Chaque élément du tableau doit être un objet avec une seule paire clé/valeur, qui représente le libellé et la valeur de l'option. Le libellé ne sera présenté que dans l'UI. Au moment du rendu, vous ne recevrez que la valeur.

  Exemple :

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

  Si display est radio, chaque option peut également recevoir une description :

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

• max number

  Lorsque display est range, le nombre maximal autorisé à être sélectionné par le curseur de plage.

• min number

  Lorsque display est range, le nombre minimal autorisé à être sélectionné par le curseur de plage.

• step number

  Lorsque display est range, la quantité que représente chaque graduation du curseur de plage.

Options d'organisation

• section chaîne

  Pour les graphiques comportant de nombreuses options, un libellé indiquant la section dans laquelle une option doit apparaître. L'UI regroupera les options en fonction de leurs valeurs section. S'il n'y a qu'une seule section, l'UI de la section ne s'affiche pas.

  Si vous utilisez section, elle doit être définie pour chaque option.

• order number

  Nombre représentant l'ordre des options pour la présentation dans l'UI. Si elle est spécifiée, les options sont triées selon cet ordre.

• display_size chaîne

  Classe de taille représentant la largeur de l'option dans l'UI. Par exemple, si vous souhaitez afficher une option "Minimum" et une option "Maximum" l'une à côté de l'autre, vous pouvez définir la taille d'affichage de chacune d'elles sur half.

  Valeurs autorisées : normal (par défaut), half, third

Événements

Les événements peuvent être déclenchés par le graphique (généralement en réponse à une interaction de l'utilisateur) et peuvent mettre à jour les propriétés de la visualisation ou de la requête.

Ils peuvent être déclenchés en appelant la fonction trigger sur l'objet de visualisation. Le premier paramètre est toujours le nom de l'événement et le second est un tableau d'arguments.

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

Événements disponibles

• updateConfig

  Mettez à jour les paramètres de configuration actuels du graphique.

  Argument : objet contenant les clés de configuration à mettre à jour. Les clés non spécifiées ne sont pas modifiées.

  Exemple :

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

• limit

  Mettez à jour la limite de la requête sous-jacente :

  Argument : entier représentant une nouvelle limite pour la requête.

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

• filter

  Mettez à jour la valeur d'un filtre sur la requête sous-jacente :

  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

  Marquez la visualisation comme étant en cours de chargement. La plupart du temps, cela n'est pas nécessaire, mais si votre visualisation charge un objet à partir d'un emplacement distant ou effectue un calcul long, vous pouvez l'utiliser pour continuer à afficher l'indicateur de chargement.

  Le chargement s'affiche jusqu'à ce que loadingEnd soit déclenché.

• loadingEnd

  Marquez la visualisation comme n'étant plus en cours de chargement.

• printSize (Looker 26.0 et versions ultérieures)

  Permet aux visualisations de profiter de l'option "Développer les tables pour afficher toutes les lignes" lors du rendu des tableaux de bord au format PDF. L'utilisation de cet événement permet à l'application de connaître la hauteur du contenu rendu et d'étendre la tuile du tableau de bord de manière appropriée afin que toutes les informations soient visibles pour l'impression.

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

• registerOptions (Looker 5.24 et versions ultérieures)

  Permet aux visualisations d'enregistrer des options supplémentaires une fois la visualisation enregistrée :

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