Download the PHP package wieni/wmentity_overview without Composer
On this page you can find all versions of the php package wieni/wmentity_overview. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download wieni/wmentity_overview
More information about wieni/wmentity_overview
Files in wieni/wmentity_overview
Package wmentity_overview
Short Description Improved EntityListBuilders with support for paging, table sorting, table dragging, filtering, bulk actions, database queries and more.
License MIT
Informations about the package wmentity_overview
Entity Overview
Improved EntityListBuilders with support for paging, table sorting, table dragging, filtering, bulk actions, database queries and more.
Why?
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
Installation
This package requires PHP 7.1 and Drupal 8 or higher. It can be installed using Composer:
How does it work?
Create an 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
Example
Override en existing entity listing
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.
Examples
Render an overview
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.
Example
Filter storages
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.
Add bulk actions
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.
Hooks and events
hook_entity_overview_alter
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
Examples
hook_entity_overview_alternatives_alter
This hook is only called in the
OverviewBuilderManager::getAlternatives
method. An event equivalent to the hook is also provided:
WmEntityOverviewEvents::ENTITY_OVERVIEW_ALTERNATIVES_ALTER
Example
Changelog
All notable changes to this project will be documented in the CHANGELOG file.
Security
If you discover any security-related issues, please email [email protected] instead of using the issue tracker.
License
Distributed under the MIT License. See the LICENSE file for more information.