repository·main·Indexed 41 days ago
https://github.com/hyva-themes/magento2-hyva-adminA Magento 2 module designed to replace the complex UI Component system for creating admin grids and forms. It leverages Tailwind CSS and Alpine.js to provide a faster developer experience, featuring XML-based grid configuration, programmatic column customization via events, and flexible grid source prefetching.
Hyvä Admin is a Magento 2 module designed to provide a modern way to create admin grids. Its primary goal is to improve the developer experience when building new administrative interfaces in Magento.
Key characteristics:
Because extension attributes are often loaded after the main record data, standard grid filtering may not work for them. To implement custom filtering for columns containing extension attributes, you can intercept the data loading process using the hyva_grid_source_prefetch_ event.
When the RepositoryGridSourceType is about to load grid data, it dispatches an event named hyva_grid_source_prefetch_ followed by a sanitized version of the grid name (where non-alphanumeric characters like - are replaced with underscores).
How to use this event:
customer-grid, the event name is hyva_grid_source_prefetch_customer_grid.events.xml.search_criteria_container (which wraps the SearchCriteriaInterface), the grid_name, and the record_type.SearchCriteria to include filters for extension attributes.// Example of the event dispatch logic in RepositoryGridSourceType
private function dispatchEvent(
string $gridName,
string $recordType,
SearchCriteriaInterface $searchCriteria
): SearchCriteriaInterface {
$eventName = 'hyva_grid_source_prefetch_' . $this->getGridNameEventSuffix($gridName);
$container = new SearchCriteriaEventContainer($searchCriteria);
$this->eventManager->dispatch($eventName, [
'search_criteria_container' => $container,
'grid_name' => $gridName,
'record_type' => $recordType
]);
return $container->getSearchCriteria();
}Before grid data is loaded from a grid source object, Hyvä Admin dispatches two events that allow you to intercept and modify the SearchCriteria instance. This is useful for applying global filters or custom search logic to specific grids.
There are two types of events available:
'hyva_grid_source_prefetch_' . $suffix. The suffix is the grid name in lowercase with underscores replacing non-alphanumeric characters (e.g., a grid named product-grid dispatches hyva_grid_source_prefetch_product_grid).'hyva_grid_source_prefetch', which triggers for all grids.Both events provide access to a SearchCriteriaEventContainer which you can use to replace the existing search criteria with your own.
// Example of how to update search criteria in an observer
public function execute(\Magento\Framework\Event\Observer $observer)
{
$event = $observer->getEvent();
/** @var \Hyva\Admin\Model\GridSourceType\RepositorySourceType\SearchCriteriaEventContainer $searchCriteriaContainer */
$searchCriteriaContainer = $event->getData('search_criteria_container');
$type = $event->getData('record_type');
// Logic to generate your custom criteria
$updatedSearchCriteria = $this->changeCriteria($type, $searchCriteriaContainer->getSearchCriteria());
// Apply the new criteria to the container
$searchCriteriaContainer->replaceSearchCriteria($updatedSearchCriteria);
}When multiple sources are available for the same data (e.g., Repository vs. Collection vs. Grid Collection), consider the following:
Magento\Sales\Model\ResourceModel\OrderGridCollection provides a full customer name field that is not present in the standard Order model).If performance or specific data availability isn't a concern, use whichever is most readily available in your implementation.
In Hyvä Admin grid XML configuration, the <field> element within <defaultSearchCriteriaBindings> allows you to automatically apply filters to a grid based on the current Magento state (e.g., filtering orders by the current customer ID or store ID). This is particularly useful for grids embedded within other entity pages.
Each <field> declaration maps a grid field name to a value retrieved from a request parameter, a service method, or a session object.
<source>
...
<defaultSearchCriteriaBindings>
<field name="entity_id" requestParam="id"/>
<field name="store_id" method="Magento\Store\Model\StoreManagerInterface::getStore" property="id"/>
<field name="customer_ids" condition="finset" method="Magento\Customer\Model\Session::getCustomerId"/>
</defaultSearchCriteriaBindings>
</source>entityConfig element serves strictly as a structural parent. It is used to group the label children elements, which define the singular and plural labels for an entity. You cannot apply configuration directly to entityConfig itself; instead, you must define the labels within its child elements.The types of the $source and $rawResult arguments in processor methods depend on the specific type of Grid Source being used:
| Grid Source Type | $source Argument | $rawResult Argument |
|---|---|---|
| Repository | Instance of the class on which getList is called | MagentoFrameworkApiSearchResultsInterface instance |
| Collection | Collection instance before search criteria are applied | Collection instance after search criteria are applied (may be loaded) |
| Array | Array provider instance | Array result after filtering, but before pagination or sorting |
| Query | MagentoFrameworkDBSelect instance after search criteria applied | Query result array: ['data' => $rows, 'count' => $count] |
In Hyvä Admin grid configurations, a <query> element can include zero or more <unionSelect> children. Each <unionSelect> allows you to combine a secondary select configuration with the primary select configuration of the query.
Note that <unionSelect> elements do not have their own attributes; instead, they inherit the same configuration structure as a standard <select> element. For more details on the allowed children within a select, refer to the grid > source > query > select documentation.
When an action event is triggered, a JavaScript event is dispatched to the window object. The event name follows a specific pattern based on the grid name, the action ID, and the event trigger type:
hyva-grid-{gridName}-action-{actionId}-{trigger}
Where {gridName} and {actionId} are processed via an eventify function (typically converting names to kebab-case).
Example:
For a grid named products-query-grid and an action with the ID delete triggered on click, the event name is:
hyva-grid-products-query-grid-action-delete-click
While grid columns are typically configured via XML, you can use the hyva_grid_column_definition_build_after event to apply conditional logic to column definitions. This event is dispatched after the column definitions are built, allowing you to modify them based on the grid type or configuration.
The event name is dynamic and follows this pattern:
hyva_grid_column_definition_build_after_{grid_name_suffix}
Where {grid_name_suffix} is the grid name in lowercase, with non-alphanumeric characters replaced by underscores. For example, a grid named product-grid dispatches hyva_grid_column_definition_build_after_product_grid.
// Example event name for a 'product-grid'
'hyva_grid_column_definition_build_after_product_grid'Hyva_Admin is designed to maximize developer efficiency and enjoyment by adhering to several core architectural principles:
.phtml templates.