2f: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:30:T713,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 cabecalhos "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.31:T534,O [opensheet](https://github.com/benborgers/opensheet#readme) é uma ferramenta criada por Ben Borges, que serve justamente para extrair os dados de uma planilha do Google Sheets no formato *JSON*. O procedimento é explicado [neste site](https://benborgers.com/posts/google-sheets-json), mas é algo tão simples que pode ser resumido em poucas linhas: Primeiro você deve tornar a planilha acessível para a leitura de todos, clicando no botão "Compartilhar" (no canto superior direito do Google Sheets), e alterando a compartilhamento para "Qualquer pessoa na internet com este link pode ver". Depois você deve extrair o **ID** da sua planilha, que é o valor na *URL* entre o `spreedsheets/d/` e o `/edit`, como no exemplo abaixo:

https://docs.google.com/spreadsheets/d/1o305wURsoKEaochwqa01482JfeoaCEUAdoeka8UgV/edit#gid=0

O link utilizado para obter os dados da planilha em formato *JSON* passa a ser: `https://opensheet.elk.sh/ID da planilha/Nome da aba`, ou, conforme nosso exemplo acima:

https://opensheet.elk.sh/1o305wURsoKEaochwqa01482JfeoaCEUAdoeka8UgV/Plan+1

Pronto. É só isso. E funciona de forma mais rápida do que o procedimento antigo, que permanece explicado abaixo (apenas por uma questão de registro, e claro, para caso algum problema venha a acontecer). 32:T4bb,```javascript function doGet(e) { if (e.parameter['cabecalhos'] != undefined && e.parameter['cabecalhos'] != "") { var DataColNames = e.parameter['cabecalhos']; } else { var DataColNames = "A1"; } if (e.parameter['dados'] != undefined && e.parameter['dados'] != "") { var DataStartCell = e.parameter['dados']; } else { var DataStartCell = "A2"; } var ss = SpreadsheetApp.getActiveSpreadsheet(); if (e.parameter['planilha'] != undefined && e.parameter['planilha'] != "") { var sheet = ss.getSheetByName(e.parameter['planilha']); } else { var sheet = ss.getActiveSheet(); } var cell = sheet.getRange(DataStartCell); var headers = sheet.getRange(DataColNames); var conteudo = []; var key; for (linhas = 0; linhas < (sheet.getLastRow()-cell.getRow()); linhas ++) { conteudo[linhas] = {}; for (colunas = 0; colunas < sheet.getLastColumn()-cell.getColumn()+1; colunas++) { key = headers.offset(0, colunas).getValue(); valor = cell.offset(linhas,colunas).getValue(); conteudo[linhas][key] = valor; } } return ContentService.createTextOutput(JSON.stringify(conteudo)).setMimeType(ContentService.MimeType.JSON); } ```33:T582,Salve e execute o código. O *Google* irá lhe solicitar diversas autorizações para que o código possa acessar os dados da planilha, e por fim, provavelmente indicará um erro de execução - isto é normal - por que a função `doGet(e)` recebe uma requisição pela *URL*, coisa que não estará acontecendo no momento. A próxima etapa é *implantar* a programação na planilha. Clique no botão **implantar**, e na opção **nova implantação**, deixe uma descrição (que é para o controle de versão do código), e defina **Quem pode acessar** (último campo) para *Qualquer pessoa*, o que permitirá que qualquer ferramenta ou plataforma conseguirá acessar à saída *JSON* da planilha. Por fim clique no botão **implantar**. Como resultado, o *Google Docs* lhe informará uma *URL* como **App da Web**. Se você acessar esta *URL* no seu navegador, verá a saída *JSON* dos dados da sua planilha. Este código assume que você estará colocando os dados na primeira aba/planilha do documento, que os cabecalhos estarão na linha 1 se iniciando na coluna A, e que os dados estarão se iniciando na linha 2 da coluna A. Se isto não for verdade, você pode parametrizar informações no final da *URL* informando as variáveis **planilha**, **cabecalhos** e **dados**, como no exemplo abaixo: ``` https://script.google.com/macros[...]/exec?planilha=OutraPlanilha &cabecalhos=B4&dados=B7 ``` 34:T4bd,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 via na saída *JSON* da planilha é a função `fetch()`, que já resolverá todas estas questões. Se você estiver escrevendo um código *Javascript* fora do *Observable*, seu `fetch()` será assim: ```javascript var url = 'https://script.google.com/macros[...]/exec'; // ou https://opensheet.elk.sh/a09rksjodf[...]/Minhaaba fetch(url).then(response => response.json()).then((dados) => { console.table(dados); Processa(dados); } ``` Tenha consciência de que `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 `Processa(dados)`, ou outra de sua preferência, passando os dados para serem processados quando eles efetivamente tiverem sido recebidos. Se você estiver utilizando o *Observable*, seu `fetch()` terá uma sintaxe um pouco diferente:35: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`. 36:[] 2d:{"title":"BACKUP","cells":[{"id":0,"value":"# BACKUP\n\n# Texto Original: Dataviz em *Javascript* utilizando dados em tempo real de uma planilha no *Google Docs* com procedimentos antigos para uso do Google Script.","pinned":false,"hidden":false,"mode":"md"},{"id":384,"value":"$2f","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*, formato que adotaremos aqui, é 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### Gerando uma saída *JSON* em uma planilha do Google","pinned":false,"hidden":false,"mode":"md"},{"id":49,"value":"$30","pinned":false,"hidden":false,"mode":"md"},{"id":411,"value":"
\n### Utilizando o opensheet de Ben Borgers","pinned":false,"hidden":false,"mode":"md"},{"id":417,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":406,"value":"
\n### Procedimento antigo
(ainda funciona, mas é pouco prático e mais lento)","pinned":false,"hidden":false,"mode":"md"},{"id":50,"value":"Para gerar a saída em *JSON* dos dados de uma planilha será necessário implementar uma programação no documento que faça este trabalho. Isso é feito acessando o *Editor de Scripts* no menu do *Google Sheets* através de **Ferramentas > Editor de Scripts **.\n\nNo editor, inclua o código abaixo:\n","pinned":false,"hidden":false,"mode":"md"},{"id":74,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":82,"value":"$33","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":"$34","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":128,"value":"
\n### Conteúdos\n\nEm ambos os casos, os resultados do `fetch()` proverão um objeto *JSON*, que pode ser expresso tanto por `dados[numerodalinha].cabecalho` no primeiro exemplo (fora do *Observable*), como por `resultados[numerdalinha].cabecalho` no segundo exemplo (no *Observable*).\n\nEles também podem ser expressos como uma *array* bidimensional, caso seja desejável utilizar alguma variável para acessar os cabecalhos, como `dados[numerodalinha][cabecalho]` ou `resultados[numerodalinha][cabecalho]`.","pinned":false,"hidden":false,"mode":"md"},{"id":276,"value":"Utilizaremos aqui uma planilha real do *Google Sheets* onde a saída *JSON* foi implementada, para construir uma visualização simples no próprio *Observable*.","pinned":false,"hidden":false,"mode":"md"},{"id":281,"value":"planilha = \"https://script.google.com/macros/s/AKfycby9lSR5Lk6IvIXudJe41vxcpVIZwV9Da4sKEQg-TcSYe-XYsb1eqaSTnx7koNDYesA/exec\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":268,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":155,"value":"\nPor se tratar de uma função assíncrona, para executá-la no *Observable* você precisará usar a chave **await**. você pode sondar os dados obtidos pelo `fetch()` na variável `resultados`, abaixo (clicando na seta antes de `Array`):\n","pinned":false,"hidden":false,"mode":"md"},{"id":145,"value":"resultados = await lista(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":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":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":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":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 `