Themes: Hummingbird and Classic

Source: PrestaShop devdocs: Changes in 9.1

Hummingbird’s file sets configuration values (four products on the home page, PSR_ICON_COLOR, PSR_TEXT_COLOR for the reassurance block), disables three modules, moves modules between hooks (ps_searchbar and ps_mainmenu into displayTop, ps_languageselector, ps_currencyselector, ps_customersignin and ps_shoppingcart into displayNav2, the home blocks into displayHome, the footer blocks into displayFooterBefore, displayFooter and displayFooterAfter) and declares 17 image types. Activating a theme replaces every existing image type with the list in its theme.yml and does not regenerate the images. In the test installation, activating Classic after Hummingbird left 7 image types in ps_image_type (Classic’s six legacy types and stores_default) and Hummingbird’s 17 returned when it was activated again (count 17 after the switch back); after any switch run Design > Image Settings > Regenerate thumbnails, or bin/console prestashop:thumbnails:regenerate.

The validator ThemeValidator runs before activation. It requires the 13 properties name, display_name, version, author.name, meta.compatibility.from, meta.available_layouts, the six global_settings.image_types.* legacy types and theme_settings.default_layout, and 32 files: preview.png, config/theme.yml, assets/css/theme.css, assets/js/theme.js, templates/index.tpl, templates/contact.tpl, templates/_partials/form-fields.tpl, the product, product list, cart, cart empty, checkout and order confirmation templates, the four cms/ templates, the thirteen customer/ templates and errors/404.tpl and errors/forbidden.tpl. For a child theme, each file is looked for in the child and then in the parent, so a missing file is an error only if both lack it. The properties are not looked up in the parent.

That last point contradicts the "minimal child theme" in the developer guide, which lists only theme.yml and preview.png and a three-line theme.yml. The first child theme built for this page failed:

and the validator’s error list (obtained with the ThemeValidator service) was:

Copying the image_types block of the parent into the child’s theme.yml fixed it: the theme was enabled, ps_shop.theme_name became pcfgcoffee and ps_image_type held the 17 types. A child theme therefore carries its own image-type list, which is reasonable because activation replaces the shop’s image types with it.

Source: PrestaShop devdocs: Theme validation

A layout (templates/layouts/layout-*.tpl) is the HTML shell: <html>, <head>, <body>, the header, the breadcrumb, the columns and the footer. A page template (catalog/product.tpl, index.tpl, checkout/checkout.tpl) extends the layout held in the Smarty variable $layout, which the front controller sets from the theme settings, and fills the blocks. Hummingbird’s layout-both-columns.tpl is the root; it declares 21 named blocks: head, top_content, skip_to_main_content, hook_after_body_opening_tag, product_activation, header, breadcrumb, main_content, notifications, content_columns, container_class, left_column, content_wrapper, content, right_column, footer, javascript_bottom, bottom_elements, hook_before_body_closing_tag, modal_container and back_to_top. The other layouts only redefine the column blocks.

The dotted arrows are the {extends file=$layout} of the page templates, which change with the layout chosen for each page; the solid arrows are fixed {extends file='...'} relations. All of this was read from Hummingbird 2.1.2: layout-full-width, layout-left-column, layout-right-column and layout-content-only each extend layout-both-columns, page.tpl, catalog/product.tpl, catalog/listing/product-list.tpl, checkout/checkout.tpl and index.tpl extend $layout, cms/page.tpl and contact.tpl extend page.tpl, and catalog/listing/category.tpl extends catalog/listing/product-list.tpl.

Source: PrestaShop devdocs: Templates and layouts

A child template redefines only the blocks it needs. Smarty has three strategies, all of which were used in the child theme:

The Pocket Coffee product template appends the roast-date badge after the price block and exposes a custom hook for modules:

Source: PrestaShop devdocs: Template inheritance

With the product feature Roast date = 2026-10-26 attached to product 1, the rendered page contained:

The Coffee Club layout prepends a banner to the breadcrumb block of the full-width layout and is assigned to the CMS pages through theme_settings.layouts.cms:

Source: PrestaShop devdocs: Template inheritance

The delivery page (a CMS page) then had <body id="cms" class="... layout-club page-cms ..."> and contained the banner.

A child template with the same path as a parent template replaces it. To start from the parent version of the same path, extend it with the parent: prefix, as the product template above does. Without the prefix, {extends file='catalog/listing/category.tpl'} written inside the child’s catalog/listing/category.tpl points at itself. In the test shop this was not a Smarty error: the request died, the Apache log reported child pid ... exit signal Segmentation fault and a PHP fatal error Allowed memory size of 536870912 bytes exhausted in Smarty’s inheritance runtime, and the client received no response at all. With the parent: prefix the same template rendered normally. Extending a different base template (the catalog/listing/category-4.tpl below extending catalog/listing/category.tpl) is fine.

PrestaShop looks for a page template by locale and entity id, from the most specific name to the default, and each name is searched in the active theme first and in its parent second. For product 2 in en-US the order is:

Listing pages add a fallback to catalog/listing/product-list.tpl. In developer mode every template is wrapped in HTML comments that name the file that was actually used, which makes the order easy to confirm. Three files were created in the child theme (templates/catalog/listing/category-4.tpl, templates/catalog/product-1.tpl and templates/en-US/catalog/product-2.tpl) and the three pages showed <!-- begin catalog/listing/category-4.tpl, <!-- begin catalog/product-1.tpl and <!-- begin en-US/catalog/product-2.tpl, while the other products kept using catalog/product.tpl. An empty template file renders nothing: an empty override replaces the page with a blank one, which is how the first attempts at these files looked before they received content.

PrestaShop loads theme.css (id theme-main, priority 50), rtl.css for RTL languages (900), custom.css (1000), core.js (priority 0), theme.js (50) and custom.js (1000) on every page. Use custom.css and custom.js for quick overrides in a theme that is not compiled.

Extra files are registered in theme.yml (per page key or all), from a module with actionFrontControllerSetMedia, or in a controller’s setMedia():

Source: PrestaShop devdocs: Asset management

The product page of the test shop loaded the parent’s theme.css, then roast-badge.css and pocket-coffee.css from the child; the home page loaded only pocket-coffee.css from the child. The options are:

Registering an id that already exists replaces the asset with that id. To remove an asset of a module, register nothing under its path by placing an empty file at themes/<theme>/modules/<module>/views/css/style.css (only for local, relative paths), or call unregisterStylesheet('id') and unregisterJavascript('id') from actionFrontControllerSetMedia.

With use_parent_assets: true the parent’s compiled theme.css and theme.js are used. The rule PrestaShop applies is per file: it takes the child’s file if it exists and the parent’s file otherwise. That has a consequence that cost an hour in the test: the first version of the child theme contained an empty assets/js/theme.js (created to satisfy the idea that the validator wants it), and the product page then loaded the child’s empty script at the end of the page and none of Hummingbird’s 211,560-byte theme.js, so every interaction of the theme was gone. After the empty file was deleted the page loaded themes/hummingbird/assets/js/theme.js. The same holds for theme.css: do not create the file in a child theme unless you mean to replace the parent’s stylesheet (in that case use_parent_assets is usually false). A child with its own styles uses the registered files above and leaves theme.css and theme.js to the parent.

If you fork Hummingbird instead of using a child theme, the source is TypeScript and SCSS built with webpack. The scripts are npm ci, npm run build, npm run watch, npm run lint, npm run stylelint, npm run format, npm run test (Jest) and npm run storybook. Edit src/scss/ and src/js/, not the compiled assets/ output. The SCSS layout is abstract/ (variables, mixins), bootstrap/ (variable overrides and component restyling), prestashop/ (base/, components/, layout/, modules/, pages/) and vendors/, with entry points theme.scss, rtl.scss and error.scss. theme.scss fixes the CSS layer order:

Unlayered CSS, for example from modules, wins over layered CSS; this is intentional for backward compatibility. Custom classes follow BEM (.product-card, .product-card__title, .product-card--featured), selectors use classes only, no ids or tag selectors, and JavaScript hooks use data-ps-* attributes (data-ps-ref, data-ps-action, data-ps-target, data-ps-component, data-ps-state, data-ps-context, data-ps-observe, data-ps-data) rather than js- classes, although both coexist in 2.1.2. Events travel through the prestashop object: prestashop.on('updatedProduct', fn), prestashop.emit('myEvent', data), with constants in Theme.events.

Source: PrestaShop devdocs: Hummingbird CSS conventions

The following steps were run in the disposable 9.2.0 installation. The theme folder was copied to themes/pcfgcoffee and given to the web user.

Source: PrestaShop devdocs: Creating a child theme

Source: PrestaShop devdocs: Creating a child theme

After activation: ps_shop.theme_name was pcfgcoffee, the product page carried the badge, the child’s two stylesheets and the parent’s theme.css and theme.js, the home page showed the pcfg-featured-beans section, and the CMS pages used the layout-club body class. During development, set Smarty to force compilation (Advanced Parameters > Performance) and disable CCC so that CSS and JavaScript are served as separate files; the image default of PS_CSS_THEME_CACHE=1 combines them into assets/cache/theme-*.css.

bin/console prestashop:theme:export pcfgcoffee (or Design > Theme & Logo > Export current theme) writes a ZIP. The command printed Your theme has been correctly exported: /var/www/html/themes/pcfgcoffee.zip. The archive contained every file of the theme folder, an index.php guard in each directory, the module overrides and a translations/en-US/ folder generated for the theme. There is no exclusion list for files: clean node_modules/, .git/, source folders, IDE and CI files and any assistant-context files before exporting. Test activation on a clean installation and keep preview.png at 500 x 746 pixels. The Addons marketplace requires its own validation; the developer documentation has no theme checklist for Addons in 9.x, only the generic validation described above.

Source: PrestaShop devdocs: Exporting your theme

prestashop:theme:enable is the only theme command besides prestashop:theme:export. In 9.2.0 it failed in the test installation with Cannot build Language context as no languageId has been defined whenever activating the theme had to change the state of a module: switching from Classic to Hummingbird failed while blockwishlist was enabled (Hummingbird disables it), and switching to Classic failed while it was disabled. Disabling or enabling the module first with bin/console prestashop:module disable blockwishlist (or enable) made the same command succeed. The cause is in the command class: prestashop:module prepares the language context through ContextBuilderPreparer, prestashop:theme:enable does not. Activating from the back office is not affected, and a script can call $container->get(ContextBuilderPreparer::class)->prepareLanguageId(1) before dispatching EnableThemeCommand.

Hummingbird’s _partials/head.tpl is the place to look. The same blocks produced these tags on the product page of the test shop:

SEO habits that belong in theme work: one <h1> per page (Hummingbird prints the product name as h1 and uses h2 for section titles), friendly URLs on, a sitemap (a CMS page and a module), canonical URLs for filtered listings, image alt text from the product, and speed. The books tie speed to SEO (PrestaShop Recipes has a chapter on it); for a theme that means few render-blocking files (the build produces one theme.css), sized images from image_types with default_xs to default_xl for responsive sets, product_main and product_main_2x for retina screens, and the CCC options in Advanced Parameters > Performance in production.

Hummingbird is written against the European Accessibility Act: landmark elements (<nav>, <main>, <header>, <footer>), a "skip to main content" link (layout-both-columns has the block skip_to_main_content), aria-label on regions, keyboard navigation and visible focus. A child theme inherits all of it and should not remove it; custom templates follow the coding standards: semantic HTML5, BEM classes, 2-space indentation, <button> for actions and <a> for navigation.