30:T468,## Introdução Para iniciar com um pouco de contexto sobre porquê utilizar planilhas e dados em tempo real para a construção de visualizações, tentarei trazer um exemplo prático e real: Há alguns anos venho trabalhando em um mapeamento de narrativas digitais, mais especificamente em um de seus primeiros formatos, os *Point & Click Adventures*. Na tentativa de construção de um quadro com estes artefatos, acabei chegando em um momento onde sua atualização se tornava impossível se realizada manualmente em uma peça de design estática; acabei, desta forma, construíndo uma visualização amparada por uma lista de artefatos que pode ser atualizada facilmente. Esta história e como este projeto foi elaborado está documentada em um capítulo de meu [livro em permanente construção sobre interfaces](https://www.ranoya.com/books/public/interfaces/?theme=paleblue&forecolor=FFFFFF&bgcolor=0dc2f2). O capítulo específico é [este aqui](https://www.ranoya.com/books/public/interfaces/informacao.php?theme=paleblue&forecolor=FFFFFF&bgcolor=0dc2f2&embed=plain). O resultado visual deste trabalho está abaixo:31:T78e,A primeira questão importante para que possamos trabalhar com dados vindos de uma fonte externa na programação *Javascript* é definir como estes dados serão estruturados. #### CSV O formato mais antigo e tradicional para isso sempre foi o *CSV* (*comma separated values*, ou em português, valores separados por vírgula). Este é um formato bem direto e otimizado, mas que pode causar alguns problemas e dificultades: é uma forma linear e sem indexação das informações, que vai dar algum trabalho para que os dados sejam tratados quando o que queremos não é simplesmente exibir todas as informações linearmente; também pode ocasionar algumas dores de cabeça quando existirem vírgulas nos próprios dados. #### XML O formato *XML* (*extensible markup language*) foi uma maneira mais estruturada de possibilitar a troca de dados entre sistemas, e é uma solução que pode se tornar muito complexa, assim como um código *HTML*. É o formato mais verborrágico e menos otimizado, mas que possibilita maneiras muito variadas para se descrever e organizar os dados. O *XML* pode ser uma forma muito interessante de realizar a troca de dados, mas certamente não é a mais conveniente e prática quando se trabalha com *Javascript*. #### JSON O *JSON* é, definitivamente, a forma mais conveniente, já que é um objeto *Javascript*. Isto significa que você estará recebendo um objeto para ser utilizado imediatamente no seu código, com toda a flexibilidade que um objeto lhe oferecerá. Considere, por exemplo, uma tabela de dados onde eles estão registrados sob os cabeçalhos "Nome", "Idade" e "Profissao"; cada linha desta tabela poderá ser acessada no código como ``` dados[linha].Ano dados[linha].Idade dados[linha].Profissao ``` Isso proverá uma facilidade enorme na programação. Utilizaremos o melhor dos dois mundos aqui: capturaremos os dados em CSV de uma planilha, e os converteremos para *JSON*32:T61f,Há alguns anos atrás o processo para capturar os dados envolveria escrever uma função *Ajax* e tratar as diversas possibilidades de respostas da solicitação. Hoje, para nossa sorte, quem irá buscar estes dados é a função `getcsvdata()` do *DataT*, que estará resolvendo todas as atividades da API `fetch`, e convertendo os dados para nossa conveniência. Se você estiver utilizando o Observable, a sintaxe será bem simples: ```js meusdados = getcsvdata(GoogleSheetCsvURL('ENDEREÇO URL DA SUA PLANILHA NO GOOGLE')) ``` Se estiver utilizando fora do Observable, será necessário incluir mais um parâmetro na função, que é para qual função os dados *JSON* deverão ser enviados: ```js getcsvdata(GoogleSheetCsvURL('ENDEREÇO URL DA SUA PLANILHA NO GOOGLE'), function(dados) { // minha função para tratar os dados }); ``` ou ```js getcsvdata(GoogleSheetCsvURL('ENDEREÇO URL DA SUA PLANILHA NO GOOGLE'), minhafuncao); ``` Tenha consciência de que a API `fetch` é uma função assíncrona, e que dependendo do tempo de resposta do *Google Sheets*, ela levará um bom momento para responder. Não considere em hipótese nenhuma que os resultados sejam imediatos, ou em tempo de execução. É por este motivo que invocamos uma função `minhafuncao(dados)`, ou outra de sua preferência, passando os dados para serem processados quando eles efetivamente tiverem sido recebidos. Também é importante que a planilha do *Google Sheets* esteja compartilhada publicamente para leitura, do contrário não será possível acessar os dados.33:T4dc,Uma das questões que os profissionais de dados comentam sobre o uso de planilhas é que, mesmo com toda a flexibilidade que nos permitem, não tem o poder de um banco de dados relacional para modelar informações. Isso é parcialmente verdadeiro, principalmente por que o *Google Sheets* possui uma função `QUERY`, que nos permite construir uma *query SQL* para compor ou formular dados de maneira mais sofisticada do que através das fórmulas e funções nativas das planilhas. A função `QUERY` no Google Sheets funciona assim: ```sql =QUERY('Planilha1'!A2:D5, 'SELECT A,B WHERE C > D ORDER BY C DESC'; -1) ``` Exceto pela ausência de um `FROM tabela`, já indicado através de um `range` dado no primeiro parâmetro da função, a sintaxe *SQL* é a mesma do que já estamos acostumados em todo sistema de banco de dados. Esta ferramenta cria um campo inteiramente novo de possibilidades no uso das planilhas como fonte de dados em tempo-real, não só para construção de *dataviz*, mas para qualquer outro tipo de operação feita com dados sendo alimentados em tempo real. A implementação do *script* que fornece uma saída *JSON* para os dados funciona normalmente para tabelas construídas com o uso da função `QUERY`. 34:[] 2e:{"title":"Dataviz em Javascript utilizando dados em tempo real de uma planilha no Google Docs","cells":[{"id":0,"value":"# Dataviz em *Javascript* utilizando dados em tempo real de uma planilha no *Google Docs*","pinned":false,"hidden":false,"mode":"md"},{"id":384,"value":"$30","pinned":false,"hidden":false,"mode":"md"},{"id":391,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":396,"value":"Por se tratar de uma peça responsiva, talvez valha a pena experimentá-la em outros contextos de uso. Ela pode ser acessada [neste link](https://narrativas.ranoya.com/pointnclick/paralax.php?theme=invertpaleblue).\n\nOs dados que alimentam esta visualização também podem ser listados nesta [outra forma de visualização](https://narrativas.ranoya.com/pointnclick/lista.php), menos visual, em forma de tabela.\n\nO intuito geral deste texto é demonstrar de que maneira podemos transformar os dados armazenados em uma planilha online em objetos *JSON*, que podem ser facilmente trabalhados com programação *Javascript*. Os dados que alimentam as visualizações acima podem ser [acessados aqui](https://www.ranoya.com/AssetsManager/simplequery/pointnclickadv.php?filter=pncadv).\n\nSem maiores delongas e explicações, vamos então ao processo para fazer algo assim acontecer:","pinned":false,"hidden":false,"mode":"md"},{"id":6,"value":"
\n## 1ª Parte: Criando uma saída de dados da planilha","pinned":false,"hidden":false,"mode":"md"},{"id":12,"value":"Muitos que trabalham com infografia e dataviz usam ferramentas sofisticadas, seja por questões de produtividade e agilidade no projeto, seja por que possuem estas ferramentas e uma infra-estrutura tecnológica à disposição para dar o devido suporte à atividade.","pinned":false,"hidden":false,"mode":"md"},{"id":20,"value":"Mas esta nem sempre é a realidade de todos, e, se você está buscando construir uma visualização utilizando uma plataforma como o *Observable*, ou se está construíndo uma representação visual utilizando uma biblioteca de programação como o *[D3](https://d3js.org/)* - fazendo as coisas no *modo hard* - é provável que você não tenha uma solução já resolvida para suprir os dados em tempo real de forma que possam ser facilmente trabalhados.","pinned":false,"hidden":false,"mode":"md"},{"id":25,"value":"Se é este o caso, esse texto poderá lhe ajudar. Mostrarei aqui como usar uma planilha do *Google* para alimentar dados para que uma visualização possa ser gerada, seja pelo *Observable*, ou em qualquer outro lugar.","pinned":false,"hidden":false,"mode":"md"},{"id":65,"value":"
\n### Performance\n\nUm aspecto que precisa ser conhecido e considerado é o fato de que a resposta do *Google Sheets* nunca terá uma boa performance. Eu suponho que ele é intencionalmente lento para que não acabe sendo ostensivamente utilizado no lugar de bancos de dados e outras soluções das quais o *Google* não deseja se posicionar como concorrente.\n\nGerar uma saída de dados não levará a eternidade computacional de um minuto, mas também não ocorrerá em frações de segundo como em um servidor *SQL*. Se performance é uma questão essencial no seu projeto, esta talvez não seja a solução ideal.\n\nConforme meu colega [Claudio Esperança](https://observablehq.com/@esperanc) comentou em uma de nossas conversas, o *JSON*, é consideravelmente verborrágico se comparado a outros formatos como *CSV*. Se você estiver tratando conjuntos muito grandes de dados, o tamanho do arquivo pode realmente gerar algum impacto.","pinned":false,"hidden":false,"mode":"md"},{"id":31,"value":"
\n### Entendendo os formatos dos dados","pinned":false,"hidden":false,"mode":"md"},{"id":49,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":411,"value":"
\n### Utilizando o DataT","pinned":false,"hidden":false,"mode":"md"},{"id":417,"value":"A captura de dados acontece através da API `fetch` do próprio *Javascript*. Uma instrução `fetch` pode ser escrita com o código abaixo no Observable:","pinned":false,"hidden":false,"mode":"md"},{"id":137,"value":"lista = function (url) {\n\n let dados = fetch(url).then(response => {\n return response.json(); \n });\n\n return dados; \n\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":467,"value":"```javascript\nlista = function (url) {\n\n let dados = fetch(url).then(response => {\n return response.json(); \n });\n\n return dados; \n\n}\n```","pinned":false,"hidden":false,"mode":"md"},{"id":443,"value":"Esta instrução funcionará muito bem se os dados capturados já estiverem no formato *JSON* disponíveis em um arquivo preparado. Para recebê-los diretamente de uma planilha, utilizei por muito tempo a solução [opensheet](https://opensheet.slk.sh) de Ben Borges, mas descobri no final de 2023 que ela era bloqueada por alguns provedores de internet como a Claro/NET, inviabilizando seu uso pelos transtornos provocados aos usuários deste provedor (e possivelmente de outros pelo mundo que também tenham bloqueado o endereço).\n\nComo solução para esta situação, incluí na biblioteca [DataT](https://datat.vercel.app) funções *Javascript* para realizar a mesma tarefa, mas adotando o *CSV* como base, e produzindo um *JSON* como resultado para facilitar a utilização dos dados.\n\nPara utilizá-la aqui no Observable, basta incluir o seguinte código no seu notebook:\n\n```javascript\nimport { getcsvdata, GoogleSheetCsvURL } from \"@ranoya/datat\"\n```","pinned":false,"hidden":false,"mode":"md"},{"id":447,"value":"import { getcsvdata, GoogleSheetCsvURL } from \"@ranoya/datat\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":450,"value":"Para utilizá-la fora do Observable, basta incluir a seguinte linha no seu código *HTML*:\n\n```html\n\n```","pinned":false,"hidden":false,"mode":"md"},{"id":107,"value":"
\n## 2ª Parte: Como receber os dados por *Javascript*","pinned":false,"hidden":false,"mode":"md"},{"id":114,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":128,"value":"
\n### Conteúdos\n\nEm ambos os casos, os resultados do `fetch` feito com `getcsvdata()` proverão um objeto *JSON*, que pode ser expresso por `meusdados[numerodalinha].cabecalho`.\n\nEles também podem ser expressos como uma *array* bidimensional, caso seja desejável utilizar alguma variável para acessar os cabeçalhos, como `meusdados[numerodalinha][cabecalho]`.","pinned":false,"hidden":false,"mode":"md"},{"id":276,"value":"Utilizaremos aqui uma planilha real do *Google Sheets* com dados capturados e transformados em *JSON*, para construir uma visualização simples no próprio *Observable*.","pinned":false,"hidden":false,"mode":"md"},{"id":281,"value":"planilha = \"https://docs.google.com/spreadsheets/d/14r3m_PuLm0ijwnSYptbOGlGKz8r7GAhQLw1-6KMY0Ew/edit#gid=0\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":268,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":487,"value":"
","pinned":false,"hidden":false,"mode":"md"},{"id":155,"value":"\nVocê também pode sondar os dados obtidos pelo `fetch()` na variável `resultados` abaixo (clicando na seta antes de `Array`), no formato em que o *Observable* os apresenta após serem carregados (utilizando a própria plataforma e a sintaxe apropriada do *DataT* para ela):\n\n```javascript\nresultados = gestcsvdata(GoogleSheetCsvURL(planilha));\n```","pinned":false,"hidden":false,"mode":"md"},{"id":145,"value":"resultados = getcsvdata(GoogleSheetCsvURL(planilha))","pinned":true,"hidden":false,"mode":"ojs"},{"id":149,"value":"
\n## 3ª Parte: Usando os dados (finalmente)","pinned":false,"hidden":false,"mode":"md"},{"id":247,"value":"Abaixo apresentamos os dados obtidos da planilha em forma númérica utilizando a função `criatabela(dados)`, descrita logo em seguida:","pinned":false,"hidden":false,"mode":"md"},{"id":230,"value":"html`${criatabela(resultados)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":485,"value":"
","pinned":false,"hidden":false,"mode":"md"},{"id":221,"value":"criatabela = function (meusdados) {\n var tabela =\n \"

\";\n\n // Cria Divs com os dados, estruturados como Grid por CSS\n for (var i = 0; i < meusdados.length; i++) {\n tabela +=\n \"

\" +\n meusdados[i].Nome +\n \"

\" +\n meusdados[i].Inicial +\n \"

\" +\n meusdados[i].Final +\n \"

\";\n }\n\n tabela += \"

\";\n\n // Retorna a a string para ser implementada como um elemento HTML no documento\n return tabela;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":477,"value":"```javascript\ncriatabela = function (meusdados) {\n var tabela =\n \"

\";\n\n // Cria Divs com os dados, estruturados como Grid por CSS\n for (var i = 0; i < meusdados.length; i++) {\n tabela +=\n \"

\" +\n meusdados[i].Nome +\n \"

\" +\n meusdados[i].Inicial +\n \"

\" +\n meusdados[i].Final +\n \"

\";\n }\n\n tabela += \"

\";\n\n // Retorna a a string para ser implementada como um elemento HTML no documento\n return tabela;\n}\n```","pinned":false,"hidden":false,"mode":"md"},{"id":254,"value":"
\nDe uma maneira um pouco menos rudimentar, mas ainda de forma bem simplória, utilizamos a função `gerasvg(dados)` para criar um elemento gráfico do tipo *SVG* e exibir os dados obtidos, visualmente. O resultado é esta representação abaixo, construída pelo código apresentado logo na sequência:","pinned":false,"hidden":false,"mode":"md"},{"id":190,"value":"html`${gerasvg(resultados)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":481,"value":"
","pinned":false,"hidden":false,"mode":"md"},{"id":178,"value":"gerasvg = function (meusdados) {\n let meusvg = ``;\n\n // Devolve o código SVG para ser incluíndo como elemento HTML no documento\n return meusvg;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":479,"value":"```javascript\ngerasvg = function (meusdados) {\n let meusvg = ``;\n\n // Devolve o código SVG para ser incluíndo como elemento HTML no documento\n return meusvg;\n}\n```","pinned":false,"hidden":false,"mode":"md"},{"id":310,"value":"É importante ressaltar que os dados tabulados e apresentados visualmente nestes dois exemplos estão sendo obtidos em tempo-real de uma planilha, e que qualquer alteração nela, proverá modificações nestes dois elementos imediatamente. Isto, ainda que sujeito a uma performance considerada lenta para os padrões da computação, fornece um recurso bastante interessante para a construção de visualizações de dados.\n\nA visualização poderia ser elaborada com qualquer tipo de tecnologia ou ferramenta disponível, seja um código trabalhando diretamente em cima do elemento `