Como criar extensões de blocos

A partir do Looker 24.0, as extensões podem ser desenvolvidas para serem executadas em um bloco nos painéis. As extensões que podem ser executadas como um bloco ou visualização podem ser adicionadas enquanto o painel está no modo de edição ou salvas em um painel como uma visualização de uma análise. As extensões também podem ser configuradas como blocos em painéis do LookML.

Exemplos de extensões que podem ser usadas como blocos de painel:

Como usar o SDK de extensão do Looker com extensões de blocos

As extensões de blocos exigem que o mount_points parâmetro seja definido no arquivo de manifesto do projeto do LookML para que as extensões sejam carregadas como blocos em um painel. Há dois tipos de mount_points relacionados a extensões de blocos:

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }
  • dashboard_vis — quando ativada, a extensão aparece nas opções de visualização de uma análise, em que a extensão pode ser selecionada como uma visualização e salva como um bloco de painel. Quando o painel é executado, ele executa a consulta associada ao bloco e disponibiliza os dados para a extensão. Isso é semelhante ao funcionamento das visualizações personalizadas. A principal diferença entre uma visualização personalizada e uma extensão em execução em um bloco de painel que tem dashboard_vis ativado é que a extensão pode fazer chamadas de API do Looker.
  • dashboard_tile — quando ativada, a extensão aparece no painel Extensões mostrado quando um usuário está editando um painel e seleciona a opção Extensões depois de clicar no botão Adicionar. Esse tipo de extensão é responsável por recuperar os próprios dados, em vez de ter a consulta de bloco fornecendo automaticamente os dados da extensão.

Um ponto de montagem adicional, standalone, faz com que a extensão apareça na seção Aplicativos do menu principal do Looker. É possível que uma extensão tenha vários pontos de montagem definidos. No momento da execução, a extensão é notificada sobre como ela é montada e pode ajustar o comportamento de acordo. Por exemplo, standalone extensões podem precisar definir a própria altura, enquanto as extensões de blocos não.

APIs adicionais de extensão de blocos

As extensões de blocos são fornecidas com APIs e dados adicionais no momento da execução. Eles são obtidos no contexto da extensão:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)
  • tileSDK: fornece funções específicas de blocos para permitir que a extensão interaja com o host do painel do Looker. Por exemplo, para permitir que a extensão mostre e limpe mensagens de erro.
  • tileHostData: fornece dados de blocos para a extensão. Os dados são atualizados automaticamente com base nas interações com o painel de hospedagem. Um exemplo é o indicador isDashboardEditing.
  • visualizationSDK: fornece funções específicas de visualização para permitir que a extensão interaja com o host do painel do Looker. Um exemplo é a função updateRowLimit.
  • visualizationData: fornece dados de visualização para a extensão. Os dados são atualizados automaticamente com base nas interações com o painel de hospedagem. Os dados são semelhantes aos fornecidos para visualizações personalizadas.

Como criar extensões reativas

Os iframes em que as extensões são executadas são redimensionados automaticamente conforme a janela do host do Looker pai é redimensionada. Isso é refletido automaticamente na janela de conteúdo do iframe. O componente iframe não tem preenchimento ou margem. Portanto, cabe à extensão fornecer o próprio preenchimento e margem para que ele pareça consistente com o aplicativo Looker. Para extensões independentes, cabe à extensão controlar a altura. Para extensões executadas em blocos de painel ou visualizações de análise, a janela de conteúdo do iframe será definida automaticamente para a altura disponibilizada pelo iframe.

Considerações sobre a renderização

É importante observar que as extensões de blocos serão renderizadas quando um painel for baixado como um PDF ou uma imagem. O renderizador espera que o bloco o notifique quando a renderização for concluída. Se isso não for feito, o renderizador vai parar de responder. Confira a seguir um exemplo de como notificar o renderizador de que o bloco foi renderizado.

  const { extensionSDK } = useContext(ExtensionContext40)

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

As animações também precisam ser desativadas durante a renderização. Confira a seguir um exemplo em que as configurações de animação são desativadas durante a renderização:

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

Funções e propriedades do SDK de blocos

O SDK de blocos fornece funções que permitem que uma extensão de bloco interaja com o painel de hospedagem.

As funções e propriedades disponíveis são mostradas na tabela a seguir:

Função ou propriedade Descrição
tileHostData (propriedade) Dados do host específicos da extensão de bloco. Consulte a seção Dados do SDK de blocos para mais detalhes.
addError Quando chamada, o painel ou a análise mostra uma mensagem de erro abaixo da visualização.
clearError Quando chamada, o painel ou a análise oculta qualquer mensagem de erro mostrada abaixo da visualização.
openDrillMenu Para extensões de visualização, essa chamada abre um menu de detalhamento. Essa chamada é ignorada se a extensão não for uma visualização de extensão de bloco.
runDashboard Executa o painel atual. Essa chamada é ignorada por uma extensão de visualização de blocos em execução em uma análise.
stopDashboard Interrompe um painel de corridas. Essa chamada é ignorada por uma extensão de visualização de blocos em execução em uma análise.
updateFilters Atualiza os filtros no painel ou na análise atual.
openScheduleDialog Abre a caixa de diálogo de programação. Essa chamada é ignorada quando executada em uma análise.
toggleCrossFilter Alterna os filtros cruzados. Essa chamada é ignorada quando executada em uma análise.

Dados do SDK de blocos

As propriedades de dados do SDK de blocos disponíveis são mostradas na tabela a seguir:

Propriedade Descrição
isExploring Quando verdadeiro, indica que o bloco está sendo configurado como uma visualização em uma análise.
dashboardId O ID do painel do bloco que está sendo renderizado. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.
elementId O ID do elemento do bloco que está sendo renderizado. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.
queryId O ID da consulta do bloco que está sendo renderizado, se estiver associado a uma visualização. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.

O queryId é o ID da consulta criada quando a visualização é integrada à análise do Looker. Ele não contém filtros ou filtros cruzados a serem aplicados ao painel. Para refletir os dados mostrados no QueryResponse, os filtros e filtros cruzados precisam ser aplicados e uma nova consulta gerada. Como resultado, pode haver propriedades mais úteis do que queryId. Consulte filteredQuery para um objeto de consulta com filtros aplicados.
querySlug O slug de consulta do bloco que está sendo renderizado, se estiver associado a uma visualização. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.

O querySlug é um slug da consulta criada quando a visualização é integrada à análise do Looker. Ele não contém filtros ou filtros cruzados aplicados ao painel. Para refletir os dados mostrados no QueryResponse, os filtros e filtros cruzados precisam ser aplicados e uma nova consulta gerada. Como resultado, pode haver propriedades mais úteis do que querySlug. Consulte filteredQuery para um objeto de consulta com filtros aplicados.
dashboardFilters Os filtros que estão sendo aplicados ao painel. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.
dashboardRunState Indica se o painel está em execução. Se o bloco estiver sendo configurado como uma análise, o estado será UNKNOWN.

Por motivos de desempenho do painel, o estado de execução nunca poderá ser mostrado como em execução. Isso geralmente acontece se não houver outros blocos associados a uma consulta, incluindo aquele ao qual a extensão está associada. Se a extensão precisar saber com certeza que um painel foi executado, detectar diferenças no lastRunStartTime é a maneira confiável.
isDashboardEditing Quando verdadeiro, o painel está sendo editado. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.
isDashboardCrossFilteringEnabled Quando verdadeiro, o filtro cruzado está ativado no painel. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.
filteredQuery Um objeto de consulta que corresponde ao ID da consulta associada ao elemento do painel subjacente que aplica todos os filtros do painel e as mudanças de fuso horário feitas no nível do painel.
lastRunSourceElementId O ID do elemento de extensão de bloco que acionou a última execução do painel. O ID será indefinido se a execução do painel tiver sido acionada pelo botão Executar ou pela atualização automática do painel, ou se a execução tiver sido acionada usando o SDK incorporado. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.

O lastRunSourceElementId pode ser o mesmo que o ID do elemento da instância de extensão atual. Por exemplo, se a extensão acionar uma execução do painel, ela será notificada quando a execução do painel começar e terminar.
lastRunStartTime Indica a última hora de início da execução do painel. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida.

Observação: os horários de início e término informados não devem ser usados para capturar métricas de desempenho.
lastRunEndTime Indica a última hora de término da execução do painel. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida. Se o bloco estiver em execução, essa propriedade não será preenchida.

Os horários de início e término informados não devem ser usados para capturar métricas de desempenho.
lastRunSuccess Indica se a última execução do painel foi bem-sucedida ou não. Se o bloco estiver sendo configurado como uma análise, essa propriedade não será preenchida. Se o bloco estiver em execução, essa propriedade não será preenchida.

Funções e propriedades do SDK de visualização

As funções e propriedades do SDK de visualização disponíveis são mostradas na tabela a seguir:

Função ou propriedade Descrição
visualizationData (propriedade) Visualização (combinação de dados visConfig e queryResponse).
visConfig (propriedade) Dados de configuração de visualização:

  • Configurações de métricas
  • Configurações de dimensões
  • Cálculos de tabela
  • Configurações de tabela dinâmica
  • Configurações de visualização

Eles são usados para personalizar a aparência de uma visualização em uma análise.
queryResponse (propriedade) Dados de resposta da consulta
configureVisualization Define a configuração padrão para uma visualização de extensão. A configuração será renderizada no editor de visualização da análise. Isso só precisa ser chamado uma vez.
setVisConfig Atualiza a configuração de visualização.
updateRowLimit Atualiza o limite de linhas da consulta.

Dados do SDK de visualização

O SDK de visualização consiste no seguinte:

  • Dados de configuração de visualização
  • Dados de resposta da consulta

Dados de configuração de visualização

Propriedade Descrição
queryFieldMeasures Informações de métricas
queryFieldDimensions Informações de dimensões
queryFieldTableCalculations Informações de cálculo de tabela
queryFieldPivots Informações de tabela dinâmica
visConfig Dados de configuração visual. Isso precisa ser mesclado com a configuração padrão e aplicado à visualização renderizada pela extensão. 
export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

Dados de resposta da consulta

Propriedade Descrição
data Matriz de dados de linha
fieldMeasures Informações de métricas de campo.
fieldDimensions Informações de dimensões de campo.
fieldTableCalculations Informações de cálculos de tabela de campo.
fieldPivots Informações de tabela dinâmica de campo.
fieldMeasureLike Uma matriz concatenada de informações de métricas de campo e cálculos de tabela que se comportam como métricas.
fieldDimensionLike Uma matriz concatenada de informações de dimensões de campo e cálculos de tabela que se comportam como dimensões.

Como usar o SDK incorporado

Não é recomendável usar o SDK incorporado em uma extensão de bloco pelos seguintes motivos:

  • É possível que a extensão acabe renderizando um painel em que ela é um bloco. A estrutura de extensão não tem como detectar isso e, como resultado, o navegador pode falhar.
  • A renderização em PDF de conteúdo incorporado em uma extensão de bloco não funciona.