Gráficos JS: Planilhas Google

Neste artigo, faremos um gráfico dos dados de um feed de planilha do Google acessível publicamente (via JSON) e criaremos um painel usando o biblioteca JS Charting. Ao consumir a planilha dessa forma, os resultados atualizados serão exibidos assim que as edições compartilhadas forem feitas por aqueles com permissão para editar os dados.

Usaremos esta planilha (Figura 1):

Para criar o seguinte painel (Figura 2):

Configurando a planilha

Ao analisar o feed de dados da planilha, será mais prático acessar as colunas por nomes de cabeçalho. Para configurar uma linha de cabeçalho, o senhor deve congelar uma linha na página da planilha. Clique em View > Freeze > 1 row para criar uma linha de cabeçalho. Isso também pode ser feito com colunas, mas, no nosso caso, congelamos apenas uma única linha, que está em negrito na figura 1.

A próxima etapa é publicar a planilha na Web para que ela possa ser acessada no navegador;
No menu do Google Docs, com a planilha aberta, selecione: File > Publish to the web.

Será gerado um link, que no nosso caso é

https://docs.google.com/spreadsheets/d/1D1vL8EI0uRzeiGM-A8hZLgUCexXrocw5B_qTGnCekNE/pubhtml

Copie esse link para referência, pois o usaremos para buscar o feed de dados. Em seguida, clique no botão Publish (Publicar).

Buscando o feed de dados

Agora que a planilha está disponível on-line, usaremos a função getJSON do jQuery para buscá-la como JSON. A seguinte formatação específica de URL é necessária para obter o JSON:

https://spreadsheets.google.com/feeds/list/1D1vL8EI0uRzeiGM-A8hZLgUCexXrocw5B_qTGnCekNE/od6/public/basic?alt=json

Observe a parte destacada do URL, que foi retirada do pop-up “Publish to the web” URL na etapa anterior;

O código para obter esse feed de dados com jQuery é:

$.getJSON(
    "https://spreadsheets.google.com/feeds/list/1D1vL8EI0uRzeiGM-A8hZLgUCexXrocw5B_qTGnCekNE/od6/public/basic?alt=json",
    function(data){
    console.log(data);
}
    

Essa linha apenas acessaria o JSON e o escreveria no console do navegador, mas precisamos analisar e consumir os dados.

Analisando os dados

A estrutura de dados JSON bruta tem a seguinte aparência:

Cada entrada representa uma linha na planilha. Este é um exemplo de linha dos dados

Observe que apenas as células com conteúdo são incluídas na propriedade $t;

O código a seguir analisa os dados da planilha em uma série de pontos e recebe dois parâmetros. Os dados e o nome da coluna que representa os valores x que são compartilhados por todos os pontos de dados.

Veja a caneta por Arthur Puszynski (@jsblog) em CodePen.

Ele funciona passando cada entrada com um nome de série, valor x e y para a função addPointToSeries(). Se não houver uma série com esse nome, uma nova série será criada; caso contrário, um ponto será adicionado à série. Depois que todas as entradas são processadas, uma matriz de séries é retornada.

OBSERVAÇÃO: Ao analisar a propriedade de conteúdo $t, certifique-se de dividir os valores usando uma vírgula com um espaço depois dela ‘, ‘ O mesmo vale para o nome e o valor da coluna ‘: ‘ Isso é necessário porque os valores numéricos podem ser formatados incluindo uma vírgula, como US$ 1.120,00, e os valores de data e hora podem conter dois pontos na parte da hora, o que pode causar problemas ao analisar.

Criando seu painel de gráficos

Agora chegamos à parte divertida: visualizar esses dados. O jQuery já está incluído, portanto, só precisamos adicionar o script do gráfico para começar.

<script src="JSC/JSCharting.js"></script>

Em seguida, é adicionado um elemento div para o gráfico em si:

<div id="mainChart"></div>

E o código para criar um gráfico a partir dos dados que temos até agora:

$('#mainChart').JSC({
	xAxisScaleType: 'time',
	yAxisScaleRangeMin: 0,
	series: seriesData
});
    

Veja a caneta por Arthur Puszynski (@jsblog) em CodePen.

Agora que o gráfico básico está configurado, adicionaremos algumas configurações para ajustar o gráfico e aproveitar as vantagens da personalização oferecida pelo JSCharting.

Primeiro, algumas configurações do eixo y para descrever os valores apresentados nesse gráfico.

yAxis:{
    formatString:'c',
    labelText:'Received',
    scaleRangeMin: 0
},
    

Observação: observe como esse bloco de opções é um objeto sob a propriedade yAxis, enquanto no exemplo anterior uma única propriedade na raiz das opções foi usada para definir opções semelhantes. Isso é possível porque a API de opções do JSCharting permite unir os nomes hierárquicos das propriedades em uma única configuração de propriedade por conveniência.

Aqui, formatamos os valores dos dados y como moeda e definimos o rótulo do eixo y. A descrição dos dados dessa forma se propagará para todas as outras partes do gráfico que utilizam valores y. Por exemplo, sempre que um valor y for mencionado em uma dica de ferramenta ou em outro lugar, ele será automaticamente formatado como moeda. Ao atribuir um rótulo ao eixo, o senhor também ajudará as dicas de ferramentas automáticas a descrever os pontos de dados.

Em seguida, especificamos um título para esse gráfico usando o seguinte código:

titleLabelText: '2015 Accounts Receivable Total: %sum'

Observe o token %sum incluído no texto do título. Há muitos tokens que podem ser usados no título do gráfico. Esses tokens estão todos listados na seção de coleção de séries deste referência de token.

Além disso, observe como a soma assume o formato de moeda, uma vez que está relacionada aos valores no eixo y.

Em seguida, vamos modificar os rótulos das legendas para incluir as somas de cada série:

legendDefaultEntryText:'%name %sum',

Veja a caneta por Arthur Puszynski (@jsblog) em CodePen.

O próximo gráfico que criaremos será baseado nos cálculos obtidos nesse primeiro gráfico e terá a renda média mensal de cada unidade mostrada como um gráfico de barras. Outra div é adicionada ao html para o segundo gráfico do nosso painel:

<div id="avgChart"></div>

Em seguida, para interagir com os dados do primeiro gráfico e usar esses cálculos, o código do gráfico de média será colocado em um retorno de chamada do método de inicialização do primeiro gráfico;

$('#mainChart').JSC({/*options*/, function(chart){ /*callback code*/});

Esse gráfico conterá apenas uma série com uma barra que representa a renda média mensal de cada série. Para fazer isso, as séries do gráfico principal são iteradas e um novo ponto é criado para cada uma delas, em que o valor y é a soma da série dividida por 12 meses;

Ao especificar uma paleta para essa série, cada barra assumirá uma cor diferente e corresponderá ao código de cores do gráfico principal.

Veja a caneta por Arthur Puszynski (@jsblog) em CodePen.

O gráfico final será um gráfico de pizza usando esses dados originais para mostrar a porcentagem de renda com que cada unidade contribuiu para o total. Nosso gráfico atual pode ser convertido em um gráfico de pizza simplesmente adicionando a propriedade type:’pie’. O senhor pode visualizar uma lista de tipos de gráficos JS juntamente com amostras de cada um para experimentar outros tipos. Essa configuração faz com que o gráfico mostre uma pizza em que cada série se torna uma fatia. Se o objetivo fosse fazer com que uma pizza representasse cada série, a configuração seria
defaultSeriesType:’pie’, que faria com que cada série fosse do tipo pizza.

Veja a caneta por Arthur Puszynski (@jsblog) em CodePen.

$('#pieChart').JSC({
	type:'pie',
 	yAxisFormatString: 'c',
     defaultPointLabelText:'<b>%name</b> %percentOfTotal%',
	series: seriesData
  });

Observe como a string de formato do eixo y é especificada, apesar do fato de as tortas não terem eixos. Isso ocorre porque a configuração do eixo y descreve os valores y em vez de um eixo real.

O texto padrão do rótulo do ponto também é especificado para esse gráfico de pizza usando o seguinte código:

defaultPointLabelText:'<b>%name</b> %percentOfTotal%',

Novamente, utilizamos tokens, mas desta vez eles são do conjunto de tokens de ponto.

JS Charting Spreadsheet helper (Auxiliar de planilha de gráficos JS)

Vale a pena mencionar um recurso interessante do JS Charting que pode ser útil em alguns casos de planilhas. No gráfico acima, usamos uma escala de tempo para o eixo x, de modo que a ordem e a posição de cada ponto de dados são definidas pelo próprio valor. Em alguns casos, como abreviações de meses com três letras, os valores x são nomes ou quaisquer cadeias arbitrárias. Como algumas dessas cadeias não podem ser analisadas em datas ou quaisquer valores quantitativos que indiquem uma posição ao longo do eixo x, a ordem de classificação dos pontos pode não estar correta. Isso ocorre, é claro, se houver células vazias em uma planilha e os primeiros valores da primeira série estiverem faltando. Em geral, o senhor esperaria que a primeira série processada definisse os valores iniciais do eixo x. Em seguida, todos os novos valores do eixo X encontrados nas séries subsequentes seriam colocados no final do eixo X. O JSCharting analisará automaticamente a ordem de todos os pontos da série para determinar qual é a ordem pretendida, mesmo quando algumas séries tiverem pontos faltando. O senhor pode ver um exemplo disso aqui. 13;

Veja a caneta por Arthur Puszynski (@jsblog) em CodePen.

Aqui, atribuímos os valores de data como nomes de pontos e removemos a configuração da escala de tempo do eixo x. O resultado é que o gráfico tem a mesma aparência de quando usamos escalas de tempo e valores.

Conclusão

As planilhas do Google oferecem alguns recursos exclusivos para armazenar dados na nuvem e permitem buscá-los para uso em qualquer aplicativo da Web. Também é possível atualizar dinamicamente essas planilhas fornecendo um backend de banco de dados baseado em nuvem. O JSCharting facilita a visualização desses dados e, com seu suporte a tokens de rótulo, é possível criar gráficos ricos e descritivos com muito pouco código. Há muitos tipos de gráficos disponíveis, incluindo o mapeamento, que é fornecido com o produto sem custo adicional. O conjunto completo de tipos e recursos de gráficos pode ser baixado gratuitamente e experimentado para fins de desenvolvimento. A documentação do JSCharting descreve a API declarativa e é bastante exaustiva.