Twig Templates & Back-Office Theming
Relevant source files
The following files were used as context for generating this wiki page:
PrestaShop utilizes Twig as its primary engine for rendering Back-Office (BO) interfaces and managing theme logic. The system integrates standard Twig capabilities with PrestaShop-specific extensions, hooks, and localized content to create a fully responsive administrative environment.
This module controls the visual presentation and layout of the administration panel. It handles the rendering of complex components like Grids, Forms, and Dashboard elements, while ensuring high customizability through a dedicated hook system and localization data.
Sources: README.md:14-25, src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php:24-60
Architecture and Hook Integration
The Back-Office theming architecture relies heavily on a dynamic hook system to modify layouts and data presentation without altering core files. The GenerateHooksDocumentationCommand class identifies how these hooks are dispatched within specific Back-Office components such as Grids and Presenters.
Hook Dispatch Flow
When the Back-Office renders a grid or form, the system dispatches specific "modifier" hooks. These hooks allow developers to inject custom logic or modify the data structure before the Twig template renders the final output.
The diagram shows how various grid-related components trigger hooks to modify definitions or data before rendering.
Sources: src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php:24-60
Key Hook Components
The system categorizes hooks based on their functional impact on the interface:
| Hook Suffix | Implementation File | Purpose |
|---|---|---|
GridDefinitionModifier | AbstractGridDefinitionFactory.php | Modifies the structure/columns of a grid. |
GridQueryBuilderModifier | DoctrineGridDataFactory.php | Alters the SQL query used to fetch data. |
GridDataModifier | GridFactory.php | Modifies raw data before presentation. |
GridFilterFormModifier | GridFilterFormFactory.php | Adds or removes filters in the BO search. |
GridPresenterModifier | GridPresenter.php | Adjusts the final presented data object. |
Sources: src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php:24-60
Content Rendering and Localization
PrestaShop Back-Office theming supports multi-language rendering through XML-based data files. These files provide the structure for CMS pages, including titles, meta information, and HTML content that Twig eventually displays to the user.
Localized Data Structure
Content for themes is defined in cms.xml files per language. These files contain raw HTML blocks that are passed to the template engine.
<cms id="About_us">
<meta_title>About us</meta_title>
<meta_description>Learn more about us</meta_description>
<content><h1 class="page-heading">About us</h1>...</content>
<link_rewrite>about-us</link_rewrite>
</cms>
Sources: install-dev/langs/en/data/cms.xml:27-66
UI Testing and Theming Validation
The integrity of themes and Twig templates is validated through functional UI tests. These tests ensure that components like categories are correctly rendered in the Back-Office and that data modifications (CRUD operations) reflect accurately in the UI.
Theming Validation Flow
The UI testing suite interacts with the Back-Office to verify that CSS classes and HTML structures (e.g., page-title, page-heading) match expected values.
This sequence illustrates the process of verifying that Twig-rendered content matches the localized source data.
Sources: tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts:60-150, tests/UI/package.json:10-50
Development Environment for Theming
For theme development and template modification, the project provides a Docker-based environment. The environment binds internal services to local ports, allowing real-time preview of Twig changes in the Back-Office.
- Backend URL:
http://localhost:8001/admin-dev - Default Credentials:
demo@prestashop.com/Pr3st4Sh0P - Admin Customization: Set via
ADMIN_MAILandADMIN_PASSWDenvironment variables.
Sources: README.md:73-88
The Twig implementation in PrestaShop ensures a separation between core business logic and presentation. By utilizing dynamic hooks and localized XML data, the Back-Office theming system remains extensible while supporting global commerce requirements.
Sources: README.md:14-25, src/PrestaShopBundle/Command/GenerateHooksDocumentationCommand.php:127-180