Grid Component Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Grid component provides a standardized way to display, filter, and manage data lists within the PrestaShop back office. It separates the data structure (Definition), the data retrieval (Data Factory), and the visual representation (Presenter) to ensure a modular and extensible architecture.
This system relies on PHP classes for logic and SCSS/Bootstrap for responsive layout. Developers extend the functionality by implementing specific factories and utilizing dynamic hooks to modify grid behavior.
Core Structural Components
The Grid architecture consists of several key layers that handle the lifecycle of a data list from definition to display.
Grid Definition and Factories
The GridDefinition defines the columns, filters, and actions available. The AbstractGridDefinitionFactory serves as the base for creating these definitions. It requires an implementation of the getDefinition() method and utilizes a HookDispatcher to allow modules to modify the grid structure.
Sources: [src/Core/Grid/Definition/Factory/AbstractGridDefinitionFactory.php:30-74](https://github.com/mattgoud-sandbox/PrestaShop/blob/a9e8f98a90dc6c32ecb7a82c567c16f0a892c444/src/Core/Grid/Definition/Factory/AbstractGridDefinitionFactory.php#L30-L74)
Grid Data and Presentation
The Grid class holds the final state of the grid, including its definition, retrieved data, and search criteria. The presentation layer uses a GridPresenter to format this data for the user interface.
Sources: [src/Core/Grid/Grid.php:25-50](https://github.com/mattgoud-sandbox/PrestaShop/blob/a9e8f98a90dc6c32ecb7a82c567c16f0a892c444/src/Core/Grid/Grid.php#L25-L50), [src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php:33-66](https://github.com/mattgoud-sandbox/PrestaShop/blob/a9e8f98a90dc6c32ecb7a82c567c16f0a892c444/src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php#L33-L66)
Architecture Flow
The following diagram illustrates the relationship between the major Grid components:
This flowchart shows how definitions and data are created, modified by hooks, and eventually presented to the UI.
Extensibility via Dynamic Hooks
The Grid system integrates dynamic hooks at multiple stages. These hooks allow developers to inject custom columns, modify database queries, or alter the final presented data without changing core files.
| Hook Suffix | Implementation File | Purpose |
|---|---|---|
GridDefinitionModifier | AbstractGridDefinitionFactory.php | Modifies columns, filters, and actions. |
GridQueryBuilderModifier | DoctrineGridDataFactory.php | Alters SQL queries (search/count) and criteria. |
GridDataModifier | GridFactory.php | Modifies the raw data rows after retrieval. |
GridFilterFormModifier | GridFilterFormFactory.php | Customizes the filter form fields. |
GridPresenterModifier | GridPresenter.php | Modifies the final array sent to the template. |
Sources: [src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php:34-65](https://github.com/mattgoud-sandbox/PrestaShop/blob/a9e8f98a90dc6c32ecb7a82c567c16f0a892c444/src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php#L34-L65)
Hook Dispatch Sequence
The sequence below shows how a Grid is instantiated and where hooks are triggered:
This diagram demonstrates the interception points for modules during the grid generation process.
Layout and Styling
The visual layer of the Grid component utilizes a customized Bootstrap-based grid system. It provides responsive containers and columns specifically tuned for the PrestaShop back office administration theme.
CSS Grid System
The layout uses a fluid container model with specific breakpoints for different screen sizes.
- Containers: Uses
.containerand.container-fluidfor layout wrapping. - Rows: The
.rowclass manages horizontal groupings and clears floats. - Columns: Implements a 12-column grid with breakpoints for
xs(extra small),sm(small),md(medium), andlg(large) devices.
Sources: [admin-dev/themes/default/scss/vendor/bootstrap-sass/_grid.scss:11-85](https://github.com/mattgoud-sandbox/PrestaShop/blob/a9e8f98a90dc6c32ecb7a82c567c16f0a892c444/admin-dev/themes/default/scss/vendor/bootstrap-sass/_grid.scss#L11-L85)
Theme Integration
The grid styles are imported into the main admin-theme.scss within the .bootstrap namespace to prevent style leakage into older parts of the back office that do not use the modern Grid component.
.bootstrap {
@import "vendor/bootstrap-sass/grid";
@import "vendor/bootstrap-sass/tables";
@import "vendor/bootstrap-sass/forms";
// ... other components
}
Sources: [admin-dev/themes/default/scss/admin-theme.scss:43-65](https://github.com/mattgoud-sandbox/PrestaShop/blob/a9e8f98a90dc6c32ecb7a82c567c16f0a892c444/admin-dev/themes/default/scss/admin-theme.scss#L43-L65)
Conclusion
The PrestaShop Grid Component Architecture provides a robust framework for data management in the back office. By decoupling definition, data retrieval, and presentation, and providing deep hook integration, it enables high maintainability and extensibility. The use of a standardized SCSS grid ensures that data lists remain responsive across all device types.