Tainacan 1.5.0 – Formatted Text, Required Documents and Order by Relevance

Users have asked us for a visual way to add links and basic formatting in long text fields for years. Visitors have asked for search results that put the closest match first. Both land here, together with a collection option to require the item document and a round of API and importer fixes that several of you reported. Site administrators also get a Management Tools screen for heavy maintenance that used to require WP-CLI—starting with the legacy activity-logs migration, which this release makes necessary if you still want the old history in the admin.

If you have been curious about these changes, come join us!

What’s new

A visual way to add links and basic formatting

Textarea metadata, Core Description, and the various description boxes around Tainacan have long allowed a little HTML—bold, italics, and links that were guessed from a bare URL. What they did not allow was writing that HTML without knowing HTML: a labelled link, a bullet list, a second paragraph that stays a paragraph. That request is older than most of the 1.x series.

The plugin Settings screen has a new Input fields section. Turn on Allow formatted text in text inputs and those description fields load a compact toolbar: bold, italic, lists, links, undo/redo, and a source-code dialog.

Settings → Input fields, with “Allow formatted text in text inputs” checked.

Collection, taxonomy, term, metadata, metadata-section, and filter descriptions pick up the editor from that setting. Item text documents do too. Textarea and Core Description stay as they are until you also enable Use formatted text editor on that metadatum—so existing fields do not suddenly change shape. The public Item Submission block keeps a plain textarea; the editor is for the admin forms (including bulk edit).

Collection description with the formatting toolbar, showing a labelled link, italics and bold.
Textarea / Core Description options showing “Use formatted text editor”.

This is not a full page editor: no headings, images, or tables. HTML saved in these fields is included in textual search, so a link in the middle of a sentence can split a phrase match. Use formatted text where links and lists are the point of the field, and leave it off where you still want a clean string for search and character limits.

Require a document before publishing

Metadata can already be marked required. The document—the file, URL, or text that often is the item—could not. Collections that live on a scan, a recording, or a page had to rely on training, or on the Item Submission block with no way to block an empty upload.

Each collection now has a Require document option. When it is on, an item can still be saved as a draft without a document; publishing (and submitting through the Item Submission block) needs an actual file, URL, or text, not only a chosen type. If everfiy document type is disabled on that collection, the option is ignored.

Collection edition form with “Require document” enabled next to the document-type switches.

The item form and the submission block both show the required state and the API’s validation errors in place.

Search results ordered by Relevance

A textual search used to keep whatever sort was already in use—usually creation date. With “search each word separately” and “search all metadata” on, a loose hit in a note and a close hit in the title sat on the same page, in date order. The closest items were not necessarily the first ones.

While the search box has a value and you have not picked another sort, the list now uses WordPress’s Relevance ranking and shows that option in the sort control (admin items list and Faceted Search block). Best match first:

  • the whole phrase in the title;
  • every word in the title;
  • any word in the title;
  • the phrase in the description;
  • everything else—including a match that exists only in other metadata—by creation date.

The automatic switch is not saved as your sort preference. Clearing the search restores the previous order. Choosing Creation date, Title, Modification date, or a custom metadatum replaces Relevance the usual way.

Admin items list with a search term and “Relevance” selected in the sort control.

The setting lives under Search and performance as Order textual search results by relevance (on by default). Sites that use ElasticPress still send orderby=relevance; there the ranking is ElasticPress’s own score, which already includes metadata.

Settings → Search and performance, with “Order textual search results by relevance” checked.

Management Tools, and the legacy logs migration

Activity logs used to live as posts in the wp_posts table, which was bad for performance. A dedicated tainacan_logs table has been available since version 1.1.0, but the plugin still fell back to the old posts unless you defined TAINACAN_USE_DEPRECATED_LOGS as false and ran a WP-CLI migration. Most sites never did that. In 1.5.0 the fallback is gone: logs are always stored and read from the new table. New activities will be fine. The old timeline stays in wp_posts until you migrate it, and the admin will look empty of history until then.

The good news is that you no longer need shell access for that job. Under Other → Management Tools there will be the new maintenance commands. The first made available is Legacy logs migration. Run starts a background process: you can leave the page, follow it on Processes, and reload Management Tools to see the last run again. Already migrated records are skipped, so it is safe to run more than once.

Other → Management Tools, with the “Legacy logs migration” card, Batch size, the purge checkbox, Run, and a process status with progress.

Batch size is how many logs each iteration takes (default 500, max 1000). Check Delete migrated legacy records from wp_posts only after you are happy with the copy: it permanently deletes the old rows, asks for confirmation, and is highlighted as destructive. Take a database backup first. The CLI is still there if you prefer it: wp tainacan logs migrate and wp tainacan logs purge_deprecated.

If your Activity log looks empty after updating to 1.5.0, you probably still have the old posts. Run Legacy logs migration once, without purge. Confirm the history is back, then purge—or leave the old rows alone.

Keep the WordPress toolbar, hide the menu

Tainacan’s Screen Options used to offer two WordPress layouts: the full admin chrome, or none of it. WordPress 7.1 keeps the toolbar in fullscreen editors as the way back to the rest of the admin. Tainacan had no matching middle state.

Under Integration with WordPress Admin UI there are now three radios:

  • Show WordPress menu and toolbar — today’s usual layout;
  • Show WordPress toolbar only — left menu gone, admin bar kept;
  • Hide WordPress navigation — the previous fullscreen mode.
Screen Options on a Tainacan admin page, with “Show WordPress toolbar only” selected.

Improvements

Random order in item list blocks

The Dynamic Items List and Carousel Items List blocks can now shuffle their results. In the block sidebar, turn on Random order when you want a related-items row or a looser showcase rather than a stable sort. The previous order is kept, so you can toggle the option off without rebuilding the query.

Carousel Items List inspector with “Random order” enabled.

Modification date as a default sort

Modification date was already an option in the sort menu. It can now be the default, in the same places as Title and Creation date: the collection’s items-list defaults, the plugin settings for repository and taxonomy-term lists, and the Faceted Search block.

Conditional sections follow the taxonomy tree

A Conditional Metadata Section that watches a hierarchical taxonomy used to look only at the term you stored. If the rule said “Mammals” and the item was filed as “Cats”, the section stayed closed. The check now walks ancestors, so a child term satisfies a parent rule. Terms and facets also expose that ancestor list to the API.

Errors that say what actually failed

Failed admin requests still raise a snackbar, but many of them now pass through the API’s own message instead of a generic status line. Item save shows validation errors (required document, required metadata, the batch terms limit) on the form. Network warnings that duplicated that feedback were dropped.

Other enhancements

  • Stored XSS through taxonomy term names and facet labels: names are no longer HTML-decoded on read, so markup saved by a lower-privileged user cannot run in an administrator’s session;
  • Private / draft videos (and other protected files) honor HTTP byte ranges, so seeking and startup no longer wait for the whole file;
  • REST errors that used to surface as HTTP 500 (“Entities must be validated”, missing report targets, invalid term item_id) now return 400 or 404 with a proper payload;
  • PHP 8.2 / 8.4 deprecations in entities, repositories, and controllers (explicit nullable types, no more dynamic properties);
  • Translated strings with numbered placeholders (%2$s) keep the right variable when a language reorders them; taxonomy checkbox/radio inputs no longer leak event listeners when a modal closes;
  • Developer documentation regenerated, with architecture and OpenAPI notes expanded;
  • And the usual round of internal code tweaks!

Bug fixes

  • Background-process heartbeats are stored in UTC, so the stale-process watchdog no longer re-queues a live import or export on sites behind UTC (Brazil included) and duplicate workers no longer write the same batch twice;
  • CSV importer automatic encoding no longer stores empty strings for Latin-1 / Windows-1252 cells (accented Portuguese, €, curly quotes). Non-UTF-8 values are converted from Windows-1252, which is what spreadsheet exports actually write;
  • Logged-out requests for items of a private collection return 401 instead of a fatal error / HTTP 500;
  • REST order=desc no longer becomes a menu_order = 0 filter, which hid metadata and filters whose menu order was not zero;
  • Facets respect Search each word separately: current_query[sentence]=false is treated as a boolean, so autocomplete / taginput options match the item list instead of the whole phrase;
  • Screen meta hidden in admin iframe mode; filter-area CSS stacking cleared when the filters are not in a modal.

For developers

Formatted text:

  • TAINACAN_ALLOW_RICH_TEXT_EDITOR (boolean) overrides Settings → Input fields → Formatted text and disables the checkbox. Only true enables the editor. The constant name is historical;
  • Textarea and Core Description gain use_rich_text_editor (yes/no, default no), labelled Use formatted text editor in the admin. Stored value is unchanged; value_as_html still runs wpautop() and make_clickable();
  • Metadata_Type::allows_links() is the backend check for keeping anchors. Textarea and Core Description return true. Titles, names, and Plain Text still strip <a> tags (visible text stays). This does not restore links removed by earlier saves.

Search and lists:

  • REST orderby=relevance is a real sort. The default remains date. TAINACAN_DISABLE_SEARCH_RELEVANCE forces the setting off. Facet ID queries skip the ranking;
  • Collection / plugin / Faceted Search defaults accept modified as orderby;
  • Dynamic Items List and Carousel Items List: block attribute randomOrder (data attribute data-random-order). Legacy carousel sort parameters are preserved.

Management Tools:

  • TAINACAN_USE_DEPRECATED_LOGS is removed. Logs always use the tainacan_logs table. Sites that never migrated must run Legacy logs migration (or wp tainacan logs migrate) to see the old history;
  • GET /tainacan/v2/management-tools lists commands and params; POST /tainacan/v2/management-tools/{command} queues a background process and returns bg_process_id. Both require manage_options. Progress is the existing bg-processes route;
  • New commands: add a definition to Management_Tools_Process::get_commands() (name, description, params, steps) and the matching step methods. Management_Tools_Process::queue( $id, $args ) is the PHP entry. The admin screen and REST list are built from that definition;
  • Admin UI option hideNavigationManagementToolsButton hides the menu item.

API and files:

  • Terms and facets now include ancestors. Conditional metadata sections use that path for hierarchical taxonomies;
  • Private file delivery answers satisfiable Range requests with 206 Partial Content. Access checks are unchanged;
  • Collection item_require_document (yes/no). Publish validation requires a document value, not only a type;
  • Reports metadata route argument is metadatum_id (it was the only reports route still named metadata_id). The URL path is the same; only the registered arg name changed;
  • REST order is sort direction, never mapped to menu_order;
  • Background-process processed_last is UTC (current_time( 'mysql', true )).

New contributors

In the latest versions, we’ve received contributions from many new external collaborators. These are the new heroes:

Get it now!

Version 1.5.0 of Tainacan is now available for download from the WordPress plugin repository:

Leave a Reply

Your email address will not be published. Required fields are marked *