Como usar componentes de visualização para criar uma visualização personalizada

Este tutorial é destinado a desenvolvedores JavaScript experientes e pressupõe alguma familiaridade com técnicas de programação funcionais.

Neste exemplo, começamos com uma consulta relacionada a informações hipotéticas de vendas trimestrais para algumas marcas. Primeiro, filtraremos a consulta por marcas específicas e, em seguida, os resultados serão dinâmicos por trimestre de vendas. Consulte a tabela a seguir para ver um exemplo.

Observação :a rotação é um recurso do Looker que permite agrupar os resultados por uma determinada dimensão. Leia mais sobre dinamização na página de documentação Como analisar dados no Looker. Leia mais sobre como filtrar dados na página de documentação Como filtrar e limitar dados.

Em seguida, usaremos os componentes de visualização para criar uma visualização personalizada que mostra a tendência dos produtos de cada marca no último trimestre. O resultado será um novo tipo de visualização, composto por uma série de sparklines aninhados em uma tabela, que se parece com este exemplo:

Além de mostrar como criar uma visualização personalizada, este exemplo demonstra algumas práticas recomendadas para trabalhar com a API Looker em um aplicativo React.

Para criar uma visualização personalizada com os componentes do Looker, verifique se a configuração atende aos requisitos e siga estas etapas:

1. Crie uma consulta em uma Análise e copie o valor qid
2. Transmitir os dados para um componente de visualização personalizado
3. Criar o componente CustomVis
4. Transforme os dados normalizados
5. Insira os dados transformados em CustomVis
6. Gerar a visualização personalizada

Usar componentes de visualização para criar uma visualização personalizada é apropriado quando ela é destinada a um aplicativo ou extensão incorporado. Se você quiser disponibilizar a visualização personalizada para os usuários do Looker em uma instância do Looker, siga as instruções na página de documentação do visualization. Se você quiser desenvolver uma visualização personalizada e fazer upload dela para o Marketplace do Looker, siga as instruções na página de documentação Como desenvolver uma visualização personalizada para o Marketplace do Looker.

Requisitos

Antes de começar, alguns elementos são necessários:

• Você precisa ter acesso a uma instância do Looker.
• Se você está criando no framework de extensão ou no seu próprio aplicativo React independente, é importante fazer a autenticação com a API do Looker e ter acesso ao objeto do SDK do Looker. Leia sobre a autenticação da API Looker ou nosso framework de extensões para mais informações.
• Verifique se você instalou o pacote NPM dos componentes de visualização do Looker e o pacote NPM @looker/components-data (links em inglês). As informações sobre como instalar e usar o pacote de componentes de visualização podem ser encontradas no documento README, disponível no GitHub e no NPM (links em inglês).

Etapa 1: criar uma consulta em uma Análise e copiar o ID da consulta

Neste exemplo, usamos informações de vendas trimestrais hipotéticas para as marcas que estamos acompanhando ao longo do tempo.

Esses dados serão dinamizados, já que a dinamização é a maneira integrada do Looker de agrupar os resultados da consulta. Em uma Análise, é possível executar uma consulta e criar um gráfico dos dados usando um dos tipos de visualização nativa do Looker. O gráfico fornece muitas informações, mas é difícil analisar rapidamente como os produtos de cada marca estão em alta:

Assim como no exemplo de renderização de uma visualização simples, a próxima etapa é copiar o valor qid da barra de URL da Análise. Para os fins deste exemplo, o valor de qid será Uijcav7pCA4MZY2MompsPZ, mas esse valor é específico para nossa instância de teste. Seu valor será diferente.

Etapa 2: transmitir os dados para um componente de visualização personalizado

Para começar, transmita o valor qid do URL da Análise para o componente Query e o objeto do SDK autenticado para o DataProvider.

import React, { useContext } from 'react'
import { ExtensionContext } from '@looker/extension-sdk-react'
import { DataProvider } from '@looker/components-data'
import { Query } from '@looker/visualizations'

export const MyReactApp = () => {
  const { core40SDK } = useContext(ExtensionContext)

  return (
    <DataProvider sdk={core40SDK}>
      <Query query='Uijcav7pCA4MZY2MompsPZ'></Query>
    </DataProvider>
  )
}

Em seguida, em vez de renderizar uma visualização nativa do Looker usando o componente Visualization, vamos criar nosso próprio componente personalizado chamado CustomVis.

O componente Query pode aceitar qualquer elemento do React como filho e simplesmente transmitir os valores config, data, fields e totals como propriedades para renderizar os próprios componentes de visualização. Vamos renderizar CustomVis como filho de Query para que ele possa receber todos os dados relevantes como propriedades.

import React, { useContext } from 'react'
import { ExtensionContext } from '@looker/extension-sdk-react'
import { DataProvider } from '@looker/components-data'
import { Query } from '@looker/visualizations'
import { CustomVis } from '../path/to/MyCustomVis'

export const MyReactApp = () => {
  const { core40SDK } = useContext(ExtensionContext)

  return (
    <DataProvider sdk={core40SDK}>
      <Query query='Uijcav7pCA4MZY2MompsPZ'>
        <CustomVis />
      </Query>
    </DataProvider>
  )
}

Etapa 3: criar o componente CustomVis

Em seguida, vamos criar o componente CustomVis. As propriedades herdadas do componente Query são config, fields, data, pivots e totals:

• config descreve todas as formas de renderização dos dados em um gráfico, como a espessura da linha em um minigráfico ou o tamanho e a forma dos pontos de um gráfico de dispersão.
• fields armazena metadados adicionais sobre os valores de medida e dimensão retornados pela consulta, por exemplo, como os valores precisam ser formatados ou o que rotular cada eixo.
• data é a resposta de chave-valor retornada da consulta.
• pivots descreve a dimensão de rotação da consulta.
• totals faz referência aos totais de linhas do Looker para uso em visualizações baseadas em tabelas.

Podemos transmitir essas propriedades não modificadas para uma visualização de tabela inserindo um componente Table.

import React from 'react'
import { Table } from '@looker/visualizations'

export const CustomVis = ({ config, fields, data, pivots }) => {
  return <Table config={config} data={data} fields={fields} pivots={pivots} />
}

Assim temos uma noção dos dados, já que eles são retornados diretamente do SDK. Na resposta renderizada, há uma linha para cada marca com os resultados agrupados ou dinamizados por trimestre.

Etapa 4: transformar os dados normalizados

Para converter esses dados dinâmicos na renderização com minigráficos aninhados, isolamos todos os valores de medida e os transmitimos para os subgráficos. No gráfico a seguir, os dados relevantes para uma única linha estão destacados para ilustrar os dados que serão recolhidos e renderizados com uma visualização filha:

Vamos criar uma transformação personalizada para isso. O exemplo a seguir é específico para esse cenário. Será necessário analisar seus próprios dados adequadamente.

import React from 'react'
import { Table, Sparkline } from '@looker/visualizations'

// we assign this value to a constant to ensure that fields and data
// objects remain in sync.
const NESTED_DATA_KEY = 'orderCount'

const nestSparklines = (data) => {
  return data.reduce((acc, d) => {
    // the first entry is the dimension (brand name), and the rest of the rows are the
    // quarterly sales information we want to pass to the Sparkline.
    const [parentDimension, ...measurePairs] = Object.entries(d)

    // `nonPivotedData` represents a single data row.
    // e.g. [{entry: 1, orderCount: 10}, {entry: 2, orderCount: 15}, ...etc]
    const nonPivotedData: SDKRecord[] = measurePairs.map(([_, value], i) => {
      return { entry: i, [NESTED_DATA_KEY]: value }
    })

    // now for each row in the table we render a Sparkline using the `nonPivotedData`
    // that we built above.
    // E.G. [{products.brand: 'adidas', orderCount: <Sparkline />}]
    return [
      ...acc,
      {
        [parentDimension[0]]: parentDimension[1],
        [NESTED_DATA_KEY]: () => (
          <Sparkline
            height={75}
            data={nonPivotedData}
            fields={{
              measures: [{ name: NESTED_DATA_KEY }],
              dimensions: [],
            }}
          />
        ),
      },
    ]
  }, [])
}

A função é criada usando as seguintes etapas:

1. Reduza o conjunto de dados para isolar o nome da marca dos dados trimestrais do pedido para cada linha.
2. Atualize cada linha para incluir a dimensão e um componente do React renderizado que possa representar os valores de cada linha na tabela.

Etapa 5: inserir os dados transformados em CustomVis

Agora, transforme os dados usando nossa nova função e atribua a saída a uma nova variável chamada nestedData:

export const CustomVis =({
  fields,
  data,
  config,
  pivots,
}) => {
  const nestedData = nestSparklines(data)

  return (
    <Table
      fields={{
        measures: [{ name: NESTED_DATA_KEY, label: 'Orders Count By Quarter' }],
        dimensions: fields.dimensions,
        pivots: [],
      }}
      config={config}
      data={nestedData}
      pivots={pivots}
    />
  )
}

Etapa 6: gerar a visualização personalizada

Depois de inserir os dados transformados e configurar o gráfico, a visualização será semelhante a este exemplo de uma tabela com minigráficos individuais para cada linha:

Todo o código necessário para renderizar a visualização acima é o seguinte:

import React, { useContext } from 'react'
import { ExtensionContext } from '@looker/extension-sdk-react'
import { DataProvider } from '@looker/components-data'
import { Query, Sparkline, Table } from '@looker/visualizations'

// we assign this value to a constant to ensure that fields and data
// objects remain in sync.
const NESTED_DATA_KEY = 'orderCount'
const ROW_HEIGHT = 75

const nestSparklines = data => {
  return data.reduce((acc, d) => {
    // the first entry is the dimension (brand name), and the rest of the rows are the
    // quarterly sales information we want to pass to the Sparkline.
    const [parentDimension, ...measurePairs] = Object.entries(d)

    // `nonPivotedData` represents a single data row.
    // e.g. [{entry: 1, orderCount: 10}, {entry: 2, orderCount: 15}, ...etc]
    const nonPivotedData = measurePairs.map(([_, value], i) => {
      return { entry: i, [NESTED_DATA_KEY]: value }
    })

    // now for each row in the table we render a Sparkline using the `nonPivotedData`
    // that we built above.
    // E.G. [{products.brand: 'adidas', orderCount: <Sparkline />}]
    return [
      ...acc,
      {
        [parentDimension[0]]: parentDimension[1],
        [NESTED_DATA_KEY]: () => (
          <Sparkline
            height={ROW_HEIGHT}
            data={nonPivotedData}
            fields={{
              measures: [{ name: NESTED_DATA_KEY }],
              dimensions: [],
            }}
          />
        ),
      },
    ]
  }, [])
}

const CustomVis = ({ fields, data, pivots, config }) => {
  const nestedData = nestSparklines(data)

  return (
    <Table
      config={config}
      height={500}
      fields={{
        measures: [{ name: NESTED_DATA_KEY, label: 'Orders Count By Quarter' }],
        dimensions: fields.dimensions,
        pivots: [],
      }}
      data={nestedData}
      pivots={pivots}
      defaultRowHeight={ROW_HEIGHT}
    />
  )
}

export const MyReactApp = () => {
  const { core40SDK } = useContext(ExtensionContext)

  return (
    <DataProvider sdk={core40SDK}>
      <Query query='Uijcav7pCA4MZY2MompsPZ'>
        <CustomVis />
      </Query>
    </DataProvider>
  )
}

Próximas etapas

• Como usar componentes de visualização e a propriedade dashboard para renderizar uma visualização simples
• Como usar componentes de visualização e a propriedade query para renderizar uma visualização simples
• Como usar componentes de visualização para renderizar visualizações personalizadas
• Tabelas de propriedades de consulta e visualização