https://github.com/wieni/wmentity_overview

Improved EntityListBuilders with support for paging, table sorting, table dragging, filtering, database queries and more.
https://github.com/wieni/wmentity_overview

drupal-module drupal8 drupal8-module entity-api

Last synced: 3 months ago
JSON representation

Improved EntityListBuilders with support for paging, table sorting, table dragging, filtering, database queries and more.

• Host: GitHub
• URL: https://github.com/wieni/wmentity_overview
• Owner: wieni
• License: mit
• Created: 2020-01-30T10:09:30.000Z (almost 5 years ago)
• Default Branch: main
• Last Pushed: 2024-03-18T09:11:10.000Z (10 months ago)
• Last Synced: 2024-09-28T10:40:13.938Z (3 months ago)
• Topics: drupal-module, drupal8, drupal8-module, entity-api
• Language: PHP
• Size: 69.3 KB
• Stars: 1
• Watchers: 5
• Forks: 1
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
Entity Overview

======================

[![Latest Stable Version](https://poser.pugx.org/wieni/wmentity_overview/v/stable)](https://packagist.org/packages/wieni/wmentity_overview)

[![Total Downloads](https://poser.pugx.org/wieni/wmentity_overview/downloads)](https://packagist.org/packages/wieni/wmentity_overview)

[![License](https://poser.pugx.org/wieni/wmentity_overview/license)](https://packagist.org/packages/wieni/wmentity_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](https://www.drupal.org/docs/8/core/modules/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](https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Entity%21EntityListBuilder.php/class/EntityListBuilder/8.2.x) 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](https://www.drupal.org/node/2020549)

- **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:

```bash

 composer require wieni/wmentity_overview

```

## How does it work?

### Create an overview

Overviews are Drupal plugins with the

[`@OverviewBuilder`](src/Annotation/OverviewBuilder.php) annotation.

Every annotation needs at least the `entity_type` and `id` parameters to

function.

There are three base classes you can choose from:

- [`OverviewBuilderBase`](src/OverviewBuilder/OverviewBuilderBase.php): the most basic entity overview with support

  for database queries, paging and table sort

- [`FilterableOverviewBuilderBase`](src/OverviewBuilder/FilterableOverviewBuilderBase.php):

  an entity overview combining the base functionality with an exposed

  filter form

- [`DraggableOverviewBuilderBase`](src/OverviewBuilder/DraggableOverviewBuilderBase.php):

  an entity overview with a draggable, re-orderable table, but without

  support for paging or filtering

#### Example

```php

getOverview();

        if (!empty($overview['form'])) {

            $overview['form']['#attributes']['class'][] = 'custom-entity-overview__form';

        }

    

        $overview['table']['#attributes']['class'][] = 'custom-entity-overview__table';

    }

}

```

#### `hook_entity_overview_alternatives_alter`

This hook is only called in the

[`OverviewBuilderManager::getAlternatives`](src/OverviewBuilder/OverviewBuilderManager.php)

method. An event equivalent to the hook is also provided:

[`WmEntityOverviewEvents::ENTITY_OVERVIEW_ALTERNATIVES_ALTER`](src/WmEntityOverviewEvents.php)

#### Example

```php

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);

    }

}

```

## Changelog

All notable changes to this project will be documented in the

[CHANGELOG](CHANGELOG.md) file.

## Security

If you discover any security-related issues, please email

[[email protected]](mailto:[email protected]) instead of using the issue

tracker.

## License

Distributed under the MIT License. See the [LICENSE](LICENSE.md) file

for more information.