README

vendor-logo the-real-world.de

description

Manage image sliders in the admin and show them in the shop. A slider consists of elements (slides), each with picture, optional alternative picture for small screens, title, description, link and display period. A slider is assigned to a page type and a position on that page.


Composer package	`therealworld/slider-module`
Module id	`trwslider`
Requires	OXID eShop CE `>=v7.4`, PHP `^8.3`, `therealworld/tools-plugin` `>=v3.6`, `therealworld/dynimg-module` `>=v1.0`

Installation

composer require therealworld/slider-module
vendor/bin/oe-console trw:module:setup trwslider

trw:module:setup (from therealworld/clirun-plugin) installs the module, runs its migrations and activates it. Without the clirun-plugin use the standard OXID steps (oe:module:install, the module migrations, oe:module:activate trwslider).

The migration creates the tables trwslider, trwslider2object, trwsliderelements and trwsliderelements2object (on PE/EE additionally the shop mapping). On activation the DB views are regenerated and the picture sizes are registered with trwdynimg.

Setting it up

In the module settings switch on the page types a slider may be assigned to, and the positions offered in the backend (all positions are off by default — without at least one, no position can be chosen).
Customer Info > Slider Settings: create a slider.
- Tab Main: name, active, period (from/till), and the assignment — start page with position, footer, or individual articles, categories and CMS pages with position. Each assignment block only appears when its page-type switch is on.
- Tab Extend: add elements. Per element: active, period (from/till), title, description, picture and alternative picture (upload), picture title (alt text and caption), link (free URL, or an assigned article or category), link target, full width, sort order (up/down); with "Individual slider-backgrounds & -buttons" also background colour, button colour and button background colour.
Check the frontend (see Frontend).

Pictures are uploaded to out/pictures/master/slider/ and out/pictures/master/slider_alternative/ and delivered in the configured size through trwdynimg. The alternative picture is shown below 481 px viewport width.

Configuration

Extensions > Modules > the-real-world - Slidermodule > Settings

Activate slider for page type ...

Controls which assignment options the slider's Main tab offers.

Option	Default
Startpage	on
Product-Detailpages	off
Categories	off
CMS-Pages	off
Footer	off

Display Slider positions in the backend

Which positions can be chosen when assigning a slider. A position already taken by another slider on the same object is not offered again.

Option	Default
Header Maincontent (`mainheader`)	off
Header Page (`pageheader`)	off
Header Page (alternative Version) (`pageheaderalternative`)	off
Footer Maincontent (`mainfooter`)	off

Slider Default position per page type

Option	Default
Startpage	Header Page
Product-Detailpages	Header Maincontent
Categories	Header Maincontent
CMS-Pages	Header Maincontent

If the chosen default position is not enabled above, the module falls back to its built-in default for that page type and saves it.

Slider Options

Option	Default	Effect
Use WYSIWYG-Editor for edit the sliderdescription	off	Element descriptions are edited with the admin's rich text editor (e.g. `trwrte`) and rendered as Twig/HTML in the frontend; otherwise plain text with line breaks
Individual slider-backgrounds & -buttons	off	Shows the colour fields per element
Format of Slider Picture	`1000*400`	Delivered size (width*height) of the picture
Format of alternative Slider Picture	`500*400`	Delivered size of the alternative picture

Frontend

The module renders the slider of position Header Page on the start page by itself. It hooks into the block start_welcome_text (flow-based themes) or start_newest_articles (Apex); a theme knowing both still shows the slider once.

All other positions and pages need the theme to include the widget, for example:

{% include "@trwslider/frontend/widget/slider/slider.html.twig" with {
    sCssClassPrefix: "mainheader",
    oSlider: oView.getMainHeaderSlider()
} %}

Source	Getters
Start page, category lists, product detail pages, CMS pages (`oView`)	`getPageHeaderSlider()`, `getPageHeaderAlternativeSlider()`, `getMainHeaderSlider()`, `getMainFooterSlider()`
Footer (`oViewConf`)	`getFooterSlider()`

Notes on the widget:

With more than one element it loads js/libs/tiny-slider.min.js and css/libs/tiny-slider.min.css from the theme — the theme must ship tiny-slider and initialise it on .tiny-slider-<prefix>.
Pictures load with native lazy loading; a theme with its own lazy loader passes sLazyPlaceholder. sLinkIconId / sLinkIconMarkup add an icon to the button.
On the start page the picture caption follows the theme parameter blSliderShowImageCaption.
The button text uses the module's language key TRWSLIDER_READ_MORE for article links and the shop's MORE_INFO for all other links; a theme can override both in its cust_lang.php.

Limits and caveats

Only active sliders whose own period covers the current time are shown; an empty from or till date means "no limit". The periods of the elements apply on top.
Deleting an article, category or CMS page removes its slider assignments.

For developers

Chain extensions

Core: Language (registers trwsliderelements as multi-language table), UtilsFile (picture types TRWSLIDER, TRWSLIDERALTERNATIVE), ViewConfig (getFooterSlider(), claimTrwSlider(), isTRWSliderUseWYSIWYG()).
Controllers: StartController, ArticleListController, ArticleDetailsController, ContentController (slider getters).
Models: Article, Category, Content (clean up assignments on delete).

Templates / blocks

page/shop/start.html.twig (all frontend themes): blocks trwslider_pageheader_welcome and trwslider_pageheader_newest — redefine them in a theme adapter to move or drop the start-page slider.
Widget @trwslider/frontend/widget/slider/slider.html.twig, elements in sliderelements.html.twig (block slider_elements).
Admin: headitem.html.twig (assets of the Extend tab), bottomnaviitem.html.twig ("Create New Slider"), shop_mall.html.twig (PE/EE: "Inherit all (TRW) Slider from parent shop").

Extension points

Slider::createConditionalSql(QueryBuilder) — add own conditions to the slider query.
ViewConfig::claimTrwSlider($placement) — returns true only for the first caller per page, to avoid rendering a placement twice.

Database

trwslider: sliders (multi-shop table)
trwslider2object: assignment slider → object (OXCLASS Start, Footer, Article, Category, Content) and position
trwsliderelements: elements (multi-language: title, description, picture title)
trwsliderelements2object: link target of an element (article or category)
Migrations in migration/data, table oxmigrations_trwslider.

Assets

Admin JS/CSS sources in resources/ (Vite), output in assets/src/.

therealworld / slider-module

Package info

Security

Statistics