In Drupal 11.3, core introduces an important structural change for the taxonomy system:Drupal\taxonomy\Form\OverviewTerms now extends Drupal\Core\Entity\EntityForm.
This update modernizes the taxonomy UI, makes the overview form fully consistent with other entity-based forms, and—most importantly—gives developers a cleaner and more powerful way to customize and override it.
In this article, we’ll walk through the change, why it matters, and how you can override the form in your own module.
🚀 What Changed?
Previously, the Overview Terms form for taxonomy vocabularies was a standalone form class with limited extensibility.
Before Drupal 11.3
- The route used
_form. - Developers had to override the route or use complex router_alter hacks to replace the form.
Starting in Drupal 11.3
OverviewTerms now extends EntityForm:
class OverviewTerms extends EntityForm
This brings the taxonomy overview UI into alignment with the rest of Drupal’s entity system.
🔧 Route Update
To support the new EntityForm behavior, the route definition has been updated.
Old definition
$route->setDefault('_form', 'Drupal\taxonomy\Form\OverviewTerms');
New definition
$route->setDefault('_entity_form', 'taxonomy_vocabulary.overview');
The taxonomy vocabulary entity now exposes an “overview” entity form mode, just like “edit” or “delete”.
🎯 Why This Matters
This change brings several benefits:
✔ Consistency
All taxonomy vocabulary forms now follow the EntityForm structure.
✔ Cleaner Overrides
Developers can override the form using hook_entity_type_alter() instead of router hacks.
✔ Better Extensibility
You gain access to:
- form actions,
- validation & submission within EntityForm,
- dependency injection via services,
- shared patterns with other entity forms.
✔ Future-Proof Code
This aligns taxonomy with Drupal’s evolving OOP-first, attribute-driven architecture.
🛠 How to Override the Taxonomy Overview Form
Instead of rewriting routes, you can now override the form cleanly using setFormClass().
Example: Override the Overview Form
In your module:
function my_module_entity_type_alter(array &$entity_types) {
if (isset($entity_types['taxonomy_vocabulary'])) {
$entity_types['taxonomy_vocabulary']->setFormClass('overview', 'Drupal\my_module\MyOverviewTerms');
}
}
Then extend the core class:
namespace Drupal\my_module;
use Drupal\taxonomy\Form\OverviewTerms;
class MyOverviewTerms extends OverviewTerms {
// Add your customizations here.
}
🧩 Example Use Cases
With this change, extending the taxonomy overview becomes much easier. Some practical examples include:
🔹 Adding new columns to the terms overview table
(e.g., a “custom field” or node usage count)
🔹 Adding custom actions to the form
(e.g., “Export to CSV”)
🔹 Adding new UI elements
(e.g., filtering terms with custom logic)
🔹 Integrating with external services
(e.g., syncing taxonomy terms with a third-party API)
🔹 Replacing the entire layout
(e.g., building a React-powered enhanced taxonomy UI)
📦 Sample Module: Add a Custom Column
Here’s a simplified example of adding a custom column to the terms list:
class MyOverviewTerms extends OverviewTerms {
public function buildForm(array $form, FormStateInterface $form_state) {
$form = parent::buildForm($form, $form_state);
$form['terms']['#header']['custom'] = $this->t('Custom');
foreach ($form['terms'] as $tid => &$row) {
if (is_numeric($tid)) {
$row['custom'] = [
'#markup' => '<em>My custom data</em>',
];
}
}
return $form;
}
}
This is now the standard approach—compatible with Drupal 11.3 and future versions.
🧭 Final Thoughts
The change to make OverviewTerms an EntityForm is small but impactful.
It modernizes a part of core that had remained unchanged for years and finally gives developers a clean, supported way to enhance or replace taxonomy overview behavior.
If your module interacts with taxonomy vocabularies, or you maintain custom backend management UIs, updating to this new pattern will keep your code aligned with Drupal’s direction.
Comments