Tainacan 1.5.0 – Texto formatado, Documento obrigatório e ordenação por relevância

Há anos os usuários pedem uma forma visual de colocar links e formatação básica em campos de texto longos. Enquanto isso, visitantes pedem que a busca traga primeiro o resultado mais próximo. Ambas novidades chegam nesta versão, junto com a opção da coleção de exigir o documento do item e uma rodada de correções na API e no importador que várias pessoas reportaram. Administradores do site também ganham a tela de Ferramentas de gerenciamento para manutenções pesadas que antes exigiam WP-CLI — começando pela migração dos logs de atividades legados, que esta versão torna necessária se você ainda quiser o histórico antigo no admin.

Se você está curioso para conhecer estas mudanças, vem com a gente!

Novidades

Uma forma visual de colocar links e formatação básica

Os metadados do tipo área de texto, a Descrição principal e as várias caixas de descrição do Tainacan já aceitavam um pouco de HTML — negrito, itálico e links adivinhados a partir de uma URL crua. O que não dava era pra escrever esse HTML sem saber HTML: um link com rótulo, uma lista com marcadores, um segundo parágrafo que continua parágrafo. Esse é um pedido mais antigo do que a maior parte da série 1.x do Tainacan.

A tela de Configurações do plugin agora tem uma seção nova, Campos de entrada. Ative Permitir texto formatado nos campos de texto e esses campos de descrição passam a carregar uma barra compacta: negrito, itálico, listas, links, desfazer/refazer e um diálogo de código-fonte.

Configurações → Campos de entrada, com “Permitir texto formatado nos campos de texto” marcado.

As descrições de coleção, taxonomia, termo, metadado, seção de metadados e filtro passam a usar o editor a partir dessa configuração. O documento em texto do item também. Metadados tipo Área de texto e Descrição principal continuam como estão até você ativar também Usar editor de texto formatado naquele metadado — assim os campos existentes não mudam de forma de uma hora para outra. O bloco público de Formulário de Submissão de Item segue com uma área de texto simples; o editor vale apenas para os formulários do admin (incluindo a edição em massa).

Descrição da coleção com a barra de formatação, mostrando um link com rótulo, itálicos e negrito.
Opções de Área de texto / Descrição principal mostrando “Usar editor de texto formatado”.

Este recurso não é um editor de página completo: sem títulos, imagens ou tabelas. Em geral não consideramos muito bom poluir suas descrições com conteúdo HTML. O código gravado nesses campos entra na busca textual, então um link no meio de uma frase pode quebrar a correspondência por frase. Use texto formatado onde links e listas são o sentido do campo, e deixe desligado onde você ainda quer uma string limpa para busca e limite de caracteres.

Exigir um documento antes de publicar

No formulário de edição do item, metadados já podiam ser marcados como obrigatórios. O documento — o arquivo, a URL ou o texto que muitas vezes representa o item em si — não. Isso deixava as coleções sem uma forma de barrar um envio vazio.

Agora cada coleção tem a configuração Exigir documento. Quando está ativada, o item ainda pode ser salvo como rascunho sem documento; mas publicar (e enviar pelo bloco de Formulário de Submissão de Item) exige um arquivo, uma URL ou um texto de fato. Se todo tipo de documento estiver desativado naquela coleção, a opção é ignorada.

O formulário de coleção com a opção de Exigir o Documento ao lado dos botões de Tipos de documento habilitados

O formulário do item e o bloco de submissão mostram o estado de obrigatório e os erros de validação da API no lugar.

Resultados da busca ordenados por Relevância

Uma busca textual costumava manter a ordenação que já estava em uso — em geral a data de criação. Com “buscar cada palavra separadamente” e “buscar em todos os metadados” ligados, um acerto parcial em um metadado qualquer e um acerto próximo no título apareciam na mesma página, em ordem de data. Os itens mais próximos não eram necessariamente os primeiros.

Agora, enquanto a caixa de busca tem um valor e você não escolheu outra ordenação, a lista passa a usar o ranking de Relevância do WordPress e mostra essa opção no controle de ordenação (lista de itens do admin e bloco de Busca Facetada). A logica é a de melhor correspondência primeiro:

  1. a frase inteira no título;
  2. todas as palavras no título;
  3. qualquer palavra no título;
  4. a frase na descrição;
  5. todo o resto — inclusive um acerto que existe só em outros metadados — pela data de criação.

A troca automática não é salva como sua preferência de ordenação. Limpar a busca restaura a ordem anterior. Escolher Data de criação, Título, Data de modificação ou um metadado personalizado substitui a Relevância do jeito de sempre.

Lista de itens no admin com um termo de busca e “Relevância” selecionada no controle de ordenação.

A configuração fica em Busca e desempenho, como Ordenar resultados da busca textual por relevância (ativa por padrão). Sites que usam ElasticPress ainda enviam orderby=relevance; aí o ranking é o score do próprio ElasticPress, que já inclui metadados.

Configurações → Busca e desempenho, com “Ordenar resultados da busca textual por relevância” marcado.

Ferramentas de gerenciamento e a migração dos logs legados

Os registros de atividades viviam como posts na tabela wp_posts, o que era ruim para desempenho. Uma tabela dedicada tainacan_logs está disponível desde a versão 1.1.0, mas o plugin ainda recaía nos posts antigos a menos que você definisse no servidor TAINACAN_USE_DEPRECATED_LOGS como false e rodasse a migração via WP-CLI. A maioria dos sites nunca fez isso. Na versão 1.5.0 este fallback some: os logs são sempre gravados e lidos na tabela nova. Atividades novas ficam onde esperado. A linha do tempo antiga permanece na wp_posts até você migrá-la, e o admin pode parecer vazio de histórico até lá.

A boa notícia é que você não precisa mais de acesso ao terminal do servidor para esse trabalho. Em Outros → Ferramentas de gerenciamento estarão os novos comandos de manutenção. O primeiro disponibilizado é Migração dos logs legados. Clicando em Executar ele inicia um processo em segundo plano: você pode sair da página, acompanhar em Processos e recarregar Ferramentas de gerenciamento para ver de novo a última execução. Registros já migrados são ignorados, então é seguro rodar mais de uma vez.

Outros → Ferramentas de gerenciamento, com o card “Migração dos logs legados”, Tamanho do lote, a caixa de exclusão, Executar e o status do processo com progresso.

A opção Tamanho do lote indica quantos logs cada iteração processa (padrão 500, máximo 1000). Marque Excluir registros legados já migrados da wp_posts só depois de estar satisfeito com a cópia: isso apaga em definitivo as linhas antigas, pede confirmação e aparece destacado como destrutivo. Faça um backup do banco antes. O comando da CLI continua disponível se você preferir: wp tainacan logs migrate e wp tainacan logs purge_deprecated.

Se o Registro de atividades parecer vazio depois de atualizar para a 1.5.0, você provavelmente ainda tem os posts antigos. Rode a Migração dos logs legados uma vez, sem excluir. Confirme que o histórico voltou e só então exclua — ou deixe as linhas antigas quietas.

Manter a barra do WordPress, esconder o menu

As Opções de tela do Tainacan ofereciam dois layouts do WordPress: a interface administrativa inteira, ou nada dela. O WordPress 7.1 mantém a barra de ferramentas nos editores em tela cheia como caminho de volta para o resto do admin. O Tainacan não tinha um estado do meio correspondente.

Em Integração com a interface administrativa do WordPress agora há três opções:

  • Mostrar menu e barra de ferramentas do WordPress — o layout de sempre;
  • Mostrar apenas a barra de ferramentas do WordPress — menu da esquerda some, a barra de admin fica;
  • Ocultar a navegação do WordPress — o modo tela cheia anterior.
Opções de tela numa página admin do Tainacan, com “Mostrar apenas a barra de ferramentas do WordPress” selecionado.

Melhorias

Ordem aleatória nos blocos de lista de itens

Os blocos Lista Dinâmica de Itens da Coleção e Carrossel de Itens agora podem embaralhar os resultados. Na barra lateral do bloco, ligue Ordem aleatória quando quiser uma fileira de itens relacionados ou uma vitrine mais solta, em vez de uma ordenação estável. A ordenação anterior é guardada, então você pode desligar a opção sem remontar a consulta.

Inspetor do Carrossel de Itens com “Ordem aleatória” ativada.

Data de modificação como ordenação padrão

Data de modificação já era uma opção no menu de ordenação. Agora pode ser o padrão, nos mesmos lugares que Título e Data de criação: os padrões da lista de itens da coleção, as configurações do plugin para listas do repositório e de termos de taxonomia, e o bloco de Busca Facetada.

Seções condicionais seguem a árvore da taxonomia

Uma Seção Condicional de Metadados que observa uma taxonomia hierárquica olhava só para o termo gravado. Se a regra dizia “Mamíferos” e o item estava em “Gatos”, a seção continuava fechada. A verificação agora sobe pelos ancestrais, então um termo filho satisfaz a regra do pai. Termos e facetas também expõem essa lista de ancestrais na API.

Erros que dizem o que de fato falhou

Requisições que falham no admin ainda disparam uma notificação no canto inferior direito, mas muitas agora passam a mensagem da própria API em vez de uma linha genérica de status. Ao salvar o item, os erros de validação (documento obrigatório, metadado obrigatório, limite de termos em lote) aparecem no formulário. Os avisos de rede que duplicavam esse retorno foram retirados.

Outras melhorias

  • Problema de XSS armazenado via nomes de termos de taxonomia e rótulos de facetas: os nomes deixam de ser decodificados como HTML na leitura, então marcação gravada por um usuário com menos privilégio não executa na sessão de um administrador;
  • Vídeos privados / rascunho (e outros arquivos protegidos) respeitam intervalos de bytes HTTP, então buscar um ponto no vídeo e o início da reprodução não esperam mais o arquivo inteiro;
  • Erros REST que apareciam como HTTP 500 (“Entities must be validated”, alvos de relatório inexistentes, item_id de termo inválido) agora devolvem 400 ou 404 com um payload adequado;
  • Depreciações de PHP 8.2 / 8.4 em entidades, repositórios e controladores (tipos anuláveis explícitos, sem propriedades dinâmicas);
  • Strings traduzidas com placeholders numerados (%2$s) mantêm a variável certa quando o idioma reordena; inputs de taxonomia em checkbox/radio não vazam mais ouvintes de evento ao fechar um modal;
  • Documentação para desenvolvedores regenerada, com notas de arquitetura e OpenAPI ampliadas;
  • E a rodada de sempre de ajustes internos de código!

Correções de erro

  • Os heartbeats dos processos em segundo plano são gravados em UTC, então o watchdog de processos parados não recoloca mais na fila um import ou export vivo em sites atrás do UTC (Brasil inclusive) e workers duplicados não escrevem mais o mesmo lote duas vezes;
  • A codificação automática do importador CSV não grava mais strings vazias para células Latin-1 / Windows-1252 (português com acento, €, aspas curvas). Valores que não são UTF-8 são convertidos a partir de Windows-1252, que é o que as planilhas de fato exportam;
  • Pedidos deslogados de itens de uma coleção privada devolvem 401 em vez de um erro fatal / HTTP 500;
  • O order=desc da REST não vira mais um filtro menu_order = 0, que escondia metadados e filtros cujo menu order não era zero;
  • As facetas respeitam Buscar cada palavra separadamente: current_query[sentence]=false é tratado como booleano, então as opções de autocomplete / taginput acompanham a lista de itens em vez da frase inteira;
  • Screen meta oculto no modo iframe do admin; empilhamento CSS da área de filtros limpo quando os filtros não estão num modal.

Para desenvolvedores

Texto formatado:

  • TAINACAN_ALLOW_RICH_TEXT_EDITOR (booleano) sobrescreve Configurações → Campos de entrada → Texto formatado e desativa a caixa. Só true liga o editor. O nome da constante é histórico;
  • Área de texto e Descrição principal ganham use_rich_text_editor (yes/no, padrão no), rotulado Usar editor de texto formatado no admin. O value armazenado não muda; value_as_html continua rodando wpautop() e make_clickable();
  • Metadata_Type::allows_links() é a checagem no backend para manter âncoras. Área de texto e Descrição principal retornam true. Títulos, nomes e Texto simples ainda removem as tags <a> (o texto visível fica). Isso não restaura links tirados em gravações anteriores.

Busca e listagens:

  • O orderby=relevance da REST é uma ordenação de verdade. O padrão continua date. TAINACAN_DISABLE_SEARCH_RELEVANCE força a configuração desligada. Consultas de faceta por ID pulam o ranking;
  • Os padrões da coleção / plugin / Busca Facetada aceitam modified como orderby;
  • Lista Dinâmica de Itens e Carrossel de Itens: atributo do bloco randomOrder (atributo de dados data-random-order). Parâmetros de ordenação antigos do carrossel são preservados.

Ferramentas de gerenciamento:

  • TAINACAN_USE_DEPRECATED_LOGS foi removida. Os logs usam sempre a tabela tainacan_logs. Sites que nunca migraram precisam rodar a Migração dos logs legados (ou wp tainacan logs migrate) para ver o histórico antigo;
  • GET /tainacan/v2/management-tools lista comandos e parâmetros; POST /tainacan/v2/management-tools/{command} enfileira um processo em segundo plano e devolve bg_process_id. Os dois exigem manage_options. O progresso é a rota já existente de bg-processes;
  • Comandos novos: acrescente uma definição em Management_Tools_Process::get_commands() (name, description, params, steps) e os métodos de passo correspondentes. Management_Tools_Process::queue( $id, $args ) é a entrada em PHP. A tela admin e a listagem REST são montadas a partir dessa definição;
  • A opção de UI do admin hideNavigationManagementToolsButton esconde o item de menu.

API e arquivos:

  • Termos e facetas agora incluem ancestors. Seções condicionais de metadados usam esse caminho para taxonomias hierárquicas;
  • A entrega de arquivos privados responde a pedidos Range satisfazíveis com 206 Partial Content. As checagens de acesso não mudam;
  • A coleção tem item_require_document (yes/no). A validação ao publicar exige um valor de documento, não só um tipo;
  • O argumento de rota dos relatórios de metadado é metadatum_id (era a única rota de relatórios ainda chamada metadata_id). O caminho da URL é o mesmo; só o nome do argumento registrado mudou;
  • O order da REST é direção de ordenação, nunca mapeado para menu_order;
  • O processed_last dos processos em segundo plano é UTC (current_time( 'mysql', true )).

Novos contribuidores

Nas últimas versões, temos recebido contribuições de diversos colaboradores externos. Estes são os novos heróis:

Baixe agora!

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

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *