Introducing Tainacan 1.0 – Part 2: Plugin Settings Screen and Appearance Adjustments per User Role

This is the second in a series of four pre-release articles covering the new features in Tainacan 1.0.0. Be sure to read the other three:

In this article, we’ll focus on one of the most relevant aspects of version 1.0.0: customization. In the previous post, we showed how users can modify their dashboard to fit their own navigation preferences. Now, we’ll turn our attention to repository managers and administrators who want more control over how the plugin behaves and how its features reach users. We’ll explore this through two new features: the Plugin Settings Screen and the new Appearance Adjustments by User Role options.

New Plugin Settings Screen

Since the early versions of Tainacan, we’ve often faced difficult decisions about how certain features and parameters should behave. We know that every WordPress installation can run on a different server, with themes and plugins we’ve never seen before — many of which may alter the system’s behavior. To give control over these decisions to those who truly manage their installations, we’re finally introducing a dedicated settings screen for the plugin.

Some of the options available here already existed as PHP constants, configurable only by editing server files. Now, we’re making these options visually accessible — and opening the door for many new settings to come.

To get started, open the unified menu at: Tainacan → Others → Settings:

As you’ll see, the screen is divided into several sections. We’ll describe each of them below, but for more details, check out our documentation on the Wiki.

Search and Performance

This section includes options that can impact your server’s response time and performance — use them carefully.

  • Search results per page: By default, every paginated search in Tainacan has a maximum number of results. Although most item/collection/taxonomy lists display 12 entries per page, you can usually increase this number via the interface or the URL. However, even despite API or URL parameters, the limit will never exceed the value defined here. For example, in the Exposers modal (“View as…”), the pagination is based on this number.
  • PDF content: When enabled, Tainacan will attempt to index the textual content of PDF files for search results. Indexing happens when the item is updated and depends on specific server configurations. See the documentation page for more information about PDF indexing.
  • Textual search fields: When enabled, full-text search includes all textual metadata fields. This extends WordPress’ default behavior — at the cost of performance. Disabling this will restrict search to title and description fields only.
  • Dynamic filter values: Whenever a filter is applied in faceted search, other filters reload and narrow their options accordingly. This “narrowing” behavior helps refine results but may slow performance. Disable it to keep all filter options visible, even if selecting some may yield empty results.
  • Facet count: Defines whether filters in faceted search should display a count beside each option (indicating how many items have that value). This can be expensive to compute before a search is applied.

Default Theme Templates

This section contains options related to theme compatibility. If your theme doesn’t implement its own Tainacan templates, you can enable these options to override the WordPress defaults. Keep in mind that the plugin knows nothing about your theme’s CSS classes, container sizes, or design — it aims to stay generic while still providing the expected functionality. Additional customization may require at least some CSS knowledge.

  • Item page: Replaces the standard WordPress single post template with a Tainacan item layout, including the document viewer, metadata, and attachments.
  • Collection items page: Replaces the default blog archive with a faceted search view showing items, filters, and display modes for that collection.
  • Taxonomy term items page: Replaces the default blog archive with a faceted search for items linked to that taxonomy term.
  • Repository items page: Replaces the blog archive with a faceted search view showing all repository items.
  • Taxonomy terms page: Replaces the default single post template with a basic list of taxonomy terms, including links to child terms and items, with basic sorting and search options.

Default List Options for Theme

This section defines default behavior for item lists displayed in repository and collection pages. These can be overridden by user preferences, collection settings, or theme options.

  • Display mode: Default view mode for items.
  • Enabled display modes: Which view modes are globally available to users.
  • Order by: Default sorting criterion.
  • Order: Default sorting direction.

Item Submission Forms with reCAPTCHA

This section allows you to configure Google reCAPTCHA for better security when using the Item Submission block. Before version 1.0.0, this setting was accessible through a submenu under the Tainacan admin menu — it now lives in this new unified settings page.

  • Google reCAPTCHA Secret Key
  • Google reCAPTCHA Site Key

Appearance Adjustments by User Role

The settings available in the Plugin Settings screen affect all users. However, some adjustments may be desirable depending on the user’s role. This type of customization already exists and can be accessed via: Tainacan → Others → User Roles, then selecting a role. Until now, all the options in that section were related to permissions — what a user can see or do, either across the whole repository or within specific collections. But sometimes permissions alone aren’t enough.

For example, an Author might not have permission to edit taxonomies, yet still needs to see them in the admin interface to select terms in related metadata. Tainacan disables the editing actions (like hiding edit buttons), but doesn’t hide the Taxonomies menu altogether, since the user can still view public taxonomies. This is a case where you might want to hide that option purely for appearance reasons — to keep the interface cleaner.

With that in mind, we’ve introduced a new tab in the user role configuration form: “Admin Appearance.”

This new tab allows you to tailor the Tainacan admin interface to simplify navigation, reduce clutter, or visually restrict access to certain areas of the system. There are dozens of options, organized by theme:

  • Navigation: Fine-grained control over each sidebar item and display mode (fullscreen layout, breadcrumbs, quick-access buttons, etc.).
  • Dashboard: Choose which cards appear on the home screen — such as collections, news, or metrics — and restrict them by authorship or editing permission.
  • Item List: Adjust the search and list interface, hiding filters, bulk actions, or advanced options.
  • Item Editing and Viewing: Customize the editing form and viewing pages, deciding which sections or fields should appear. You can even switch to a tabbed layout for item editing with just a few clicks.

These options allow you to create cleaner and safer experiences for different user profiles — for example, showing only the essentials for content editors or limiting navigation for restricted users.

For a full list of available options, see our documentation on the Wiki.

Wait, there’s more!

Be sure to read the other articles covering the new features in the 1.0 release:

Leave a Reply

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

Related Posts