Improved EntityListBuilders with support for paging, table sorting, table dragging, filtering, bulk actions, database queries and more.
At Wieni, we're not a big fan of the Views module and for a couple of reasons:
- we're programmers, we don't like to create functionality by clicking through the Drupal interface and especially not the bloated Views interface
- we prefer to write our own database or entity queries, it gives us more flexibility when filtering and including non-entity field data and it makes it easier to optimize queries
That's why a couple of years ago we decided to disable the module altogether and we ended up with the EntityListBuilder based listings.
Those proved to be lacking in functionality and user friendliness soon enough, which is how we ended up creating this module: the perfect middle ground between Views and EntityListBuilder. It offers all features of the latter, plus the following:
- Exposed filtering with a custom form
- Behind-the-scenes filtering using custom database queries
- Table sorting, configurable on a per-column basis
- Bulk actions using core Action plugins
- Override built-in entity listings with a custom one, on an entity type or bundle level
- Override any route with a custom entity listing
This package requires PHP 7.1 and Drupal 8 or higher. It can be installed using Composer:
composer require wieni/wmentity_overview
Overviews are Drupal plugins with the
@OverviewBuilder
annotation.
Every annotation needs at least the entity_type
and id
parameters to
function.
There are three base classes you can choose from:
OverviewBuilderBase
: the most basic entity overview with support for database queries, paging and table sortFilterableOverviewBuilderBase
: an entity overview combining the base functionality with an exposed filter formDraggableOverviewBuilderBase
: an entity overview with a draggable, re-orderable table, but without support for paging or filtering
<?php
namespace Drupal\yourmodule\Plugin\EntityOverview;
/**
* @OverviewBuilder(
* entity_type = "node",
* )
*/
class NodeOverview extends FilterableOverviewBuilderBase
{
}
You can override the default entity listing with a custom overview by
adding the override
parameter to the annotation. In case the entity
type is not recognised by this module, you can add the route_name
and
pass the route name of the entity listing instead.
It is also possible to override the entity listing only when a certain combination of filters is active. This way, you could for example add extra filters or table columns when your overview is filtered by a certain bundle.
<?php
namespace Drupal\yourmodule\Plugin\EntityOverview;
/**
* @OverviewBuilder(
* id = "node",
* entity_type = "node",
* override = true,
* )
*/
class NodeOverview extends FilterableOverviewBuilderBase
{
}
<?php
namespace Drupal\yourmodule\Plugin\EntityOverview;
/**
* @OverviewBuilder(
* id = "redirect",
* entity_type = "redirect",
* route_name = "redirect.list",
* )
*/
class RedirectOverview extends FilterableOverviewBuilderBase
{
}
<?php
namespace Drupal\yourmodule\Plugin\EntityOverview;
/**
* @OverviewBuilder(
* id = "node.article",
* entity_type = "node",
* override = true,
* filters = {
* "type" = "article",
* },
* )
*/
class ArticleOverview extends NodeOverview
{
}
When you create an overview without overriding an existing route, you will have to render it somewhere manually.
Creating an instance of an entity overview is done the same way as other
Drupal plugins, by using the createInstance
method of
OverviewBuilderManager
.
Another option is adding _entity_overview
to the defaults
section of
your route definition, with as value the plugin id.
yourmodule.content_overview.article:
path: '/admin/content/article'
defaults:
_entity_overview: 'node.article'
_title: 'Articles'
requirements:
_permission: 'administer nodes'
options:
_admin_route: TRUE
Entity overviews with exposed filter forms need a place to (temporarily) store their filter values. That's where filter storages come to play: an abstraction in the way these values are stored.
By default, two storage methods are included: query
, which stores
values as query parameters in the URL and session
, which stores values
in the session storage.
Custom storage methods can be added by creating a Drupal plugin with the
@FilterStorage
annotation and an
id
parameter, implementing
FilterStorageInterface
and optionally extending
FilterStorageBase
.
The default storage method is query
, but this can be changed by adding
a filter_storage
parameter to @OverviewBuilder
annotations.
Bulk actions can be added to your overview by implementing
BulkActionOverviewBuilderInterface
and the getBulkActionPlugins
method. This method can return two kinds of arrays:
- an associative array with the plugin IDs as keys and the labels as values
- a flat array with plugin ID's
In the last case the default plugin labels will be used.
It is possible to attach a configuration form to your action plugin by implementing
PluginFormInterface
.
In case you need access to the entities in your form validate and/or submit handlers, you can implement
ActionPluginFormInterface
instead. Note that in contrary to
PluginFormInterface
this is a custom interface, only supported by this module.
This hook is only called when using overrides or when using the
_entity_overview
default in routes. An event equivalent to the hook is
also provided:
WmEntityOverviewEvents::ENTITY_OVERVIEW_ALTER
<?php
use Drupal\wmentity_overview\Annotation\OverviewBuilder;
function yourmodule_entity_overview_alter(OverviewBuilder $definition, array &$overview)
{
if (!empty($overview['form'])) {
$overview['form']['#attributes']['class'][] = 'custom-entity-overview__form';
}
$overview['table']['#attributes']['class'][] = 'custom-entity-overview__table';
}
<?php
namespace Drupal\yourmodule\EventSubscriber;
use Drupal\wmentity_overview\Event\EntityOverviewAlterEvent;
use Drupal\wmentity_overview\WmEntityOverviewEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
class EntityOverviewSubscriber implements EventSubscriberInterface
{
public static function getSubscribedEvents()
{
$events[WmEntityOverviewEvents::ENTITY_OVERVIEW_ALTER][] = ['onAlter'];
return $events;
}
public function onAlter(EntityOverviewAlterEvent $event): void
{
$overview = &$event->getOverview();
if (!empty($overview['form'])) {
$overview['form']['#attributes']['class'][] = 'custom-entity-overview__form';
}
$overview['table']['#attributes']['class'][] = 'custom-entity-overview__table';
}
}
This hook is only called in the
OverviewBuilderManager::getAlternatives
method. An event equivalent to the hook is also provided:
WmEntityOverviewEvents::ENTITY_OVERVIEW_ALTERNATIVES_ALTER
<?php
namespace Drupal\yourmodule\EventSubscriber;
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\wmentity_overview\Event\EntityOverviewAlternativesAlterEvent;
use Drupal\wmentity_overview\OverviewBuilder\OverviewBuilderManager;
use Drupal\wmentity_overview\WmEntityOverviewEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
class EntityOverviewAlternativesSubscriber implements EventSubscriberInterface
{
/** @var OverviewBuilderManager */
protected $overviewBuilders;
/** @var RouteMatchInterface */
protected $routeMatch;
public function __construct(
OverviewBuilderManager $overviewBuilders,
RouteMatchInterface $routeMatch
) {
$this->overviewBuilders = $overviewBuilders;
$this->routeMatch = $routeMatch;
}
public static function getSubscribedEvents()
{
$events[WmEntityOverviewEvents::ENTITY_OVERVIEW_ALTERNATIVES_ALTER][] = ['onTaxonomyAlternativesAlter'];
return $events;
}
/**
* Since taxonomy has a per-bundle overview, we get the bundle from
* the route parameters and use it to add more possible alternatives.
*/
public function onTaxonomyAlternativesAlter(EntityOverviewAlternativesAlterEvent $event): void
{
if (!$vocabulary = $this->routeMatch->getParameter('taxonomy_vocabulary')) {
return;
}
if ($event->getDefinition()->getEntityTypeId() !== 'taxonomy_term') {
return;
}
$filters = ['vid' => $vocabulary->id()];
$alternatives = array_merge(
$event->getAlternatives(),
$this->overviewBuilders->getAlternativesByFilters($event->getDefinition(), $filters)
);
$event->setAlternatives($alternatives);
}
}
All notable changes to this project will be documented in the CHANGELOG file.
If you discover any security-related issues, please email [email protected] instead of using the issue tracker.
Distributed under the MIT License. See the LICENSE file for more information.