Skip to content

Importador de Instituições do MuseusBR

Jump to bottom
Mateus Machado Luna edited this page Aug 12, 2024 · 2 revisions

O módulo "Importador de Instituições do MuseusBR" abrange uma das funcionalidades mais importantes criada para o VisiteMuseus que é a capacidade de se criar Instituições pré-preenchidas através de dados existentes no Cadastro Nacional de Museus (aka MuseusBR).

A funcionalidade tem uma interface frontend criada usando os componentes React mais modernos do WordPress. É a única região do código que demanda compilação, visto que os arquivos fontes React estão em /museusbr-fetcher/src mas o Javascript utilizando mesmo está em /museusbr-fetcher/build.

A lógica de criação dos itens no banco em si permanece em PHP. Toda esta funcionalidade depende fortemente dos IDs de metadado existentes tanto no VisiteMuseus quanto no MuseusBR, inclusive da URL da API do MuseusBR, que está hardcoded no código.

Arquivos envolvidos

/museusbr-fetcher/src/hooks/use-museus.js

Neste arquivo estão as consultas via API feitas do lado do cliente. As funções são chamadas nos componentes React.

fetchMuseusFromMuseusBR()

A busca textual feita via API REST na instalação do Cadastro Nacional de Museus. O parâmetro inputValue contém a string de busca. Quando retornada a resposta, o array de itens (museus) é mapeado para serem passados apenas os campos relevantes na criação da lista no autocomplete.

fetchMuseusFromMuseusBRDebounced()

Versão alternativa à função anterior que aplica um debounce de 600ms para evitar muitas chamadas à API enquanto o usuário digita.

prepareItemToCreateInstituicao()

Função chamada para consultar todos os detalhes do museu escolhido e passá-los à função que cria a instituição. A consulta feita em fetchMuseusFromMuseusBR() busca apenas alguns dados básicos da instituição. Aqui são consultados todos os metadados além dos arquivos de mídia, uma vez que a instituição for selecionada para ser criada.

  • Há uma lógica para se passar os filhos de metadados compostos no mesmo array de metadados, deixando a resposta mais linear/
  • Há uma lógica para se passar os nomes dos termos de taxonomia como valores dos metadados tipos Taxonomia (ao invés de se passar os objetos dos termos). Isso permite que os termos sejam criados usando as Taxonomias existens na instalação do VisiteMuseus, que na prática são cópias das Taxonomias do MuseusBR;
  • Há a lógica para se passar a URL dos arquivos de mídia como parâmetro para se importar a mídia na hora de se configurar os anexos na instalação do VisiteMuseus;

createInstituicaoFromMuseu()

Função ajax que chama a função cne_create_instituicao() presente em - /museusbr-fetcher/museusbr-fetcher.php. Ao ser concluida com sucesso esta função redireciona o usuário para o formulário de edição do item recentemente criado com os dados pré-preenchidos.

/museusbr-fetcher/src/components

Os componentes React utilizados para montar o modal, o autocomplete e a interface de forma geral desta funcionalidade. Em sua maioria são utilizados componentes do Gutenberg, nativos do WordPress cuja documentação está disponível aqui.

A inicialização destes componentes é feita no /museusbr-fetcher/src/index.js, onde um botão é inserido na página que conter a classe .museusbr-fetcher-button-container em alguma tag.

/museusbr-fetcher/package.json

Lista de dependências e script de compilação do módulo Javascript. Foi utilizado fortemente a estrutura padrão de projetos WP Script, cuja documentação pode ser acessada aqui.

/museusbr-fetcher/museusbr-fetcher.php

cne_museusbr_fetcher_enqueue_style_script()

Usando a action admin_enqueue_scripts carrega os scripts compilados no contexto da página que lista as instituições e passa através da variável global cne_museusbr_fetcher algumas informações necessárias para script, como a URL das requisições ajax e o nonce preciso para se fazer as requisições autenticadas.

cne_create_instituicao()

A função chamada pela consulta quando o botão "Criar instituição" é pressionado. Esta função recebe, do lado do cliente os objetos item, itemDocument e itemMetadata construidos na createInstituicaoFromMuseu da [/museusbr-fetcher/src/hooks/use-museus.js](https://github.com/tainacan/cne/blob/main/museusbr-fetcher/src/hooks/use-museus.js).

  • Os dados guardados nestes objetos passados com parâmetro correspondem ao item da coleção de Museus do MuseusBR. Eles são enviados com uma string JSON e convertidos em um array PHP;
  • A função cria um item na coleção de instituição, com o status de "Rascunho automático";
  • Usando um mapeamento manual feito entre os IDs dos metadados na coleção de museus do MuseusBR e a coleção de instituições no VisiteMuseus, percorre-se o objeto de metadados do item criando valores novos para os metadados do item recém instanciado na VisiteMuseus;
  • Durante este loop, um vetor de warnings e errors é gerado para permitir depuração via servidor.
    • Avisos são guardados para situações menos críticas, como por exemplo quando não é encontrado um metadado mapeado (apenas alguns metadados do MuseusBR são puxados para o VisiteMuseus);
    • Erros são guardados quando a importação poderia gerar um item incoerente. Por exemplo, se o metadado tiver uma configuração diferente na instalação de origem. Um exemplo forte disso é se for tentado definir um termo de uma Taxonomia que não existe na instalação destino. Por conta disso, é importante que os metadados e as taxonomias de ambas as instalações estejam em sincronia, o que deve ser feito manualmente;
  • Quando o metadado de Estado é criado, usa-se uma função dedicada cne_get_regiao_from_estado() para se preencher também o metadado de Região derivada, visto que este dado não existe na instalação de origem;
  • Também é auto-preenchido o metadado que indica que a instituição está cadastrada no MuseusBR;
  • Há também uma lógica para preencher o documento e a minitura do item, usando da função \Tainacan\Media::get_instance()->insert_attachment_from_url, que baixa e cria a mídia do lado da instalação de destino.
Clone this wiki locally