Category Banner: complete guide

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 8.0 to 9.x, Classic theme and derived themes.
• PHP 7.4 to 8.3.
• 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.

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.

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.

Appearance and link

• Banner link: destination URL, absolute (https://…) or starting with a slash (/new-arrivals). Leave empty for a non clickable banner.
• CSS class: grid classes applied to the banner cell, for example col-12 or col-12 col-md-6. Leave empty to reuse the product cell classes of your theme automatically.
• 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 and Alt text fields exist for every active language. The language tabs at the top of the form show 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.

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 width of a product cell: the module reads the grid classes of the first product in the list and applies them to the banner. Fill in the CSS class field to force another width, for example a full-width banner with col-12.

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.

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.

Image dimensions are read on upload and written into the HTML width and height attributes, which avoids layout shift on load. Files are renamed with a random suffix and stored in /img/datafireflycategorybanner/.

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 listens to PrestaShop’s updateProductList event, removes the previous banners and re-inserts them at the right positions after every DOM refresh.

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

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.

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

Empty the CSS class field so the banner reuses the product cell classes of your theme. For a full-width banner, enter col-12. Avoid mixing classes from different grid systems.

The banner disappears after filtering

The module hooks back onto the updateProductList event. If your theme or a third-party filter module replaces the whole product list container without firing that event, re-insertion cannot happen. Contact support with the name of your theme and filter module.

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.

The banner link is rejected

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.