Créer des extensions de tuiles

À partir de Looker 24.0, il est possible de développer des extensions pour qu'elles s'exécutent dans une vignette de tableau de bord. Les extensions qui peuvent être exécutées en tant que vignette ou visualisation peuvent être ajoutées lorsque le tableau de bord est en mode édition ou enregistrées dans un tableau de bord en tant que visualisation à partir d'une exploration. Les extensions peuvent également être configurées en tant que tuiles dans les tableaux de bord LookML.

Voici des exemples d'extensions pouvant être utilisées comme vignettes de tableau de bord :

Utiliser le SDK d'extension Looker avec des extensions de tuiles

Les extensions de tuiles nécessitent que le paramètre mount_points soit défini dans le fichier manifeste du projet LookML pour que les extensions soient chargées en tant que tuiles dans un tableau de bord. Il existe deux types de mount_points liés aux extensions de tuiles :

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }
  • dashboard_vis : lorsqu'elle est activée, l'extension s'affiche dans les options de visualisation d'une exploration, où elle peut être sélectionnée comme visualisation et enregistrée en tant que vignette de tableau de bord. Lorsque le tableau de bord est exécuté, il exécute la requête associée au bloc et met les données à la disposition de l'extension. Ce mode de fonctionnement est semblable à celui des visualisations personnalisées. La principale différence entre une visualisation personnalisée et une extension exécutée dans une vignette de tableau de bord pour laquelle dashboard_vis est activé est que l'extension peut effectuer des appels à l'API Looker.
  • dashboard_tile : lorsque cette option est activée, l'extension s'affiche dans le panneau Extensions qui s'affiche lorsqu'un utilisateur modifie un tableau de bord et sélectionne l'option Extensions après avoir cliqué sur le bouton Ajouter. Ce type d'extension est responsable de la récupération de ses propres données, au lieu de laisser la requête de tuile fournir automatiquement les données à l'extension.

Un point de montage supplémentaire, standalone, permet à l'extension d'apparaître dans la section Applications du menu principal de Looker. Il est possible qu'une extension comporte plusieurs points de montage. Lors de l'exécution, l'extension est informée de la façon dont elle est montée et peut ajuster son comportement en conséquence. Par exemple, les extensions standalone peuvent avoir besoin de définir leur propre hauteur, contrairement aux extensions de tuiles.

API supplémentaires pour l'extension de tuiles

Les extensions de tuiles fournissent des API et des données supplémentaires au moment de l'exécution. Ils sont obtenus à partir du contexte de l'extension :

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)
  • tileSDK : fournit des fonctions spécifiques aux blocs pour permettre à l'extension d'interagir avec l'hôte du tableau de bord Looker. Par exemple, pour permettre à l'extension d'afficher et d'effacer les messages d'erreur.
  • tileHostData : fournit des données de carte à l'extension. Les données sont automatiquement mises à jour en fonction des interactions avec le tableau de bord d'hébergement. Par exemple, l'indicateur isDashboardEditing.
  • visualizationSDK : fournit des fonctions spécifiques à la visualisation pour permettre à l'extension d'interagir avec l'hôte du tableau de bord Looker. Par exemple, la fonction updateRowLimit.
  • visualizationData : fournit des données de visualisation à l'extension. Les données sont automatiquement mises à jour en fonction des interactions avec le tableau de bord d'hébergement. Ces données sont semblables à celles fournies aux visualisations personnalisées.

Créer des extensions réactives

Les iFrames dans lesquels les extensions s'exécutent sont automatiquement redimensionnés lorsque la fenêtre hôte Looker parente est redimensionnée. Cela se reflète automatiquement dans la fenêtre de contenu de l'iFrame. Le composant iframe ne comporte aucune marge intérieure ni extérieure. C'est donc à l'extension de fournir sa propre marge intérieure et extérieure pour qu'elle soit cohérente avec l'application Looker. Pour les extensions autonomes, il incombe à l'extension de contrôler sa hauteur. Pour les extensions qui s'exécutent dans des vignettes de tableau de bord ou des visualisations Explorer, la hauteur de la fenêtre de contenu de l'iframe est automatiquement définie sur la hauteur disponible dans l'iframe.

Remarques sur le rendu

Il est important de noter que les extensions de tuiles seront affichées lorsqu'un tableau de bord est téléchargé au format PDF ou image. Le moteur de rendu s'attend à ce que le bloc l'informe lorsque le rendu est terminé. Si vous ne le faites pas, le moteur de rendu cessera de répondre. Voici un exemple de notification au moteur de rendu indiquant que le bloc a été rendu.

  const { extensionSDK } = useContext(ExtensionContext40)

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

Les animations doivent également être désactivées lors du rendu. Voici un exemple où les configurations d'animation sont désactivées lors du rendu :

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

Fonctions et propriétés du SDK Tile

Le SDK de blocs fournit des fonctions qui permettent à une extension de bloc d'interagir avec son tableau de bord hôte.

Le tableau suivant présente les fonctions et propriétés disponibles :

Fonction ou propriété Description
tileHostData (propriété) Données de l'hôte spécifiques à l'extension de tuile. Pour en savoir plus, consultez la section Données du SDK Tile.
addError Lorsqu'il est appelé, le tableau de bord ou Explore affiche un message d'erreur sous la visualisation.
clearError Lorsqu'il est appelé, le tableau de bord ou l'exploration masquent tout message d'erreur affiché sous la visualisation.
openDrillMenu Pour les extensions de visualisation, cet appel ouvre un menu d'analyse. Cet appel est ignoré si l'extension n'est pas une visualisation d'extension de carte.
runDashboard Exécute le tableau de bord actuel. Cet appel est ignoré par une extension de visualisation de tuiles exécutée dans une exploration.
stopDashboard Arrête un tableau de bord en cours d'exécution. Cet appel est ignoré par une extension de visualisation de tuiles exécutée dans une exploration.
updateFilters Met à jour les filtres dans le tableau de bord ou l'exploration actuels.
openScheduleDialog Ouvre la boîte de dialogue de planification. Cet appel est ignoré lors de l'exécution dans une exploration.
toggleCrossFilter Active/Désactive les filtres croisés. Cet appel est ignoré lors de l'exécution dans une exploration.

Données du SDK Tile

Le tableau suivant présente les propriétés de données du SDK de tuiles disponibles :

Propriété Description
isExploring Lorsque la valeur est "true", cela indique que le bloc est configuré en tant que visualisation dans une exploration.
dashboardId ID du tableau de bord du bloc en cours d'affichage. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.
elementId ID de l'élément de la tuile en cours de rendu. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.
queryId ID de la requête de la vignette affichée, si elle est associée à une visualisation. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.

queryId correspond à l'ID de la requête créée lorsque la visualisation est intégrée à l'outil Explorer de Looker. Il ne contient aucun filtre ni filtrage croisé à appliquer au tableau de bord. Pour refléter les données affichées dans QueryResponse, vous devrez appliquer des filtres et des filtres croisés, puis générer une nouvelle requête. Par conséquent, il peut y avoir plus de propriétés utiles que queryId. Consultez filteredQuery pour obtenir un objet de requête avec des filtres appliqués.
querySlug Le slug de la requête de la vignette en cours de rendu, si elle est associée à une visualisation. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.

querySlug est un slug de requête créé lorsque la visualisation est intégrée à l'exploration Looker. Il ne contient aucun filtre ni filtrage croisé appliqué au tableau de bord. Pour refléter les données affichées dans QueryResponse, vous devrez appliquer des filtres et des filtres croisés, puis générer une nouvelle requête. Par conséquent, il peut y avoir plus de propriétés utiles que querySlug. Consultez filteredQuery pour obtenir un objet de requête avec des filtres appliqués.
dashboardFilters Filtres appliqués au tableau de bord. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.
dashboardRunState Indique si le tableau de bord est en cours d'exécution. Si la vignette est configurée en tant qu'exploration, l'état est UNKNOWN.

Pour des raisons de performances du tableau de bord, l'état d'exécution peut ne jamais être affiché comme "en cours d'exécution". Cela se produit généralement s'il n'y a pas d'autres tuiles associées à une requête, y compris celle à laquelle l'extension est associée. Si l'extension doit savoir avec certitude qu'un tableau de bord a été exécuté, la méthode fiable consiste à détecter les différences dans lastRunStartTime.
isDashboardEditing Si la valeur est "true", le tableau de bord est en cours de modification. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.
isDashboardCrossFilteringEnabled Si la valeur est "true", le filtrage croisé est activé dans le tableau de bord. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.
filteredQuery Objet de requête correspondant à l'ID de requête associé à l'élément de tableau de bord sous-jacent qui applique les filtres et les modifications du fuseau horaire effectués au niveau du tableau de bord.
lastRunSourceElementId ID de l'élément d'extension de vignette qui a déclenché la dernière exécution du tableau de bord. L'ID sera indéfini si l'exécution du tableau de bord a été déclenchée par le bouton Exécuter ou l'actualisation automatique du tableau de bord, ou si l'exécution a été déclenchée à l'aide du SDK d'intégration. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.

Notez que lastRunSourceElementId peut être identique à l'ID d'élément de l'instance d'extension actuelle. Par exemple, si l'extension déclenche l'exécution d'un tableau de bord, elle recevra une notification au début et à la fin de l'exécution.
lastRunStartTime Indique l'heure de début de la dernière exécution du tableau de bord. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée.

Notez que les heures de début et de fin indiquées ne doivent pas être utilisées pour capturer les métriques de performances.
lastRunEndTime Indique l'heure de fin de la dernière exécution du tableau de bord. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée. Si le bloc est en cours d'exécution, cette propriété ne sera pas renseignée.

Notez que les heures de début et de fin indiquées ne doivent pas être utilisées pour capturer les métriques de performances.
lastRunSuccess Indique si la dernière exécution du tableau de bord a réussi ou non. Si le bloc est configuré en tant qu'exploration, cette propriété ne sera pas renseignée. Si le bloc est en cours d'exécution, cette propriété ne sera pas renseignée.

Fonctions et propriétés du SDK de visualisation

Le tableau suivant présente les fonctions et propriétés du SDK de visualisation disponibles :

Fonction ou propriété Description
visualizationData (propriété) Visualisation (combinaison des données visConfig et queryResponse).
visConfig (propriété) Données de configuration de la visualisation :

  • Configurations des mesures
  • Configurations des dimensions
  • Calculs de tables
  • Configurations de tableaux croisés dynamiques
  • Configurations de visualisation

Ils permettent de personnaliser l'apparence d'une visualisation dans une exploration.
queryResponse (propriété) Données de réponse de la requête
configureVisualization Définit la configuration par défaut d'une visualisation d'extension. La configuration sera affichée dans l'éditeur de visualisation Explorer. Cette méthode ne doit être appelée qu'une seule fois.
setVisConfig Met à jour la configuration de la visualisation.
updateRowLimit Met à jour la limite de lignes de la requête.

Données du SDK Visualization

Le SDK de visualisation se compose des éléments suivants :

  • Données de configuration de la visualisation
  • Données de réponse aux requêtes

Données de configuration de la visualisation

Propriété Description
queryFieldMeasures Informations sur la mesure
queryFieldDimensions Informations sur la dimension
queryFieldTableCalculations Informations sur les calculs de tables
queryFieldPivots Informations sur le tableau croisé dynamique
visConfig Données de configuration visuelle. Elle doit être fusionnée avec la configuration par défaut et appliquée à la visualisation affichée par l'extension. 
export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Données de réponse aux requêtes

Propriété Description
data Tableau de données de ligne
fieldMeasures Informations sur les mesures sur le terrain.
fieldDimensions Informations sur la dimension du champ.
fieldTableCalculations Informations sur les calculs de table des champs.
fieldPivots Informations sur le tableau croisé dynamique du champ.
fieldMeasureLike Tableau concaténé d'informations sur les mesures de champ et les calculs de tables qui se comportent comme des mesures.
fieldDimensionLike Tableau concaténé d'informations sur les dimensions de champ et les calculs de table qui se comportent comme des dimensions.

Utiliser le SDK d'intégration

L'utilisation du SDK d'intégration dans une extension de tuile n'est pas recommandée pour les raisons suivantes :

  • Il est possible que l'extension finisse par afficher un tableau de bord dans lequel elle est une vignette. Le framework d'extension n'a aucun moyen de le détecter. Par conséquent, le navigateur peut planter.
  • Le rendu PDF du contenu intégré dans une extension de carte ne fonctionne pas.