From 2f5935c762e3047446307885b1ec0028381077f8 Mon Sep 17 00:00:00 2001 From: tblivet Date: Mon, 23 Feb 2026 18:44:25 +0100 Subject: [PATCH 01/48] feat: theme refactor --- basics/installation/_index.md | 2 +- development/architecture/introduction.md | 4 +- development/internationalization/rtl.md | 2 +- modules/core-updates/8.0.md | 2 +- .../displaying-content-in-front-office.md | 2 +- themes/_index.md | 20 +- themes/concepts/_index.md | 23 ++ themes/concepts/asset-management.md | 181 +++++++++ themes/concepts/hooks.md | 87 +++++ themes/concepts/overrides.md | 107 +++++ themes/concepts/rtl.md | 61 +++ themes/concepts/templates/_index.md | 20 + themes/concepts/templates/head.md | 56 +++ .../templates/img/inheritance-schema.png | Bin 0 -> 79598 bytes themes/concepts/templates/listing-pages.md | 81 ++++ themes/concepts/templates/notifications.md | 33 ++ .../templates/template-inheritance.md | 117 ++++++ .../templates/templates-and-layouts.md | 151 +++++++ themes/concepts/theme-structure.md | 261 +++++++++++++ themes/concepts/translation.md | 99 +++++ themes/create-a-theme/_index.md | 20 + themes/create-a-theme/child-theme.md | 139 +++++++ themes/create-a-theme/from-hummingbird.md | 74 ++++ themes/create-a-theme/from-scratch.md | 177 +++++++++ themes/distribution/_index.md | 11 +- themes/distribution/exporting.md | 60 ++- .../distribution/img/export-current-theme.png | Bin 85118 -> 0 bytes themes/distribution/testing.md | 71 ---- themes/distribution/validation.md | 71 ++++ themes/getting-started/_index.md | 11 +- .../asset-management/_index.md | 368 ------------------ .../asset-management/img/webpack.png | Bin 150078 -> 0 bytes .../asset-management/webpack.md | 45 --- themes/getting-started/environment-setup.md | 92 +++++ themes/getting-started/guidelines.md | 67 ---- themes/getting-started/quick-start.md | 75 ++++ themes/getting-started/requirements.md | 59 +++ .../setting-up-your-local-environment.md | 87 ----- themes/getting-started/theme-organization.md | 132 ------- themes/getting-started/theme-yml.md | 242 ------------ .../tools-for-theme-designers.md | 217 ----------- themes/guidelines/_index.md | 22 ++ themes/guidelines/accessibility.md | 90 +++++ themes/guidelines/browser-compatibility.md | 68 ++++ themes/guidelines/coding-standards.md | 89 +++++ themes/hummingbird/_index.md | 29 +- themes/hummingbird/accessibility.md | 53 +++ themes/hummingbird/bootstrap-compatibility.md | 87 +++++ themes/hummingbird/css-architecture.md | 111 ++++++ themes/hummingbird/development-workflow.md | 65 ++++ themes/hummingbird/hooks/_index.md | 21 +- themes/hummingbird/hooks/cartpage.md | 16 +- themes/hummingbird/hooks/categorypage.md | 13 +- themes/hummingbird/hooks/checkoutflow.md | 30 +- themes/hummingbird/hooks/connexionpage.md | 16 +- themes/hummingbird/hooks/contactpage.md | 14 +- themes/hummingbird/hooks/homepage.md | 40 +- themes/hummingbird/hooks/myaccount.md | 12 +- themes/hummingbird/hooks/productpage.md | 23 +- themes/hummingbird/javascript.md | 111 ++++++ themes/img/choose-layouts.png | Bin 0 -> 172483 bytes themes/img/export-current-theme.png | Bin 0 -> 41136 bytes themes/img/inheritance-schema.png | Bin 0 -> 79598 bytes themes/img/rtl-generate.png | Bin 0 -> 49199 bytes themes/reference/_index.md | 18 +- themes/reference/bootstrap-compatibility.md | 93 ----- themes/reference/hooks/_index.md | 59 --- themes/reference/javascript-events.md | 42 ++ themes/reference/javascript-events/_index.md | 94 ----- themes/reference/migration-from-16.md | 14 - themes/reference/overriding-modules.md | 138 ------- themes/reference/overriding-selectors.md | 16 - themes/reference/rtl.md | 66 ---- themes/reference/smarty-helpers.md | 47 ++- .../reference/template-inheritance/_index.md | 73 ---- .../img/template-inheritance.png | Bin 946207 -> 0 bytes .../parent-child-feature.md | 86 ---- themes/reference/template-variables.md | 247 ++++++++++++ themes/reference/templates/_index.md | 13 - themes/reference/templates/head.md | 65 ---- .../templates/img/configure-layout.png | Bin 186891 -> 0 bytes themes/reference/templates/listing.md | 71 ---- themes/reference/templates/notifications.md | 116 ------ .../reference/templates/templates-layouts.md | 214 ---------- themes/reference/templates/variables.md | 206 ---------- themes/reference/theme-translation.md | 77 ---- 86 files changed, 3228 insertions(+), 2764 deletions(-) create mode 100644 themes/concepts/_index.md create mode 100644 themes/concepts/asset-management.md create mode 100644 themes/concepts/hooks.md create mode 100644 themes/concepts/overrides.md create mode 100644 themes/concepts/rtl.md create mode 100644 themes/concepts/templates/_index.md create mode 100644 themes/concepts/templates/head.md create mode 100644 themes/concepts/templates/img/inheritance-schema.png create mode 100644 themes/concepts/templates/listing-pages.md create mode 100644 themes/concepts/templates/notifications.md create mode 100644 themes/concepts/templates/template-inheritance.md create mode 100644 themes/concepts/templates/templates-and-layouts.md create mode 100644 themes/concepts/theme-structure.md create mode 100644 themes/concepts/translation.md create mode 100644 themes/create-a-theme/_index.md create mode 100644 themes/create-a-theme/child-theme.md create mode 100644 themes/create-a-theme/from-hummingbird.md create mode 100644 themes/create-a-theme/from-scratch.md delete mode 100644 themes/distribution/img/export-current-theme.png delete mode 100644 themes/distribution/testing.md create mode 100644 themes/distribution/validation.md delete mode 100644 themes/getting-started/asset-management/_index.md delete mode 100644 themes/getting-started/asset-management/img/webpack.png delete mode 100644 themes/getting-started/asset-management/webpack.md create mode 100644 themes/getting-started/environment-setup.md delete mode 100644 themes/getting-started/guidelines.md create mode 100644 themes/getting-started/quick-start.md create mode 100644 themes/getting-started/requirements.md delete mode 100644 themes/getting-started/setting-up-your-local-environment.md delete mode 100644 themes/getting-started/theme-organization.md delete mode 100644 themes/getting-started/theme-yml.md delete mode 100644 themes/getting-started/tools-for-theme-designers.md create mode 100644 themes/guidelines/_index.md create mode 100644 themes/guidelines/accessibility.md create mode 100644 themes/guidelines/browser-compatibility.md create mode 100644 themes/guidelines/coding-standards.md create mode 100644 themes/hummingbird/accessibility.md create mode 100644 themes/hummingbird/bootstrap-compatibility.md create mode 100644 themes/hummingbird/css-architecture.md create mode 100644 themes/hummingbird/development-workflow.md create mode 100644 themes/hummingbird/javascript.md create mode 100644 themes/img/choose-layouts.png create mode 100644 themes/img/export-current-theme.png create mode 100644 themes/img/inheritance-schema.png create mode 100644 themes/img/rtl-generate.png delete mode 100644 themes/reference/bootstrap-compatibility.md delete mode 100644 themes/reference/hooks/_index.md create mode 100644 themes/reference/javascript-events.md delete mode 100644 themes/reference/javascript-events/_index.md delete mode 100644 themes/reference/migration-from-16.md delete mode 100644 themes/reference/overriding-modules.md delete mode 100644 themes/reference/overriding-selectors.md delete mode 100644 themes/reference/rtl.md delete mode 100644 themes/reference/template-inheritance/_index.md delete mode 100644 themes/reference/template-inheritance/img/template-inheritance.png delete mode 100644 themes/reference/template-inheritance/parent-child-feature.md create mode 100644 themes/reference/template-variables.md delete mode 100644 themes/reference/templates/_index.md delete mode 100644 themes/reference/templates/head.md delete mode 100644 themes/reference/templates/img/configure-layout.png delete mode 100644 themes/reference/templates/listing.md delete mode 100644 themes/reference/templates/notifications.md delete mode 100644 themes/reference/templates/templates-layouts.md delete mode 100644 themes/reference/templates/variables.md delete mode 100644 themes/reference/theme-translation.md diff --git a/basics/installation/_index.md b/basics/installation/_index.md index 1db70d76d0..80fd873e1d 100644 --- a/basics/installation/_index.md +++ b/basics/installation/_index.md @@ -293,7 +293,7 @@ This problem may arise in case-insensitive file systems like MacOS due to a misc [getting-started-guide]: https://docs.prestashop-project.org/v.8-documentation/v/english/getting-started [system-requirements]: {{< relref "/9/basics/installation/system-requirements" >}} -[clone-the-repository]: {{< relref "/9/themes/getting-started/setting-up-your-local-environment" >}} +[clone-the-repository]: {{< relref "/9/themes/getting-started/environment-setup" >}} [compile-assets]: {{< relref "/9/development/compile-assets" >}} [webpack]: https://webpack.js.org/ [composer]: https://getcomposer.org/download/ diff --git a/development/architecture/introduction.md b/development/architecture/introduction.md index 6149ab20ec..5c8b5b8649 100644 --- a/development/architecture/introduction.md +++ b/development/architecture/introduction.md @@ -295,8 +295,8 @@ Remember the overview at the top of the article? Have a look at this more detail [MVC]: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller [smarty]: https://www.smarty.net/ [bootstrap]: https://getbootstrap.com/ -[child-theme]: {{< ref "/9/themes/reference/template-inheritance/parent-child-feature" >}} -[theme-module-override]: {{< ref "/9/themes/reference/overriding-modules" >}} +[child-theme]: {{< ref "/9/themes/create-a-theme/child-theme" >}} +[theme-module-override]: {{< ref "/9/themes/concepts/overrides" >}} [twig]: https://twig.symfony.com/ [github]: https://github.com/PrestaShop/prestashop-ui-kit/ [autoupgrade]: https://github.com/PrestaShop/autoupgrade/ diff --git a/development/internationalization/rtl.md b/development/internationalization/rtl.md index 746261c8e9..0bbcf348c1 100644 --- a/development/internationalization/rtl.md +++ b/development/internationalization/rtl.md @@ -32,4 +32,4 @@ If you changed something in your Back Office theme and you want your change to b {{< figure src="../img/rtl-edit-language.png" title="Toggling RTL for a language" >}} -[rtl-support]: {{< ref "/9/themes/reference/rtl" >}} +[rtl-support]: {{< ref "/9/themes/concepts/rtl" >}} diff --git a/modules/core-updates/8.0.md b/modules/core-updates/8.0.md index dcd61cddb8..a9cf166fcc 100644 --- a/modules/core-updates/8.0.md +++ b/modules/core-updates/8.0.md @@ -59,7 +59,7 @@ The `use_parent_assets` setting in `theme.yml`, when set to `true`, makes the ch To maintain the behavior of 1.7 and load the child theme's assets, `use_parent_assets` must be set to `false`. -[More details in the theme.yml reference page]({{}}). +[More details in the theme.yml reference page]({{}}). #### Classic theme diff --git a/modules/creation/displaying-content-in-front-office.md b/modules/creation/displaying-content-in-front-office.md index 4e686f183d..a379d18f7b 100644 --- a/modules/creation/displaying-content-in-front-office.md +++ b/modules/creation/displaying-content-in-front-office.md @@ -416,7 +416,7 @@ name, or even your own name or initials, such as: ## List of Smarty variables -You can find [a complete list of variables available in Smarty Templates on this page]({{< relref "/9/themes/reference/templates/variables" >}}). +You can find [a complete list of variables available in Smarty Templates on this page]({{< relref "/9/themes/reference/template-variables" >}}). There are many other contextual hooks. If you need to display all of the current page's Smarty variables, add the following call: diff --git a/themes/_index.md b/themes/_index.md index 4a7e3b40dd..de79a1d551 100644 --- a/themes/_index.md +++ b/themes/_index.md @@ -11,12 +11,22 @@ icon: 'images/icons/themes.svg' # Themes -The default PrestaShop installation offers the neutral "Classic theme", enabling merchants to quickly start their activity, whatever their business line. +PrestaShop themes control the entire front-office experience: layout, templates, styles, and client-side behavior. -Several marketplaces are available to get PrestaShop themes. As a graphic designer/front developer, you can put your themes up for sale on this marketplaces. +Starting from PrestaShop 9.1, **[Hummingbird]({{< relref "/9/themes/hummingbird" >}})** is the default theme. It is built on Bootstrap 5.3, follows BEM conventions, and provides an accessibility-first, jQuery-free architecture. -{{% notice note %}} -A new theme, Hummingbird, is being developed by the maintainer team. While under develoment, [you can start to discover it here]({{}}). +{{% notice warning %}} +The **Classic theme is deprecated** for new development starting from PrestaShop 9.1. It remains available for backward compatibility but will not receive new features. For Classic-specific documentation, refer to the [v8 theme docs]({{< relref "/8/themes" >}}). {{% /notice %}} -{{% children /%}} +## Documentation structure + +| Section | What you'll find | +|---------|-----------------| +| **[Getting started]({{< relref "/9/themes/getting-started" >}})** | Requirements, quick start, environment setup | +| **[Concepts]({{< relref "/9/themes/concepts" >}})** | How the PrestaShop theme system works, structure, templates, assets, hooks, overrides | +| **[Hummingbird]({{< relref "/9/themes/hummingbird" >}})** | The reference theme, CSS architecture, JavaScript conventions, accessibility, workflow | +| **[Create a theme]({{< relref "/9/themes/create-a-theme" >}})** | Step-by-step guides to build your own theme | +| **[Guidelines]({{< relref "/9/themes/guidelines" >}})** | Coding standards, browser compatibility, accessibility requirements | +| **[Reference]({{< relref "/9/themes/reference" >}})** | Lookup tables, template variables, JavaScript events, Smarty helpers | +| **[Distribution]({{< relref "/9/themes/distribution" >}})** | Validation, testing, and exporting your theme | diff --git a/themes/concepts/_index.md b/themes/concepts/_index.md new file mode 100644 index 0000000000..3e5c249560 --- /dev/null +++ b/themes/concepts/_index.md @@ -0,0 +1,23 @@ +--- +title: Theme concepts +menuTitle: Concepts +weight: 10 +chapter: true +showOnHomepage: true +--- + +# Theme concepts + +This section explains how the PrestaShop theme system works. These concepts apply to **any** PrestaShop theme — they are not specific to Hummingbird or any other theme implementation. + +| Page | Description | +|------|-------------| +| [Theme structure]({{< relref "/9/themes/concepts/theme-structure" >}}) | Directory layout, `theme.yml` reference, core assets | +| [Templates]({{< relref "/9/themes/concepts/templates" >}}) | Layouts, inheritance, listing pages, head, notifications | +| [Asset management]({{< relref "/9/themes/concepts/asset-management" >}}) | CSS/JS registration API, per-page assets, module integration | +| [Hooks]({{< relref "/9/themes/concepts/hooks" >}}) | Extension points for modules in the front office | +| [Overrides]({{< relref "/9/themes/concepts/overrides" >}}) | Module template/asset overrides and JS selector overrides | +| [Translation]({{< relref "/9/themes/concepts/translation" >}}) | Internationalization for theme wordings | +| [RTL support]({{< relref "/9/themes/concepts/rtl" >}}) | Right-to-left language stylesheet handling | + +For Hummingbird-specific architecture and conventions, see the [Hummingbird section]({{< relref "/9/themes/hummingbird" >}}). diff --git a/themes/concepts/asset-management.md b/themes/concepts/asset-management.md new file mode 100644 index 0000000000..a66ddd2b30 --- /dev/null +++ b/themes/concepts/asset-management.md @@ -0,0 +1,181 @@ +--- +title: Asset management +weight: 3 +--- + +# Asset management + +This page covers how PrestaShop registers, loads, and unregisters CSS and JavaScript assets in the front office. + +## Core assets + +PrestaShop automatically loads these files on every front-office page: + +| File | ID | Priority | Description | +|------|----|----------|-------------| +| `theme.css` | `theme-main` | 50 | Main theme stylesheet | +| `rtl.css` | `theme-rtl` | 900 | Loaded only for RTL languages | +| `custom.css` | `theme-custom` | 1000 | Empty override file, loaded last | +| `core.js` | `corejs` | 0 | Event system, `prestashop` object, jQuery (for module compat) | +| `theme.js` | `theme-main` | 50 | Main theme JavaScript | +| `custom.js` | `theme-custom` | 1000 | Empty override file, loaded last | + +{{% notice tip %}} +`custom.css` and `custom.js` are loaded last (priority 1000). Use them for quick overrides without modifying compiled theme files. +{{% /notice %}} + +## Registering assets + +PrestaShop's `FrontController` provides `registerStylesheet()` and `registerJavascript()`. Both take three arguments: + +1. **ID** — Unique identifier. Registering an asset with an existing ID **replaces** the previous one (same array key). Prefix with your theme/module name to avoid collisions. +2. **Relative path** — From the theme or PrestaShop root: + - `assets/css/product.css` for theme assets + - `modules/modulename/css/example.css` for module assets +3. **Options** — Configuration array (see tables below). + +### Stylesheet options + +| Name | Values | Description | +|------|--------|-------------| +| media | `all` \| `screen` \| `print` \| … (default: `all`) | CSS media type | +| priority | 0–999 (default: 50) | Lower number = loaded earlier in the HTML. Equal priorities keep registration order | +| inline | `true` \| `false` (default: `false`) | Inline in `