Slider / Slideshow Management

Flow ID: AD-21 Module(s): sliders, Slider (domain) Complexity: Medium Last Updated: 2026-04-04

Business Overview

Three-level hierarchy: Slideshow Groups -> Sliders (Slideshows) -> Slides. Supports date-based display filtering (auto-cleanup of expired slides), audience targeting for personalized campaigns, YouTube video slides alongside images, per-language content (title, subtitle, discount text, button label, image, URL), and theme classes for visual styling. Both legacy admin controllers and a modern REST API with full CRUD operate on the same data model.

The slider system is used for homepage hero banners, category page promotions, and marketing campaigns. Slides can be time-boxed (scheduled start/end dates) and audience-targeted, making them a key tool for personalized merchandising.

API Reference

REST Endpoints (Modern Layer)

Group Endpoints:

Method	Path	Controller	Description
GET	/rest/slider/group	Advisable\Rest\Slider\Controllers\Group::index	List all groups (paginated, filterable)
GET	/rest/slider/group/item	Group::item	Get single group by filter
GET	/rest/slider/group/{id}	Group::show	Single group
POST	/rest/slider/group	Group::store	Create group
POST	/rest/slider/group/{id}	Group::update	Update group
DELETE	/rest/slider/group/{id}	Group::destroy	Delete group

Slider (Slideshow) Endpoints:

Method	Path	Controller	Description
GET	/rest/slider/slider	Advisable\Rest\Slider\Controllers\Slider::index	List all sliders (paginated, filterable)
GET	/rest/slider/slider/item	Slider::item	Get single slider by filter
GET	/rest/slider/slider/{id}	Slider::show	Single slider with translations
POST	/rest/slider/slider	Slider::store	Create slider (with MUI translations)
POST	/rest/slider/slider/{id}	Slider::update	Update slider
DELETE	/rest/slider/slider/{id}	Slider::destroy	Delete slider

Slide Endpoints:

Method	Path	Controller	Description
GET	/rest/slider/slide	Advisable\Rest\Slider\Controllers\Slide::index	List all slides (paginated, filterable)
GET	/rest/slider/slide/item	Slide::item	Get single slide by filter
GET	/rest/slider/slide/{id}	Slide::show	Single slide with translations
POST	/rest/slider/slide	Slide::store	Create slide (with MUI translations)
POST	/rest/slider/slide/{id}	Slide::update	Update slide
DELETE	/rest/slider/slide/{id}	Slide::destroy	Delete slide

All endpoints also support language-prefixed routes: /{lang}/rest/slider/... (e.g., /el/rest/slider/slide).

Total: 18 REST endpoints (6 per entity x 3 entities), each duplicated with language prefix = 36 route entries.

Legacy Admin Routes

Route	Controller	Description
sliders/slide_admin	Adv_slide_admin	Slide CRUD, image upload, YouTube, ordering
sliders/sliders_admin	Adv_sliders_admin	Slider CRUD, slide assignment
sliders/slideshow_groups_admin	Adv_slideshow_groups_admin	Minimal UI shell for group management
sliders/slideshow_groups_admin/api/*	AdvApiSlideshowGroupsEditorAdmin	REST-style API for group editor Vue component

Code Flow

Slide Creation via REST API

POST /rest/slider/slide
  |-- HandlesWriteActions::doStore()
  |     |-- Parse JSON body
  |     |-- WriteData::fromArray($data)
  |     |     |-- Map camelCase -> snake_case fields
  |     |     |-- audienceId, showButton, dateStart, dateEnd, themeClass, order
  |     |-- Validator::validateStore($writeData)
  |     |     \-- themeClass is required on create
  |     |-- WriteService::store($writeData)
  |     |     |-- WriteRepository::insert($writeData->toArray())
  |     |     |-- If translations provided:
  |     |     |     \-- MuiWriteRepository::insertMany($translations)
  |     |     \-- Return created entity
  |     \-- Return Resource with 201 status

Slide Display on Frontend (Date + Audience Filtering)

Adv_sliders_model::getSliderSlides($sliderId)
  |-- Query: slider_slides JOIN slide JOIN slide_mui
  |-- Date filter: NOW() BETWEEN date_start AND date_end (or dates are NULL)
  |-- Auto-cleanup: expired slides removed from slider_slides on fetch
  |-- Audience filter: slide.audience_id checked against customer audiences
  |     |-- EntityCustomerAudienceCheck::audiencesCheck($customerAudiences, $audienceId)
  |     |     |-- NULL audience_id -> show to all
  |     |     |-- criteria_type ALL (null) -> show to all
  |     |     |-- No criteria -> show to all
  |     |     \-- Check: in_array($audienceId, $customerAudiences)
  |-- Order: slide.order ASC
  \-- Limit: slider.slides_num (if set)

Group Management (Vue Component + API)

AdvApiSlideshowGroupsEditorAdmin
  |-- index(): GET all groups with slider count + view metrics
  |-- store(): POST create group (name + created_at)
  |-- update($id): POST update group name
  |-- destroy($id): DELETE group
  |     |-- Nullify slider.group_id and slider.group_order for orphaned sliders
  |     \-- Delete from slideshow_groups
  |-- updateOrder(): POST reorder sliders within a group
  |     \-- Batch update slider.group_order based on position array

YouTube Thumbnail Download

Adv_slide_admin::saveYoutubeThumbnail($youtubeId)
  |-- Try: download maxresdefault.jpg from YouTube
  |-- Fallback: download hqdefault.jpg if maxres not available
  |-- Save to files/sliders/ directory
  \-- Return filename for slide_mui.image field

Domain Layer

Modern Domain (src/Domains/Slider/)

Slide Entity:

File	Description
Slide/Repository/Entity.php	Properties: id, audience_id, show_button, date_start, date_end, theme_class, order. Implements FilterTranslation.
Slide/Repository/MuiEntity.php	MUI properties: id, slide_id, url, title, subtitle, discount, button_label, color_inverse, image, lang, descr, media_type, youtube_id
Slide/Repository/Repository.php	BaseRepository with translation filtering
Slide/Repository/MuiRepository.php	BaseMuiRepository for slide_mui
Slide/Repository/WriteRepository.php	Insert/update for slide table
Slide/Repository/MuiWriteRepository.php	Insert/update for slide_mui table
Slide/Repository/RepositoryConfigurator.php	Table name, relations, default includes
Slide/Repository/Specification/FilterByTranslation.php	Filter slides by MUI fields
Slide/Repository/Specification/SortByTranslation.php	Sort slides by MUI fields
Slide/Service.php	Read operations: match (paginated list), get (single)
Slide/WriteService.php	Write operations: store, update, destroy
Slide/WriteData.php	Value object: audienceId, showButton, dateStart, dateEnd, themeClass, order. OpenAPI-annotated.
Slide/MuiWriteData.php	Translation value object for slide_mui fields
Slide/Validator.php	Validates required fields (themeClass on create)
Slide/ListRequest.php	Filter/sort/pagination params

Slider Entity:

File	Description
Slider/Repository/Entity.php	Properties: id, name, group_id, group_order, slides_num. Implements FilterTranslation.
Slider/Repository/MuiEntity.php	MUI properties: id, slider_id, url, title, image, descr, lang
Slider/Repository/Repository.php	BaseRepository with translation filtering
Slider/Repository/MuiRepository.php	BaseMuiRepository for slider_mui
Slider/Repository/WriteRepository.php	Insert/update for slider table
Slider/Repository/MuiWriteRepository.php	Insert/update for slider_mui table
Slider/Service.php	Read operations
Slider/WriteService.php	Write operations
Slider/WriteData.php	Value object: name, groupId, groupOrder, slidesNum. OpenAPI-annotated.
Slider/MuiWriteData.php	Translation value object for slider_mui fields
Slider/Validator.php	Validates required fields (name on create)

Group Entity:

File	Description
Group/Repository/Entity.php	Properties: id, name, created_at
Group/Repository/Repository.php	BaseRepository
Group/Repository/WriteRepository.php	Insert/update for slideshow_groups
Group/Service.php	Read operations
Group/WriteService.php	Write operations
Group/WriteData.php	Value object: name, createdAt. OpenAPI-annotated.
Group/Validator.php	Validates required fields

DI Container:

• Domain: src/Domains/Slider/container.php
• REST: src/Rest/Slider/container.php

REST Controllers (src/Rest/Slider/Controllers/)

File	Description
Group.php	Extends HandlesRestfulActions + uses HandlesWriteActions. CRUD for slideshow groups.
Slider.php	Extends HandlesRestfulActions + uses HandlesWriteActions. CRUD for sliders with MUI.
Slide.php	Extends HandlesRestfulActions + uses HandlesWriteActions. CRUD for slides with MUI.

REST Resources (src/Rest/Slider/Resources/)

File	Description
Group/Resource.php / Collection.php	Group resource transformation
Slider/Resource.php / Collection.php	Slider resource
Slider/MuiResource.php / MuiCollection.php	Slider translations
Slide/Resource.php / Collection.php	Slide resource
Slide/MuiResource.php / MuiCollection.php	Slide translations

Legacy Admin Controllers (ecommercen/eshop/controllers/ or ecommercen/sliders/)

File	Lines	Description
Adv_slide_admin.php	~516	Slide CRUD: create/edit with image upload and YouTube support, ordering via drag-and-drop, audience targeting assignment
Adv_sliders_admin.php	~277	Slider CRUD: create/edit named slideshows, assign/remove slides, manage slide order within slider
AdvApiSlideshowGroupsEditorAdmin.php	~240	REST-style API for Vue-based group editor: CRUD + reorder, with view metrics integration
Adv_slideshow_groups_admin.php	~18	Minimal UI shell -- loads Vue component that calls the API controller

Architecture

Entity Hierarchy

Slideshow Group (slideshow_groups)
  |-- 1:N --> Slider (slider)  [via slider.group_id]
                |-- N:N --> Slide (slide)  [via slider_slides junction]
                |             |-- 1:N --> Slide MUI (slide_mui)  [per-language content]
                |-- 1:N --> Slider MUI (slider_mui)  [per-language metadata]

Key Features

• Date filtering: Slides only display if NOW() >= date_start AND NOW() <= date_end (or dates are NULL). Expired slides are auto-removed from slider_slides junction table on fetch.
• Audience targeting: Each slide has an optional audience_id FK. Frontend filtering uses EntityCustomerAudienceCheck trait to verify customer membership.
• YouTube support: slide_mui.media_type (0=image, 1=youtube) + slide_mui.youtube_id. Thumbnail auto-downloaded from YouTube (tries maxresdefault, falls back to hqdefault). Added via migration 20251229133112.
• Drag-and-drop ordering: Slides within sliders use slide.order field. Sliders within groups use slider.group_order field. Both support AJAX reorder.
• Cache: PSCache invalidation on any modification (clearCache('sliders')).
• Theme classes: slide.theme_class (0=default, 1=light, 2=dark) controls visual styling.
• Blog integration: Blogs can reference a slider_id for embedded slideshows (added via migration 20260224114108).

Data Model

slide Table

Column	Type	Description
id	INT(10) PK AI	Slide ID
audience_id	INT(11) NULL	FK to audience.id for targeting
show_button	TINYINT(1) DEFAULT 1	Whether to show CTA button
date_start	DATETIME NULL	Scheduled start date
date_end	DATETIME NULL	Scheduled end date
theme_class	TINYINT(4)	Theme: 0=default, 1=light, 2=dark
order	INT(10) NULL	Display order within slider

Index: audience_id.

slide_mui Table

Column	Type	Description
id	INT(10) PK AI	Translation ID
slide_id	INT(10)	FK to slide.id
url	TEXT	CTA link URL
title	VARCHAR(280) NULL	Slide title
subtitle	VARCHAR(255) NULL	Slide subtitle
discount	VARCHAR(255) NULL	Discount text overlay
button_label	VARCHAR(150) NULL	CTA button label
color_inverse	TINYINT(1) DEFAULT 0	Invert text color
image	TEXT	Image filename
media_type	INT DEFAULT 0	0=image, 1=youtube
youtube_id	VARCHAR(20) NULL	YouTube video ID
lang	VARCHAR(2)	Language abbreviation
descr	VARCHAR(400)	Description text

Indexes: slide_id, lang, (slide_id, lang).

slider Table

Column	Type	Description
id	INT(10) PK AI	Slider ID
name	VARCHAR(100)	Internal name
slides_num	INT(10) NULL	Max slides to display
group_id	INT(11) NULL	FK to slideshow_groups.id
group_order	INT(11) NULL	Order within group

slider_mui Table

Column	Type	Description
id	INT(10) PK AI	Translation ID
slider_id	INT(10)	FK to slider.id
url	TEXT NULL	Slider-level URL
title	VARCHAR(280) NULL	Slider title
image	TEXT NULL	Slider image
descr	MEDIUMTEXT NULL	Slider description (enlarged via migration 20241025134613)
lang	VARCHAR(2)	Language abbreviation

Indexes: slider_id, lang, (slider_id, lang).

slider_slides Junction Table

Column	Type	Description
slider_id	INT(10)	FK to slider.id
slide_id	INT(10)	FK to slide.id

Indexes: slide_id, slider_id, (slider_id, slide_id).

slideshow_groups Table

Column	Type	Description
id	INT(11) PK AI	Group ID
name	VARCHAR(255)	Group name
created_at	DATETIME	Creation timestamp

Related Migrations

Migration	Description
20241025134613_change_slider_descr_type_medium_text.php	slider_mui.descr changed from VARCHAR(400) to MEDIUMTEXT
20251229133112_add_youtube_support_to_slide.php	Added media_type (INT) and youtube_id (VARCHAR(20)) to slide_mui
20260224114108_blog_slider.php	Added slider_id column to blog table for embedded slideshows

Configuration

• Cache key: sliders -- invalidated via clearCache('sliders') on any slider/slide modification.
• Image upload directory: files/sliders/ for uploaded slide images and YouTube thumbnails.
• Audience targeting: Requires SMART_RECOMMENDATIONS.IS_ENABLED_CUSTOMER_TAG registry value to be enabled.
• DI modules: Registered in application/config/container/modules.php.

Client Extension Points

• Legacy controllers can be overridden in client repos by placing same-named files in application/controllers/.
• REST controllers can be overridden via DI alias in custom/Rest/Slider/container.php.
• Domain services can be extended via Custom\Domains\Slider\* with DI aliases.
• Additional slide fields can be added via migrations + MuiEntity extension in client repos.

Business Rules

Rule	Implementation
Slider deletion blocked if slides are linked	can_delete_record() check in legacy model
Group deletion orphans sliders	Nullifies group_id and group_order on child sliders
Date auto-cleanup	Expired slides removed from slider_slides junction on fetch
Audience + date combined	Frontend filters by both date range AND customer audience membership
YouTube thumbnail fallback	Tries maxresdefault.jpg, falls back to hqdefault.jpg
Slides_num limit	If slider.slides_num is set, only the first N ordered slides are shown
Multi-language images	Each language can have a different image via slide_mui.image
Order field	slide.order for within-slider; slider.group_order for within-group

Related Flows

• CF-01 Product Browsing -- category sliders display
• CF-12 Promotions Front -- home page slideshows
• CF-26 Home Page -- homepage hero banner slideshows
• AD-05 Category Management -- categories reference sliders via slider_id, menu_slider_id, extra_slider_id
• AD-12 Blog Admin -- blog articles can embed a slider via slider_id
• AD-19 Vendor Management -- vendor exclusive pages use slider assignment
• AD-22 Audience & Campaigns -- audience targeting for slides
• AD-13 Settings & Configuration -- SMART_RECOMMENDATIONS.IS_ENABLED_CUSTOMER_TAG feature flag
• SY-23 MUI Translation Pattern -- slide_mui companion table stores per-language slide content (title, subtitle, button label, image, description)
• SY-25 File Upload & Storage -- REST HandlesUploadActions and legacy controller handle per-language slide image uploads