README

Complete banner slider solution with responsive images, video support, WebP/AVIF variants and a visual cropper.

Overview

This metapackage installs the four Banner Slider packages at matching versions. Together they manage sliders of image, video and custom HTML banners, crop every image per breakpoint, and render the slider on the storefront with Splide.js.

Included Packages

The admin and storefront packages depend only on the API package's contracts; the core implements them.

Key Features

Banners

• Image banners with a crop per slider breakpoint
• Video banners: YouTube, Vimeo, or uploaded MP4/WebM files. A regular video shows a poster with a play button and loads the player on click; a background video plays muted and loops. YouTube and Vimeo embeds are privacy-enhanced by default.
• Custom HTML banners, rendered through the CMS filter
• Link URL with same-tab or new-tab target, title, position and a from/to schedule

Responsive images

• Breakpoints per slider, each with a media query, a minimum width and a target size
• WebP and AVIF variants per crop. The format list is open: a new format is one registry entry and an encoder.
• The admin browser may encode the variants (WASM); anything it does not send, or that fails validation, is encoded on the server (GD, Imagick, cwebp, cavif)
• <picture> output, widest breakpoint first, with the crop's width and height on every source to avoid layout shift

Sliders

• Store view and customer group targeting, including "all customer groups"
• Placement by location code or by slider id; the lowest priority value wins a shared location
• Slide or fade effect, loop, autoplay with interval and a pause/play button that can be switched off, arrows, pagination, lazy loading
• Slides per page from each viewport width upwards, with an optional gap
• Preload links for the first banners (LCP)

Operations

• Full-page cache tags per slider, banner and location, cleaned on save and when a schedule opens or closes (cron, every 5 minutes)
• bin/magento banner-slider:crops:regenerate: re-encode crops on the server
• bin/magento banner-slider:media:cleanup --dry-run: list media files no row references; an optional daily sweep deletes them once enabled
• Works on themes with RequireJS (Luma) and without it (Hyvä), with plain CSS and no preprocessor

Requirements

• PHP 8.3 or 8.4
• Magento Open Source or Adobe Commerce 2.4.7 or later
• Composer 2

Installation

composer require hryvinskyi/magento2-banner-slider-pack:^2.0
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

In production mode also run bin/magento setup:static-content:deploy.

Upgrading from 1.x

1. Back up the hryvinskyi_banner_slider* tables. The migration is one-way: it moves data into new tables and drops the old columns, and 1.x cannot run on the migrated schema. The dump is the only way back.

2. Update custom code written against the 1.x API. Removed and changed contracts are listed in the API package changelog.

3. Upgrade all packages together through the pack:

   composer require hryvinskyi/magento2-banner-slider-pack:^2.0
   bin/magento setup:upgrade
   bin/magento setup:di:compile

4. Deploy static content in production mode, flush the cache, and purge Varnish or any other page cache: cached pages still reference 1.x storefront assets.

Data migrates automatically during setup:upgrade: store views and customer groups, crop formats, responsive items, media paths, image sizes and whole-image crops. Sliders hidden in 1.x stay hidden. The core package README lists every step and what it logs.

Themes and CMS content keep working: the block class Hryvinskyi\BannerSliderFrontendUi\Block\Widget\Slider, the template Hryvinskyi_BannerSliderFrontendUi::slider.phtml and the location and slider_id arguments are unchanged. Admin role assignments keep working too, because the ACL resource ids keep their Hryvinskyi_BannerSlider:: prefix.

hryvinskyi/magento2-media-uploader is no longer needed; remove it if nothing else uses it.

Configuration

Stores > Configuration > Hryvinskyi Extensions > Banner Slider

• Images: default variant formats for new crops, WebP and AVIF quality, largest upload
• Video: privacy-enhanced embeds, largest upload
• Media: the daily orphan media sweep (off by default; check banner-slider:media:cleanup --dry-run first)

Usage

Sliders and banners

1. Content > Banner Slider > Sliders: create a slider, set its location, store views, customer groups, carousel options and breakpoints.
2. Content > Banner Slider > Banners: create a banner, pick its slider and type, upload the image or video or enter the HTML, and crop the image for each breakpoint.

Placing a slider

CMS page or block:

{{widget type="Hryvinskyi\BannerSliderFrontendUi\Block\Widget\Slider" slider_id="1" template="Hryvinskyi_BannerSliderFrontendUi::slider.phtml"}}

Layout XML, by location:

<referenceContainer name="content">
    <block class="Hryvinskyi\BannerSliderFrontendUi\Block\Widget\Slider" name="banner.slider"
           template="Hryvinskyi_BannerSliderFrontendUi::slider.phtml">
        <arguments>
            <argument name="location" xsi:type="string">homepage</argument>
        </arguments>
    </block>
</referenceContainer>

Use a slider_id argument (xsi:type="number") instead of location to place one slider by id.

Database Schema

Dependencies

Installed automatically with the packages:

• hryvinskyi/magento2-base, hryvinskyi/magento2-configuration-fields (admin)
• hryvinskyi/magento2-splide-js, hryvinskyi/magento2-head-tag-manager (storefront)
• hryvinskyi/image-binaries (the cwebp and cavif encoders), symfony/process, symfony/console, psr/clock, psr/log

Support

• Report issues: https://github.com/hryvinskyi/magento2-banner-slider-pack/issues
• Email: volodymyr@hryvinskyi.com

Author

Volodymyr Hryvinskyi

• Email: volodymyr@hryvinskyi.com
• Website: https://hryvinskyi.com

License

MIT License - see LICENSE file for details

Changelog

See CHANGELOG.md for detailed version history.