PS PrestaShop Beginner

Category Banner: complete guide

Install, configure and run category banners: position and size in the grid, mobile image, link per language, date scheduling in the shop's time, subcategories, Creative Elements, multistore and troubleshooting for PrestaShop 1.7, 8 and 9.

Updated Module version 1.3.0

Overview and requirements

Category Banner inserts visuals into the product grid of your category pages, at the position you choose. You set the category, the product number the banner follows and the image to use for each language. The module handles the rest, including after a faceted filter or a page change.

  • Compatible with PrestaShop 1.7.6 to 9.x, verified on 1.7.8, 8.2.1 and 9.1.5: Classic and Hummingbird themes, derived themes, Creative Elements listings, CSS grid themes.
  • PHP 7.4 to 8.5.
  • Multistore and multilingual (fr, en, es, de, it, nl, pl, pt).
  • No override, no template change, no CRON task.
  • The banner markup is rendered server side by a Smarty template; the JavaScript only inserts it at the right place, with no jQuery and no third-party library.

Uploaded images are stored in /img/datafireflycategorybanner/, outside the module folder. They therefore survive module updates.

PrestaShop category page with a promotional banner inside the product grid and a full width sale banner
A one-cell banner after the first product and a full width sale banner in the Art category (Hummingbird theme, PrestaShop 9).

Installation

  1. Download the datafireflycategorybanner.zip archive from your customer account.
  2. In the back office, open Modules > Module Manager.
  3. Click Upload a module and drop the archive.
  4. Click Configure to reach the banner list.

On installation the module creates its three tables (banners, translations, shop association), creates the /img/datafireflycategorybanner/ folder and registers its hooks.

Back office list of the category banners: image, category, position, languages, size and scheduling
The banner list: category, position, languages that have an image, size and scheduling.

Creating a banner

From the configuration page, click Add new banner. The form groups the following settings.

Targeting

  • Category: the category the banner appears in. The list mirrors the shop tree, with disabled categories flagged.
  • Apply to subcategories: extends the banner to every subcategory of the chosen category, at any depth.
  • After product number: the banner is inserted after this product of the listing. A value of 4 places the banner after the fourth product displayed.
  • First page only: shows the banner on the first page of the listing only, without repeating it on page 2, 3 and so on.
Banner form: category, subcategories, position after a product, first page only, width, height and image display
Targeting, position, size in the grid and image display.
  • Banner link: destination URL, absolute (https://…) or starting with a slash (/new-arrivals). Leave empty for a non clickable banner.
  • Width in the grid: number of product columns the banner covers, from 1 to 4, or Full row. On screens that show fewer columns, the width is reduced automatically.
  • Height in the grid: number of product rows the banner covers, from 1 to 3. Available on CSS grid listings (Creative Elements, most recent themes).
  • Image display: Fill the banner area crops the image to the size of the cell, Keep the image proportions shows it in full.
  • CSS class: extra classes applied to the banner cell. Leave empty to reuse the product cell classes of your theme. With a width and height of 1, a size class of your theme (for example one that sets grid-area) still applies.
  • Custom CSS: declarations applied to this banner only, for example border-radius: 12px; padding: 10px;.

Scheduling and status

  • Start date and End date: display window, in YYYY-MM-DD HH:MM:SS format. An empty field means no limit on that side.
  • Active: shows or suspends the banner without deleting it.
  • Shop association: in multistore, tick the shops concerned.

Per-language images

The Banner image, Mobile image, Alt text and Link for this language fields exist for every active language. The language selector just above these fields shows the fields of the selected language. When an image is already in place, a preview appears alongside a Delete image switch that only affects that language.

Accepted formats: JPG, PNG, GIF, WebP and SVG, up to 4 MB. A width of 1200 px suits most grids.

Banner image, mobile image, alt text and link for each language of the shop
For each language: image, mobile image, alt text and optional link.

How the position is computed

The position is expressed as a number of products, and it applies to every page of the listing. A banner set to 4 appears after the fourth product of the current page, whether the visitor is on page 1 or page 3.

Several banners can target the same category, each at its own position. When two banners share the same position they are inserted one after the other, in save order. If the position exceeds the number of products displayed on the page, the banner is simply skipped for that page, without shifting the others.

By default the banner takes the place of one product cell. The Width in the grid and Height in the grid fields enlarge it, as explained below.

Mobile view of a PrestaShop category: the banner takes the place of a product in the two column grid
On mobile, the banner after the first product takes the place of a product in the two-column grid.

Each banner covers a block of product cells: 1 × 1 by default, up to 4 columns by 3 rows, or the full row. The products after the banner fill the cells left free, so the grid keeps no hole.

  • CSS grid listings (Creative Elements, most recent themes): width and height both apply. A 2 × 2 banner placed after the 4th product of a four-column grid takes the first two columns of rows 2 and 3, and products 5 to 8 sit beside it.
  • Bootstrap rows (Classic theme): the width applies, as a share of the row. The height follows the image.
  • Small screens: the width is capped at the number of columns displayed. A four-column banner on a two-column mobile grid becomes a full-row banner.

In fill mode the image covers the whole area, takes the height of the neighbouring products and is cropped from the centre. A full-row banner always keeps its proportions, since no product sits beside it to give it a height: use a landscape image for it.

For a 2 × 2 banner in fill mode, prepare an image slightly taller than wide and keep the key message in the centre, as the edges may be cropped.

Free shipping banner two columns wide and gift ideas banner between the products of a PrestaShop category
A 2 × 1 banner after the 4th product and a 1 × 1 banner after the 6th, in fill mode.
Two column free shipping banner taking the full width of the mobile product grid
On a two-column mobile grid, the 2 × 1 banner takes the full width.

Scheduling a campaign

Set a start date and an end date so a banner appears and disappears on its own. This is the right tool to prepare sales, Black Friday or a year-end campaign weeks in advance.

  • Start date only: the banner appears on that date and stays visible afterwards.
  • End date only: the banner shows immediately and stops on that date.
  • Both dates: the banner is visible only within that window.
  • No date: the banner is permanent.

Dates are entered and compared in the shop’s time, based on the time zone set in International > Localization, not in the visitor’s time. An end date entered without a time ends at 23:59:59.

Banner scheduling: start and end date picker in the shop time zone
Start and end dates with the PrestaShop date picker, in the shop’s time.

Covering a whole category tree

The Apply to subcategories option saves you from recreating the same banner in every aisle. Set on a parent category, the banner shows in that category and in all of its descendants.

Resolution relies on PrestaShop’s native nested tree (nleft and nright columns), so it costs no extra query per page. If you move categories around, PrestaShop recomputes those values and the scope follows automatically.

Images and languages

Each banner accepts artwork and alt text per language, which lets you adapt a message or a price to the market. When a language has not received its own artwork, the module displays the one from the shop’s default language rather than hiding the banner. The language’s own alt text is kept when it is filled in.

An optional mobile image can complement each artwork: it is served to screens up to 767 px wide, with its own dimensions. Prepare it in portrait format for a full row banner.

Image dimensions are read on upload and written into the HTML width and height attributes, which avoids layout shift on load. The banner visible when the page opens is loaded first (fetchpriority="high"), the others are deferred (loading="lazy"). Files are renamed with a random suffix and stored in /img/datafireflycategorybanner/.

Alt text is read by search engines and screen readers. Describe what the artwork shows rather than repeating the category name.

Full width sale banner with its dedicated mobile image on a smartphone
The full width banner shows its portrait mobile image on a phone.

Multistore

When the multistore feature is active, the form shows a Shop association block. A banner only appears in the shops you tick, and the back office list only shows the banners visible in the current shop context.

If no shop is ticked, the module associates the banner with the current context so that it never creates an orphan banner.

Faceted filters, sorting and pagination

On PrestaShop 8 and 9, faceted filters, sorting and pagination reload the product list over AJAX without reloading the page. The module watches the listing: as soon as new product cells appear, after a filter, a page change, a load more button or infinite scroll, it puts the banners back at the right positions. It also listens to PrestaShop’s updateProductList event.

The product grid is found from the products themselves (data-id-product and product-miniature markers), not from the classes of a given theme. This covers the Classic theme, Creative Elements listings and most custom themes.

CSS and JavaScript are loaded on category pages only, and only when the current category has at least one active and displayable banner.

Settings: product grid selector

Below the banner list, the Settings panel holds a single field, Product grid selector. Leave it empty: the grid is detected automatically.

Only if banners never show on a theme with an unusual structure, enter the CSS selector of the element that directly contains the product cells, for example #js-product-list .products or .ce-products. When the grid cannot be found, the module prints a [DataFirefly Category Banner] warning in the browser console.

What’s new in version 1.3.0

Version 1.3.0 fixes several issues found during a full review on PrestaShop 1.7.8, 8.2.1 and 9.1.5, and adds a few settings.

  • Mobile image: each language accepts a second image, displayed on screens up to 767 px wide. This helps with a full row banner, which is hard to read in landscape format on a phone.
  • Link per language: an optional link per language replaces the common link, so you can point to a page whose address is translated, for example /en/content/1-delivery.
  • First page only: the banner is no longer repeated on page 2, 3 and so on of the listing. It shows again as soon as the visitor returns to page 1 or applies a filter.
  • Date picker: the calendar in the form now fills in the right format. An end date entered without a time ends at 23:59:59.
  • Shop time: dates are compared against the shop’s time. Previously the MySQL server clock, often set to UTC, shifted the start and end by one to two hours.
  • Core Web Vitals: banners are inserted right after the product grid (displayFooterCategory hook), before the first render, which removes layout shift (CLS). The banner visible when the page opens is loaded first, the following ones are deferred.
  • Image security: SVG files that contain a script, an event handler or external content are rejected, and the /img/datafireflycategorybanner/ folder gets its own .htaccess (images only, SVG isolated). A rejected image no longer creates an empty banner.
  • WebP on PrestaShop 1.7: WebP images are accepted and served correctly.
  • Back office list: an Images column shows the languages that have artwork, and ended or scheduled banners are flagged.

To upgrade, install the 1.3.0 archive over the current version from the module manager. Your banners and images are kept. Then clear the PrestaShop cache and the cache of any performance module.

Upgrading to version 1.2.0

Install the 1.2.0 archive over the previous version from the module manager. The upgrade script adds the size and image display columns, plus the grid selector setting. Existing banners keep their current look: 1 × 1, image proportions kept. Edit a banner to give it another size or switch it to fill mode.

The front script changes in this version. After the upgrade, clear the PrestaShop cache and the cache of any performance module (CCC, page cache, minification), otherwise the previous script keeps being served.

Upgrading from version 1.0.0

Simply install the new archive over the old one from the module manager. The upgrade script takes care of:

  • adding the scope, scheduling and image dimension columns;
  • creating the shop association table and carrying over the original shop of each banner;
  • moving existing images from views/img/banners/ to /img/datafireflycategorybanner/ and reading their dimensions;
  • removing a hook that is no longer needed.

Your banners, their positions and their artwork are preserved.

FAQ and troubleshooting

The banner does not show on the category page

Check in order: the banner is active; today’s date falls within the scheduling window; the targeted category is the one being browsed, or the subcategory scope is on; the displayed language has an image, or the default language has one; in multistore, the current shop is ticked. Finally, clear the PrestaShop cache.

On a listing built with Creative Elements or another page builder, check that the module runs version 1.2.0 or later: earlier versions only recognised the Classic theme grid. Then open the browser console: a [DataFirefly Category Banner] warning means the grid was not found, see the Settings section.

The banner appears in the wrong place

The position counts the products of the current page. If your listing shows 12 products per page, a banner at position 20 will never appear. Lower the value or raise the number of products per page.

The banner breaks the grid layout

Set the size with the Width in the grid and Height in the grid fields rather than with grid classes, and empty the CSS class field unless your theme provides a size class. Avoid mixing classes from different grid systems.

The banner disappears after filtering

Since version 1.2.0 the module re-inserts the banners as soon as new product cells appear in the listing, whatever the filter module. If the banner still disappears, open the browser console: a [DataFirefly Category Banner] warning means the grid was not found after the refresh. Enter the grid selector in the Settings panel, and contact support if the problem persists.

The image refuses to upload

The module accepts JPG, PNG, GIF, WebP and SVG files up to 4 MB. Also check that /img/datafireflycategorybanner/ is writable and that the PHP upload_max_filesize and post_max_size directives are larger than the file.

Only URLs starting with http://, https:// or a slash are accepted. This guards against javascript: and data: injection.

What happens on uninstall?

The module drops its tables and removes the /img/datafireflycategorybanner/ folder together with the artwork it holds. Back up your images if you plan to reinstall later.

Was this page helpful?

Still stuck? Contact support