"category" Attribute property used inconsistently

Created on 19 November 2024, 5 months ago

Problem/Motivation

As of New API for defining field type categories β†’ , FieldType plugins use the "category" attribute property as a plugin_id, while other core plugins use the "category" property as a translatable string. Because the plugin managers for all these core plugins implement CategorizingPluginManagerInterface, it seems reasonable that they should all treat "category" the same way. But to have it be a translatable string for most plugins but a plugin_id for just FieldType plugins seems wrong, and means that we have to treat categories differently for different types of plugins, yet we have no way to distinguish which type is which because they all implement the same interface and use the same "category" property.

Background:

Categorizing plugins have long used the "category" Annotation key, and now the "category" Attribute property, to specify a translatable string category name used to group plugins of the same type.

For example, in the core UserLoginBlock, the plugin attribute looks like this:

#[Block(
  id: "user_login_block",
  admin_label: new TranslatableMarkup("User login"),
  category: new TranslatableMarkup("Forms")
)]

Note the category is a TranslatableMarkup object. This allows user interfaces to display groups of like plugins under a common, readable, localized name. In this example, the category will show up in the UI along with the admin_label when you "Place blocks" at /admin/structure/block

This is a feature used extensively in contributed modules like Rules, for example to present the user with a selection of e.g. Condition plugins in a select form element grouped by categories.

Steps to reproduce

Use category: new TranslatableMarkup() in a FieldType attribute, just like you would with a Block. Your site will crash and burn when you subsequently try to add a field to a content type, e.g. at /admin/structure/types/manage/page/fields/add-field

Server logs show the error Uncaught PHP Exception TypeError: "Cannot access offset of type Drupal\\Core\\StringTranslation\\TranslatableMarkup in isset or empty" at /.../core/lib/Drupal/Component/Plugin/Discovery/DiscoveryTrait.php line 45

The reason for this error is that FieldType plugins use the "category" as a plugin_id which must be a machine name, not a general string (no spaces, for example), and certainly not a markup object.

Proposed resolution

I don't know. I think we should use the category property the same way for all plugins. And I think categorizing plugins should all work the same way.

Right now only FieldType uses plugin_id, but plugin_id is probably more useful than a string because it is a machine name and we don't have to worry about different capitalizations being considered different categories. But the new field_ui is nice and I don't want to go back, so even if it's a lot more work perhaps we should consider changing all the other plugins to do things like FieldType? That seems like a lot of work, because now we have to have category type plugins (akin to FieldTypeCategory plugins) for each individual plugin type, which is a lot of extra, mostly boilerplate code.

Or perhaps instead of FieldTypeCategory plugins like we have now, maybe just make Category plugins used by ALL categorizing plugin types. I'm not sure why a field-specific solution was introduced here rather than a general-purpose solution for categories.

Categories are really underutilized in core - most core plugins that have categorizing plugin managers don't even bother to define categories, let alone use them. For example, core Action plugins don't ever use the category, even though ActionManager is-a CategorizingPluginManager. Also for example, Block categories aren't utilized in an effective manner, as you can see on the "Place blocks" page. But if we turn the field-specific solution into a general solution, I think it would be a win for UX everywhere.

Looking for thoughts about which direction to take here, before I spend time on an MR.

πŸ› Bug report
Status

Active

Version

11.0 πŸ”₯

Component

field system

Created by

πŸ‡ΊπŸ‡ΈUnited States tr Cascadia

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @tr
  • First commit to issue fork.
Production build 0.71.5 2024