Esta página foi traduzida pela API Cloud Translation.

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 uma 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 detalhada. As extensões também podem ser configuradas como blocos nos painéis do LookML.

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

A extensão de visualização de bloco mostra como criar uma visualização personalizada usando a estrutura de extensão.
A extensão do SDK de bloco mostra os métodos de API disponíveis específicos para extensões de bloco.

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

As extensões de bloco exigem que o parâmetro mount_points 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 bloco:

  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 detalhada, em que pode ser selecionada como uma visualização e salva como um bloco do 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 executada em um bloco do painel com dashboard_vis ativado é que a extensão pode fazer chamadas da API Looker.
dashboard_tile: quando ativada, a extensão aparece no painel Extensões, que é exibido quando um usuário edita 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 dados automaticamente à 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. Uma extensão pode ter vários pontos de montagem definidos. Em tempo de execução, a extensão é notificada sobre como ela é montada e pode ajustar o comportamento de acordo. Por exemplo, as extensões standalone podem precisar definir a própria altura, enquanto as extensões de bloco não.

APIs adicionais de extensão de bloco

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

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)

tileSDK: fornece funções específicas do bloco 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 bloco 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 host principal do Looker é redimensionada. Isso é refletido automaticamente na janela de conteúdo do iframe. O componente iframe não tem padding nem margem. Portanto, cabe à extensão fornecer o próprio padding e margem para que ele pareça consistente com o aplicativo Looker. Para extensões independentes, é a extensão que controla a altura dela. Para extensões que são executadas em blocos do painel ou visualizações do recurso Detalhar, a janela de conteúdo do iframe será definida automaticamente como a altura disponibilizada pelo iframe.

Considerações sobre renderização

É importante observar que as extensões de bloco são renderizadas quando um painel é baixado como PDF ou imagem. O renderizador espera que o bloco 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 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 oferece 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)	Hospeda dados específicos da extensão de bloco. Consulte a seção Dados do SDK de blocos para mais detalhes.
`addError`	Quando chamado, o painel ou a Análise vai mostrar uma mensagem de erro abaixo da visualização.
`clearError`	Quando chamado, o painel ou a Análise vai ocultar 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 será 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 bloco em execução em uma Análise.
`stopDashboard`	Interrompe um painel em execução. Essa chamada é ignorada por uma extensão de visualização de bloco 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 detalhada.
`toggleCrossFilter`	Alterna o cruzamento de filtros. Essa chamada é ignorada quando executada em uma análise detalhada.

Dados do SDK de blocos

As propriedades de dados disponíveis do SDK de blocos 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 detalhada.
`dashboardId`	O ID do painel do bloco que está sendo renderizado. Se o bloco estiver sendo configurado como uma análise detalhada, 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 detalhada, essa propriedade não será preenchida.
`queryId`	O ID da consulta do bloco que está sendo renderizado, se ele estiver associado a uma visualização. Se o bloco estiver sendo configurado como uma análise detalhada, essa propriedade não será preenchida. O `queryId` é o ID da consulta criada quando a visualização é integrada ao Looker Explore. Ele não contém filtros ou filtros cruzados para serem aplicados ao painel. Para refletir os dados mostrados no `QueryResponse`, é necessário aplicar filtros e filtros cruzados e gerar uma nova consulta. Como resultado, pode haver mais propriedades úteis do que `queryId`. Consulte `filteredQuery` para um objeto de consulta com filtros aplicados.
`querySlug`	O slug 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 detalhada, essa propriedade não será preenchida. O `querySlug` é um slug da consulta criada quando a visualização é integrada ao Looker Explore. Ele não contém filtros ou filtros cruzados aplicados ao painel. Para refletir os dados mostrados no `QueryResponse`, é necessário aplicar filtros e filtros cruzados e gerar uma nova consulta. Como resultado, pode haver mais propriedades ú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 detalhada, 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 detalhada, o estado será `UNKNOWN`. Por motivos de performance do painel, o estado de execução pode nunca ser mostrado como "em execução". Isso geralmente acontece se não houver outros blocos associados a uma consulta, incluindo aquele a que 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 "true", o painel está sendo editado. Se o bloco estiver sendo configurado como uma análise detalhada, essa propriedade não será preenchida.
`isDashboardCrossFilteringEnabled`	Quando definido como verdadeiro, o cruzamento de filtros é ativado no painel. Se o bloco estiver sendo configurado como uma análise detalhada, 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 filtros e mudanças de fuso horário feitas no nível do painel.
`lastRunSourceElementId`	O ID do elemento de extensão do bloco que acionou a última execução do painel. O ID será indefinido se a execução do painel for acionada pelo botão Executar ou atualização automática do painel ou se a execução for acionada usando o SDK de incorporação. Se o bloco estiver sendo configurado como uma análise detalhada, 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 de painel, ela será notificada quando a execução começar e terminar.
`lastRunStartTime`	Indica o horário de início da última execução do painel. Se o bloco estiver sendo configurado como uma análise detalhada, 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 performance.
`lastRunEndTime`	Indica o horário de término da última execução do painel. Se o bloco estiver sendo configurado como uma análise detalhada, 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 performance.
`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 detalhada, 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 disponíveis do SDK de visualização são mostradas na tabela a seguir:

Função ou propriedade	Descrição
`visualizationData` (propriedade)	Visualização (combinação de dados de `visConfig` e `queryResponse`).
`visConfig` (propriedade)	Dados de configuração de visualização: Configurações de medição Configurações de dimensão 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 detalhada.
`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 do recurso Detalhar. Ele só pode ser chamado uma vez.
`setVisConfig`	Atualiza a configuração da 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étrica
`queryFieldDimensions`	Informações de dimensão
`queryFieldTableCalculations`	Informações sobre cálculos de tabela
`queryFieldPivots`	Informações de pivô
`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 medição de campo.
`fieldDimensions`	Informações de dimensão do campo.
`fieldTableCalculations`	Informações sobre cálculos de tabela de campo.
`fieldPivots`	Informações de dinamização de campo.
`fieldMeasureLike`	Uma matriz concatenada de informações de medição de campo e cálculos de tabela que se comportam como medições.
`fieldDimensionLike`	Uma matriz concatenada de informações de dimensão de campo e cálculos de tabela que se comportam como dimensões.

Como usar o SDK de incorporação

Não é recomendável usar o SDK de incorporação 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.