Tainacan 1.3.0 – Novas opções para filtros, busca avançada e metadado de seleção

Se o último lançamento foi uma rodada de novidades mais especializadas, este volta para algo que quase todo mundo que usa o Tainacan toca no dia a dia: a busca. Nestes últimos meses trabalhamos na busca facetada, no formulário de Busca Avançada e na forma como os blocos Gutenberg escolhem itens de uma coleção — além de algumas correções de catalogação e importação que várias pessoas da comunidade reportaram.

A versão 1.3.0 também chega enquanto o WordPress 7.1 está sendo lançado, e precisamos garantir que nossos blocos Gutenberg continuassem compatíveis com algumas mudanças introduzidas nele.

Se você estava curioso para conhecer estes recursos, vem com a gente!

Novidades

Adicione filtros gradualmente

Coleções com muitos filtros podem deixar a barra lateral carregada — sobretudo quando alguns deles só servem de vez em quando. Queríamos um jeito de visitantes (e catalogadores) escolherem quais filtros extras trazer, em vez de sempre ver a lista inteira.

Cada filtro agora tem uma opção de Exibição inicial:

Padrão — o filtro aparece assim que a lista carrega (o comportamento de sempre);
Recolhido — o filtro está lá, mas começa fechado até alguém expandi-lo (substitui a antiga opção de “iniciar recolhido”);
Oculto — o filtro fica fora da barra lateral até a pessoa adicioná-lo.

*Formulário de edição do filtro mostrando o seletor “Exibição inicial” com Padrão, Recolhido e Oculto.*

Quando há pelo menos um filtro oculto, um botão Adicionar filtros aparece no final da busca facetada. Ao abri-lo, a lista mostra os filtros ocultos (agrupados por coleção nas listagens em nível de repositório), e escolher um deles o revela no lugar, pronto para uso. Você não está criando um filtro novo ali — só exibindo um que a coleção já tem.

*Barra lateral da busca facetada com o botão “Adicionar filtros” e o menu dos filtros ocultos.*

Esta é uma boa hora para revisitar suas listas de filtros. Deixe os do dia a dia em Padrão e passe os de uso ocasional para Oculto, para que a primeira impressão da coleção continue focada.

Critérios pré-definidos na Busca Avançada

O modal de Busca Avançada costumava abrir de um jeito bem “frio”: uma única linha vazia, e a tarefa de escolher em qual metadado buscar ainda pela frente. Isso funciona quando se busca só de vez em quando. Funciona menos quando um punhado de campos é o que as pessoas sempre usam.

A opção já existente Oferecer na busca avançada, em cada metadado, agora tem três estados:

Por padrão — o campo já aparece como critério quando o modal abre;
Opcional — continua disponível no seletor de metadados, mas não vem pré-montado (este ainda é o padrão para metadados existentes);
Nunca — não aparece de jeito nenhum na Busca Avançada.

*Formulário de edição do metadado com “Oferecer na busca avançada” em Por padrão / Opcional / Nunca.*

As linhas pré-definidas vazias existem só para poupar um clique. Elas não são enviadas como parâmetros de consulta até que a pessoa de fato preencha um valor, então abrir a Busca Avançada e fechá-la de novo não altera os resultados atuais.

*Modal de Busca Avançada abrindo com algumas linhas de metadados já no lugar, ainda sem valores.*

“Ver mais” nos filtros de checkbox

Filtros de checkbox com mais valores do que o máximo de opções iam direto para um modal de Ver todos. Esse modal continua sendo a ferramenta certa para vocabulários enormes — e segue sendo o caminho para taxonomias hierárquicas, em que é preciso navegar a árvore. Em listas mais “planas” de opções, que só passam um pouco da primeira página, abrir um modal parecia exagero.

Filtros de checkbox (texto e de taxonomia) agora têm Máximo de tentativas de “Ver mais”. Deixe em 0 e nada muda: você só vê Ver todos. Coloque um número maior que zero e o filtro começa oferecendo Ver mais, acrescentando outra página de valores ali mesmo. Depois dessa quantidade de carregamentos, o link vira Ver todos e o modal de sempre assume.

*Um filtro de checkbox na barra lateral com o link “Ver mais” abaixo das últimas opções.*

Opções do filtro de checkbox mostrando “Máximo de tentativas de Ver mais”.

Buscar cada palavra separadamente — por padrão, se você quiser

A busca textual do Tainacan sempre foi uma busca por frase: digitar cadeira de madeira procura essa string inteira. Já existia um controle na interface para mudar para o modo por palavra (um OU entre os termos), com aspas ainda disponíveis para uma frase exata. Alguns usuários nos disseram que queriam esse comportamento por palavra como padrão, e não como um clique a mais.

Na tela de Configurações do plugin, em Busca e desempenho, você encontra Buscar cada palavra separadamente por padrão. Quando está ativada, as buscas consideram cada palavra de forma independente, e a interface continua explicando que aspas mantêm a frase exata. Quem preferir uma constante no servidor pode definir TAINACAN_SEARCH_EACH_WORD_BY_DEFAULT no wp-config.php.

*Configurações do plugin, seção Busca e desempenho, com “Buscar cada palavra separadamente por padrão” marcada.*

Mais formas de preencher um metadado de Seleção

O antigo tipo de metadado Selectbox agora se chama Seleção. Já era útil dentro de metadados Compostos, ou para listas fechadas curtas como Sim/Não. O que faltava era escolher o tipo de entrada: você sempre ganhava um dropdown, mesmo quando duas ou três opções em checkboxes ficariam mais claras.

Há agora uma configuração de Tipo de entrada, parecida com a dos metadados de Taxonomia:

Selectbox — o dropdown original (continua sendo o padrão);
Radio / Checkbox — conforme o metadado permita ou não múltiplos valores;
Botões de seleção — a mesma ideia, apresentada como rádios ou checkboxes em formato de botão.

*Formulário de edição do item com um metadado de Seleção usando botões de rádio ou botões de seleção, ao lado da opção Tipo de entrada.*

Você já sabe como um checkbox fica né? Aqui está um exemplo com os novos “Botões de seleção”:

Melhorias

A seleção no Gutenberg lembra o que você já escolheu

Quando você abria um bloco de Lista de Itens, Carrossel ou Galeria e voltava ao modal de seleção, a lista sempre começava do zero. Os itens já escolhidos vinham desmarcados, e confirmar uma nova seleção podia até duplicar IDs. O modal agora recebe a seleção atual, marca de novo esses itens e substitui a lista do bloco ao aplicar — então desmarcar um item de fato o remove.

Busca textual nas facetas de metadados de Controle

Filtros Autocomplete e Taginput de metadados de Controle (Coleção, Tipo de documento, Possui miniatura e semelhantes) conseguiam buscar os valores armazenados, mas não os rótulos que as pessoas de fato veem. Buscar o nome de uma coleção ou “PDF” nessas facetas agora olha para os rótulos, do mesmo jeito que os filtros de Taxonomia, Relacionamento e Usuário já faziam.

Outras melhorias

Adiciona a opção allowfullscreen nas configurações do documento tipo URL com iframe forçado;
Atualização da biblioteca de gráficos na página de Relatórios, com animações mais suaves e paginação;
Esconde a seção de filtros se todos os filtros internos estiverem ocultos;
Pequenas melhorias de CSS para filtros horizontais;
Correções de strings em inglês, incluindo o aviso de “fewer elements” ao ordenar listas de itens por valor de metadado;
E a costumeira rodada de ajustes internos no código!

Correções de erro

Modais de seleção de itens do Gutenberg falhando no Chrome com o WordPress 7.1. A correção exigiu mudar a forma como essa seleção era comunicada entre os componentes, então se você, como desenvolvedor, já usou nossos iframes de seleção, dê uma olhada na seção para desenvolvedores abaixo.
Abrir um item para edição não dispara mais uma atualização de metadado para campos de Taxonomia vazios e de valor único (o que também gerava registros extras de atividades);
Arquivos CSV salvos em UTF-8 com BOM — o export típico do Excel — agora têm suas colunas especiais (special_item_id, special_document, miniatura, anexos, status etc.) detectadas corretamente. O mesmo tratamento de BOM foi aplicado ao importador CSV de Termos. Obrigado ao Paulo Henrique por reportar isso;
Limpar um mapeamento CSV de volta para “Selecione um metadado” não cria mais um metadado novo nem importa aquela coluna. Obrigado ao Hudson Gomes Arruda por reportar isso;
A Galeria de Itens no frontend falhava ao montar quando continha um slide de vídeo nativo sem um elemento <img> descendente. Obrigado ao Fred Marvilla (Bauhaus Tech) por reportar e corrigir isso!
Estilo do layout em etapas no bloco de Formulário de Submissão de Item, que tinha quebrado após mudanças recentes de classes do Buefy;
Correções de segurança para prevenir injeção de SQL no endpoint de relatórios e nas consultas de relacionamento (reportado pelo Patchstack);

Para desenvolvedores

Agora temos um CONTRIBUTING.md no repositório. Ele cobre o fluxo GitFlow, a nomenclatura de branches e como esperamos que os pull requests cheguem. Se você está entrando no projeto — ou enviando o primeiro patch — comece por ali.

Se você embute a lista de itens do admin no seu próprio iframe, ou reutiliza os módulos React de seleção, duas coisas mudaram com o WordPress 7.1:

Não leia iframe.contentWindow.location. Inscreva-se no BroadcastChannel de seleção. O fluxo está documentado em docs/react-selection-modules.md;
Passe os IDs atuais pela prop existingSelectedItems (ou initiallySelectedItems em location.search, se o iframe for seu). O Apply deve substituir a lista anterior de IDs, não concatená-la.

Tipos de metadado customizados que gerenciam a própria interface de múltiplos valores (adicionar/remover, tag inputs etc.) podem declarar esse contrato em vez de depender de uma lista fixa de componentes no TainacanFormItem. Na classe do tipo de metadado:

$this->set_manage_multiple_input( true );

A flag é exposta em metadata_type_object.manage_multiple_input. O metadado de Seleção a sobrescreve nos tipos de entrada em checkbox, para que um único controle possa ser dono do array inteiro de valores. Taxonomia, Relacionamento, Composto, Usuário e GeoCoordinate já a definem como true.

Outras notas:

O modo padrão de correspondência da busca textual pode ser filtrado com tainacan-default-search-sentence, ou forçado com a constante TAINACAN_SEARCH_EACH_WORD_BY_DEFAULT;
Filtros expõem initial_display (default, collapsed, hidden). O atributo antigo begin_with_filter_collapsed ainda é mapeado para clientes mais antigos, mas código novo deve usar initial_display;
Nosso PHPUnit agora roda em PHP 7.4, 8.3 e 8.4. Obrigado ao Hudson Gomes Arruda pelo trabalho extra de cobertura rumo ao PHP 8.x.

Também adicionamos uma nova seção na Wiki com algumas sugestões para desenvolvimento de plugins para quem quiser estender o Tainacan.

Baixe agora!

A versão 1.3.0 do Tainacan já está disponível para download no repositório de plugins do WordPress:

Tainacan