diff --git a/modules/concepts/hooks/list-of-hooks/displayAdminDashboardToolbar.md b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardToolbar.md new file mode 100644 index 0000000000..41a731de33 --- /dev/null +++ b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardToolbar.md @@ -0,0 +1,27 @@ +--- +Title: displayAdminDashboardToolbar +hidden: true +hookTitle: 'Symfony Dashboard - Toolbar' +files: + - + url: 'https://github.com/PrestaShop/PrestaShop/blob/develop/src/PrestaShopBundle/Resources/views/Admin/Dashboard/index.html.twig' + file: src/PrestaShopBundle/Resources/views/Admin/Dashboard/index.html.twig +locations: + - 'back office' +type: display +hookAliases: +array_return: false +check_exceptions: false +chain: false +origin: core +description: "Displays module content in the toolbar area of the migrated (Symfony) dashboard page. Modern counterpart of the legacy displayDashboardToolbarTopMenu hook." + +--- + +{{% hookDescriptor %}} + +## Call of the Hook in the origin file + +```twig +{{ renderhook('displayAdminDashboardToolbar') }} +``` diff --git a/modules/concepts/hooks/list-of-hooks/displayAdminDashboardTop.md b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardTop.md new file mode 100644 index 0000000000..6d390b1a09 --- /dev/null +++ b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardTop.md @@ -0,0 +1,27 @@ +--- +Title: displayAdminDashboardTop +hidden: true +hookTitle: 'Symfony Dashboard - Top' +files: + - + url: 'https://github.com/PrestaShop/PrestaShop/blob/develop/src/PrestaShopBundle/Resources/views/Admin/Dashboard/index.html.twig' + file: src/PrestaShopBundle/Resources/views/Admin/Dashboard/index.html.twig +locations: + - 'back office' +type: display +hookAliases: +array_return: false +check_exceptions: false +chain: false +origin: core +description: "Displays module content in the top area of the migrated (Symfony) dashboard page. Modern counterpart of the legacy displayDashboardTop hook." + +--- + +{{% hookDescriptor %}} + +## Call of the Hook in the origin file + +```twig +{{ renderhook('displayAdminDashboardTop', {date_from: dateFrom, date_to: dateTo}) }} +``` diff --git a/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneOne.md b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneOne.md new file mode 100644 index 0000000000..2f42856893 --- /dev/null +++ b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneOne.md @@ -0,0 +1,27 @@ +--- +Title: displayAdminDashboardZoneOne +hidden: true +hookTitle: 'Symfony Dashboard - Zone one' +files: + - + url: 'https://github.com/PrestaShop/PrestaShop/blob/develop/src/PrestaShopBundle/Controller/Admin/DashboardController.php' + file: src/PrestaShopBundle/Controller/Admin/DashboardController.php +locations: + - 'back office' +type: display +hookAliases: +array_return: false +check_exceptions: false +chain: false +origin: core +description: "Displays module content in the first column of the migrated (Symfony) dashboard page. Modern counterpart of the legacy dashboardZoneOne hook." + +--- + +{{% hookDescriptor %}} + +## Call of the Hook in the origin file + +```php +$hookDispatcher->dispatchRenderingWithParameters('displayAdminDashboardZoneOne', ['date_from' => $dateFrom, 'date_to' => $dateTo]) +``` diff --git a/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneThree.md b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneThree.md new file mode 100644 index 0000000000..ed41dc5b58 --- /dev/null +++ b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneThree.md @@ -0,0 +1,27 @@ +--- +Title: displayAdminDashboardZoneThree +hidden: true +hookTitle: 'Symfony Dashboard - Zone three' +files: + - + url: 'https://github.com/PrestaShop/PrestaShop/blob/develop/src/PrestaShopBundle/Controller/Admin/DashboardController.php' + file: src/PrestaShopBundle/Controller/Admin/DashboardController.php +locations: + - 'back office' +type: display +hookAliases: +array_return: false +check_exceptions: false +chain: false +origin: core +description: "Displays module content in the third column of the migrated (Symfony) dashboard page. Modern counterpart of the legacy dashboardZoneThree hook." + +--- + +{{% hookDescriptor %}} + +## Call of the Hook in the origin file + +```php +$hookDispatcher->dispatchRenderingWithParameters('displayAdminDashboardZoneThree', ['date_from' => $dateFrom, 'date_to' => $dateTo]) +``` diff --git a/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneTwo.md b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneTwo.md new file mode 100644 index 0000000000..a723aaad74 --- /dev/null +++ b/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneTwo.md @@ -0,0 +1,27 @@ +--- +Title: displayAdminDashboardZoneTwo +hidden: true +hookTitle: 'Symfony Dashboard - Zone two' +files: + - + url: 'https://github.com/PrestaShop/PrestaShop/blob/develop/src/PrestaShopBundle/Controller/Admin/DashboardController.php' + file: src/PrestaShopBundle/Controller/Admin/DashboardController.php +locations: + - 'back office' +type: display +hookAliases: +array_return: false +check_exceptions: false +chain: false +origin: core +description: "Displays module content in the second column of the migrated (Symfony) dashboard page. Modern counterpart of the legacy dashboardZoneTwo hook." + +--- + +{{% hookDescriptor %}} + +## Call of the Hook in the origin file + +```php +$hookDispatcher->dispatchRenderingWithParameters('displayAdminDashboardZoneTwo', ['date_from' => $dateFrom, 'date_to' => $dateTo]) +``` diff --git a/modules/sample-modules/dashboard-new-hooks/_index.md b/modules/sample-modules/dashboard-new-hooks/_index.md new file mode 100644 index 0000000000..4300bd78ec --- /dev/null +++ b/modules/sample-modules/dashboard-new-hooks/_index.md @@ -0,0 +1,108 @@ +--- +title: Dashboard page new hooks +weight: 2 +--- + +# Dashboard page new hooks +{{< minver v="9.2.0" title="true" >}} + +## Introduction + +The Back Office **Dashboard** page is being migrated from a legacy controller to a Symfony controller rendering a Twig layout. The migrated page is gated behind the `dashboard` **feature flag** (beta, disabled by default), available in *Advanced Parameters > New & Experimental Features*. + +The migrated page deliberately exposes a **new, dedicated hook family** (`displayAdminDashboard*`), distinct from the legacy dashboard hooks. This is the key integration principle: + +{{% notice note %}} +A module knows which architecture it is integrating with **purely from which hook is called**. The migrated (Symfony) page never calls the legacy hooks, and the legacy page never calls the new ones. There is therefore **no version detection to do** on the module side, no `get_class($this->context->controller)` check, and no dependency on Smarty or the legacy `Helper*` classes. +{{% /notice %}} + +A complete, minimal example is provided by the [`dashexample`](https://github.com/PrestaShop/example-modules/tree/master/dashexample) module. + +## New hooks vs legacy hooks + +| New hook (Symfony dashboard) | Type | Parameters | Legacy counterpart | +|---|---|---|---| +| [`displayAdminDashboardZoneOne`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneOne" >}}) | display | `date_from`, `date_to` | `dashboardZoneOne` | +| [`displayAdminDashboardZoneTwo`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneTwo" >}}) | display | `date_from`, `date_to` | `dashboardZoneTwo` | +| [`displayAdminDashboardZoneThree`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAdminDashboardZoneThree" >}}) | display | `date_from`, `date_to` | `dashboardZoneThree` | +| [`displayAdminDashboardTop`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAdminDashboardTop" >}}) | display | `date_from`, `date_to` | `displayDashboardTop` | +| [`displayAdminDashboardToolbar`]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAdminDashboardToolbar" >}}) | display | — | `displayDashboardToolbarTopMenu` | + +The `date_from` / `date_to` parameters carry the employee's selected stats date range (format `Y-m-d`). + +The zone hooks are expected to **return an HTML string**; the core injects it into the corresponding zone. The page makes no assumption about how the module produces that HTML. + +## Rendering hook content + +On the migrated page you render your content with a **Twig template** and the module's Symfony service container — no Smarty, no `HelperForm`, no `Db::getInstance()`: + +```php +public function install(): bool +{ + return parent::install() + && $this->registerHook([ + 'displayAdminDashboardZoneOne', + 'displayAdminDashboardZoneTwo', + 'displayAdminDashboardToolbar', + ]); +} + +public function hookDisplayAdminDashboardZoneOne(array $params): string +{ + return $this->get('twig')->render('@Modules/mymodule/views/templates/admin/zone_one.html.twig', [ + 'dateFrom' => $params['date_from'] ?? null, + 'dateTo' => $params['date_to'] ?? null, + ]); +} +``` + +### Loading your own assets + +Because there is no `actionAdminControllerSetMedia` + controller class-name detection, load your CSS/JS **from your hook output**. The toolbar hook is rendered once at the top of the page, which makes it a good place for this: + +```twig +{# views/templates/admin/toolbar.html.twig #} + + +``` + +where `moduleUri` is `$this->getPathUri()` passed from the hook. + +## Supporting both the legacy and the migrated dashboard + +To keep a single module compatible across PrestaShop versions, register on **both** hook families. The core calls only the hook that belongs to the currently displayed page, so the two never collide: + +```php +public function install(): bool +{ + return parent::install() + && $this->registerHook([ + // Migrated (Symfony) dashboard — Twig, no legacy helpers + 'displayAdminDashboardZoneOne', + 'displayAdminDashboardZoneTwo', + 'displayAdminDashboardToolbar', + // Legacy dashboard — Smarty / HelperForm as before + 'dashboardZoneOne', + 'dashboardZoneTwo', + 'displayDashboardToolbarTopMenu', + ]); +} + +// Called only on the migrated page +public function hookDisplayAdminDashboardZoneOne(array $params): string +{ + return $this->get('twig')->render('@Modules/mymodule/views/templates/admin/zone_one.html.twig', $params); +} + +// Called only on the legacy page +public function hookDashboardZoneOne(array $params): string +{ + $this->smarty->assign($params); + + return $this->display(__FILE__, 'views/templates/hook/zone_one.tpl'); +} +``` + +{{% notice tip %}} +While the migration is ongoing, the native dashboard modules (`dashactivity`, `dashtrends`, `dashgoals`, `dashproducts`) are not yet compatible with the migrated page and will not display anything on it until they are migrated. This is why the page is gated behind a beta feature flag. +{{% /notice %}}