Hyvä Admin

This module aims to make creating grids and forms in the Magento 2 adminhtml area joyful and fast.
It does not use any UI components. Status:

They came round the corner, and there was Eeyore's
house, looking as comfy as anything.
"There you are," said Piglet.
"Inside as well as outside," said Pooh proudly.
Eeyore went inside . . . and came out again.
"It's a remarkable thing," he said. "It is my house,
and I built it where I said I did, so the wind must have blown
it here. And the wind blew it right over the wood, and blew it
down here, and here it is as good as ever. In fact, better in
places."
"Much better," said Pooh and Piglet together.
"It just shows what can be done by taking a little
trouble," said Eeyore. "Do you see, Pooh? Do you see, Piglet?
Brains first and then Hard Work. Look at it! That's the way to
build a house," said Eeyore proudly.

• Alan Alexander Miln, "The house at Pooh Corner"

Overview

Hyva_Admin is a Magento 2 module that offers a new way to create admin grids.
All existing grids and forms are not affected. They remain unchanged.
Hyva_Admin exists to improve the developer experience while creating new grids.

In the future, Hyva_Admin will support creating forms, too (this issue tracks progress).

Relationship with frontend Hyvä-Themes

This module does not require using a Hyva-Theme for a store front. It is an independent module.
It only shares three things with the Hyvä frontend theme:

• the idea that development should be enjoyable
• the framework should support developers instead of creating more work than necessary
• it uses tailwind css and alpinejs under the hood, but you will probably never even notice when using Hyva_Admin

You can install this module and enjoy it without having a Hyvä-Themes license.
That said, I really recommend you get a store front Hyvä license, and make work there enjoyable and fast, too.

Rationale

When using the Magento 2 UI Components to create admin grids and forms, I always felt like I was dying a bit inside. From my point of view it's an awful system for a number of reasons that I don't want to go into more details about here.
Alternative store fronts that do not use UI components (PWA Studio, Hyva Themes) are great for frontend developers, but (un?)fortunately I mostly do backend work. The UI interfaces I create are mostly for store owners and admins.

I desire a way to do my job (which includes building grids and forms) that doesn't feel like I have to fight the framework.
I want to feel empowered and get work done quickly and efficiently.
After years of bitching about Magento, I was very impressed by the work Willem Wigman has done with the Hyvä frontend theme.
He inspired me to stop complaining and also take matters into my own hands, and finally build the tools I desire.
Hence, Hyva_Admin.

Installation

The module can be installed via composer by adding the repository as a source and then requiring it:

composer require hyva-themes/module-magento2-admin

If you want to just play around to get a feel for Hyva_Admin grids, you can install a test module that declares an example grid, too:

composer require hyva-themes/module-magento2-admin-test

Requirements

It should work with pretty much any Magento 2 version, as long as the $escaper is assigned in templates.

Quickstart

Note: Both an overview with a step by step walkthrough and an API reference can be found in the docs folder.

Once installed, grids can be added to any admin page by adding a bit of layout XML and a grid configuration file.
The layout XML has to contain two things:

• A <update handle="hyva_admin_grid"/> declaration to load alpine.js and tailwind.
• A Hyva\Admin\Block\Adminhtml\HyvaGrid block, with name of the grid configuration as a block argument (or as the block name-in-layout).

After that, a grid configuration has to be created in a directory [Your_Module]/view/adminhtml/hyva-grid, where the
file names corresponds to the name that was passed to the grid block (with a .xml suffix added to the file name).

The grid configuration will need contain a grid source specification. Currently that can be a repository list method, or a
\Hyva\Admin\Api\HyvaGridArrayProviderInterface implementation.

With no further configuration, all fields of the provided records are shown as grid columns.
It's then possible to either exclude columns as needed, or, alternatively, specify an include-list for the columns to display.
In many cases the default will be good enough and no further configuration beyond the grid source will be necessary.

Grid row actions, mass actions, paging and filtering can also be configured as needed.

More information can be found in the Hyva Admin documentation.

Stability

The module isn’t feature complete.
However, the API will remain stable, unless some real flaw is discovered.
New features will be added in a backward compatible manner.

Contributions

PR's are very welcome.
Please submit contributions based on the main branch. Currently, the oldest supported PHP version is 7.4.

Copyright & License

Copyright 2021 Vinai Kopp & Hyvä Themes BV

The module is released under the BSD-3 Clause license.

Parting words

"And I know it seems easy," said Piglet to himself,
"but it isn't every one who could do it."

• Alan Alexander Miln, "The house at Pooh Corner"

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

Unreleased

Added

• Nothing

Changed

• Nothing

Removed

• No removals.

1.1.23 - 2025-02-06

Added

• Nothing

Changed

• Fixed: Boolean filter behavior in grids with multiple filters (thanks to Andreas von Studnitz)

Removed

• Nothing

1.1.22 - 2023-12-08

Added

• Nothing

Changed

• Fixed: Ajax Grid: after filtering all mass actions redirect to admin dashboard

Removed

• Nothing

1.1.18 - 2022-04-12

Added

• Nothing

Changed

• PHP 8.1 compatibility changes. All changes are backward compatible.

• Dropping PHP 7.3 support

Removed

• Nothing

1.1.17 - 2022-03-08

Added

• French Translation
  Thanks to Frederic Martinez for the PR!

Changed

• Grid Labels are now translated
  Thanks to Frederic Martinez for the PR!

Removed

• Nothing

1.1.16 - 2021-07-01

Added

• Support grid column data types smallint and mediumint

Changed

• Bugfix: modules enabled in app/etc/config.php but not installed no longer throw an exception.
  Thanks to Mirko Cesaro for reporting!

• Bugfix: grid sources with an accessor methods starting with is (e.g. isActive) no longer always
  return null if the object also implements magic getters.

• Bugfix: for ajax grids, grid action URLs with * as part of the new path will now resolve to the original route instead of using the ajax route.
  This closes the issue #56.

• Use TailwindCSS forms plugin strategy class. This will improve compatibility with
  existing Magento forms. Some modules that relied on the automatic form styles resets might need to be updated.
  More information can be found at https://github.com/tailwindlabs/tailwindcss-forms#using-classes-instead-of-element-selectors

Removed

• No removals.

1.1.15 - 2021-05-26

Added

• Nothing

Changed

• Removed Umlaut from file name in documentation, because it breaks composer package building.
  Thanks to Pieter Hoste for letting me know.

Removed

• Nothing

1.1.14 - 2021-05-14

Added

• New collection grid source type specific processor interface
  HyvaGridCollectionProcessorInterface extending HyvaGridSourceProcessorInterface

  If processors implement this interface, an afterInitSelect method is called for collections.
  This allows joining fields before the available grid columns are extracted or the search criteria is applied.

• New method getGridName on all grid source types.
  This might be handy in plugins.

1.1.13 - 2021-05-5

No changes, this is a fix for a botched 1.1.12 release.

1.1.12 - 2021-05-5

Added

• New experimental JavaScript events implementation for grid actions.

Changed

• Nothing.

Removed

• No removals.

1.1.11 - 2021-04-27

Added

• Added $escaper declaration to templates for Magento 2.3 compatibility.

Changed

• Nothing.

Removed

• No removals.

1.1.10 - 2021-04-23

Added

• Nothing yet.

Changed

• Use in_array instead of external dependency that declares array_contains.
  Thanks to Helge Baier who made me aware of this bug.

Removed

• No removals.

1.1.9 - 2021-04-23

Added

• New grid column type website_id.
• New low level grid customization technique via \Hyva\Admin\Api\HyvaGridSourceProcessorInterface
  They can be configured on grids in the XML at grid/source/processors.

Changed

• Allow as="" attribute for query grid source join columns
• Improved grid styling a bit (I hope)

Removed

• No removals.

1.1.8 - 2021-04-17

Added

• Nothing currently.

Changed

• Bugfix: grids without filters throw an error that action is undefined on null.

Removed

• No removals.

1.1.7 - 2021-04-11

Added

• It's now possible to configure Exports for grids, thanks to https://github.com/pointia!

Changed

• Nothing currently.

Removed

• No removals.

1.1.6 - 2021-04-09

Added

• A new Query Grid Source Type is now available to display DB table data without using ORM models.

Changed

• Nothing currently.

Removed

• No removals.

1.1.5 - 2021-04-06

Added

• Add composer dependency on laminas/laminas-code:^3.0.0 for Magento 2.3 compatibility.
• Read return type from method declaration on interfaces if present.
• Use Select inspection on collection grid source type for columns that do not have getters or setters.
  This also supports fields added with joins and custom fields on existing flat tables.

Changed

• Nothing currently.

Removed

• No removals.

1.1.4 - 2021-03-15

Added

• Add polyfill for \Magento\Framework\View\Helper\SecureHtmlRenderer for
  view/adminhtml/templates/page/js/require_js.phtml Magento 2.3 compatibility.

Changed

• Bugfix: allow underscore in route-id for route declarations in XML
• Bugfix: grid column filters with a zero value are now possible
• Bugfix issue #42: array grid providers returning an empty array no longer produce a stack trace.
• Fixed example how to use ColumnDefinition::merge() in the docs.
• Bugfix issue #33: With active filters the array grid source type page count still is calculated based on all grid
  records, not the filtered grid entries, resulting in added blank pages at the end.

Removed

• No removals.

1.1.3 - 2021-02-05

Added

• New event to customize column definitions conditionally:
  'hyva_grid_column_definition_build_after_' . $gridNameSuffix
  Thanks to @paugnu for the PR!

Changed

• No changes

Removed

• No removals.

1.1.2 - 2021-01-28

Added

• Filters now can have source models:
  <filter column="store_id" source="\Magento\Config\Model\Config\Source\Store"/>

Changed

• No changes

Removed

• No removals.

1.1.1 - 2021-01-26

Added

• Support collections that use the generic entity type
  \Magento\Framework\View\Element\UiComponent\DataProvider\Document
  This is mainly used in the standard adminhtml (non-hyva) grids.
  For example `Magento\Sales\Model\ResourceModel\Order\Grid\Collection´

Changed

• Backward compatible bugfix for select filter with ajax pagination.

Removed

• No removals.

1.1.0 - 2021-01-19

Added

• Add feature to declare default search criteria bindings for embedded grids.
  More information can be found in the docs.

Changed

• A number of small bugfixes that I forgot to include individually in this changelog. Still getting used to it.

Removed

• No removals.

1.0.8 - 2021-01-15

Added

• Add this CHANGELOG.md file.
• New column attribute initiallyHidden. When set to true, a column will be rendered
  in HTML but hidden by JavaScript on the initial page load. The Display dropdown can be used to show the column
  when needed.
  Thanks to @paugnu for this feature.
• Buttons to navigate to the first and last page are now part of the pagination.
  Thanks to @Bartlomiejsz for this feature.
• New pager attribute enabled. When set to false no pagination is rendered, and no current page
  and page size is set on the search criteria passed to the grid data providers.
• Ajax Paging. Ajax paging is the default navigation mode. It can be disabled by setting the useAjax attribute
  on the pager element to false. <pager useAjax="false"/> .

Changed

• Changed the column type long_text to function as a non-truncating text type.
  The default behavior remains that text content is truncated if it's longer than 30 characters.

Removed

• No removals.