Download the PHP package lindemannrock/craft-slideshow-manager without Composer

Slideshow Manager for Craft CMS

A comprehensive slideshow management plugin with Swiper.js integration for Craft CMS 5.x.

License

This is a commercial plugin licensed under the Craft License. It will be available on the Craft Plugin Store soon. See LICENSE.md for details.

⚠️ Pre-Release

This plugin is in active development and not yet available on the Craft Plugin Store. Features and APIs may change before the initial public release.

Table of Contents

• Slideshow Manager for Craft CMS
  • Table of Contents
  • Quick Start
  • Features
  • Requirements
  • Installation
  • Via Composer
  • Using DDEV
  • Via Control Panel
  • Custom Swiper Installation
  • Option 1: Using npm (Recommended for Production)
  • Option 2: Using CDN (Default)
  • Option 3: Custom CDN or Version
  • Configuration
  • Plugin Settings
    • General Settings
    • Swiper Configuration Tabs
  • Config File
  • Environment-Specific Configuration
  • Usage
  • Field Types
    • Slideshow Config Field
  • Global Settings
  • Template Usage
    • Basic Slideshow
    • With Debug Logging
    • With Runtime Overrides
    • With Visibility Classes
  • Template Variables
    • settings
    • buildSwiperConfig(config, sliderId)
    • buildCssVars(cssVars)
    • initSlider(sliderId, overrides, debug)
    • getVisibilityClasses(visibility)
  • CSS Custom Properties
  • Available CSS Variables
    • Theme
    • Navigation
    • Pagination
    • Scrollbar
    • Other
  • Usage Pattern
  • Swiper Configuration
  • Examples
  • Logging
  • Log Levels
  • Configuration
  • Log Files
  • Log Management
  • Troubleshooting
  • Slideshow Not Initializing
  • Navigation/Pagination Not Showing
  • CSS Variables Not Working
  • Field Not Saving
  • Support
  • License

Quick Start

Get up and running with Slideshow Manager in 5 minutes:

1. Install the plugin

2. Configure global settings (optional)

• Go to Slideshow Manager → Settings in the Control Panel
• Configure default Swiper behavior (navigation, pagination, autoplay, etc.)
• Set CSS custom properties for styling

3. Add a field to your section

• Go to Settings → Fields
• Create a new "Slideshow Config" field (for per-entry config)
• Add it to your entry type

4. Use in templates

That's it! Your slideshow is live. See Examples for comprehensive use cases.

Features

• Automatic Asset Loading: CSS and JS automatically injected when enabled in settings
• Two Field Types: Slideshow field (Matrix-based) and Config field (per-entry settings)
• Comprehensive Configuration: 30+ Swiper options across 5 organized settings tabs
• Per-Entry Customization: Optional config field for entry-specific slideshow settings
• Responsive Controls: Breakpoint-based configuration with visual UI
• Visibility Management: Control navigation/pagination display per device (mobile/desktop)
• CSS Custom Properties: Full Swiper styling customization via CSS variables
• Config File Overrides: Environment-specific settings
• Helper Methods: Simple template methods for initialization and config transformation
• Integrated Logging: Built-in logging with configurable levels

Requirements

• Craft CMS 5.0.0 or later
• PHP 8.2 or later
• Logging Library 5.0 or greater (installed automatically as dependency)

Installation

Via Composer

Using DDEV

Via Control Panel

In the Control Panel, go to Settings → Plugins and click "Install" for Slideshow Manager.

Note: Frontend assets are pre-built and included. No build step required for installation.

Custom Swiper Installation

By default, the plugin auto-loads Swiper from CDN. However, you can use your own Swiper installation:

Option 1: Using npm (Recommended for Production)

1. Install Swiper via npm:

2. Import in your JavaScript:

Note: Only import the modules you need. Available modules include:

• Navigation, Pagination, Scrollbar
• Autoplay, EffectFade, EffectCube, EffectFlip, EffectCoverflow, EffectCards, EffectCreative
• Grid, FreeMode, Thumbs, Parallax, Zoom
• Keyboard, Mousewheel, HashNavigation, History, Controller, A11y, Virtual, Manipulation

See Swiper Modules Documentation for complete details.

3. Disable auto-loading in plugin settings:

Via Control Panel:

• Go to Slideshow Manager → Settings → General
• Disable "Auto Load Swiper CSS"
• Disable "Auto Load Swiper JS"

Or via config file:

4. Use the plugin normally: The initSlider() helper will use your bundled Swiper installation automatically.

Option 2: Using CDN (Default)

The plugin auto-loads Swiper from CDN when enabled in settings:

• CSS: https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css
• JS: https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js

This is the easiest option but may not be ideal for production due to:

• Additional HTTP requests
• No control over caching
• Dependency on external CDN availability

Option 3: Custom CDN or Version

You can use a different CDN or Swiper version by:

1. Disabling auto-loading in settings
2. Loading Swiper manually in your template:

Configuration

Plugin Settings

Settings can be configured in the Control Panel at Slideshow Manager → Settings, or via a config file.

General Settings

• Plugin Name: Customize the plugin display name
• Auto Load Swiper CSS: Automatically inject Swiper CSS on frontend pages
• Auto Load Swiper JS: Automatically inject Swiper JS on frontend pages
• Enable Cache: Cache slideshow data for better performance
• Cache Duration: How long to cache data (in seconds)
• Log Level: Logging verbosity (debug, info, warning, error)

Swiper Configuration Tabs

• Basic Settings: Navigation, pagination, autoplay, effects, loop
• Layout & Responsive: Slides per view, spacing, grid mode, breakpoints
• Controls: Keyboard, mousewheel, scrollbar, hash navigation
• Advanced: Free mode, lazy loading, parallax, zoom, virtual slides

Config File

Create a config/slideshow-manager.php file to override default settings:

Settings defined in the config file will override CP settings.

Environment-Specific Configuration

See Configuration Documentation for all available options.

Usage

Field Types

Slideshow Config Field

The Config field stores per-entry Swiper configuration:

1. Go to Settings → Fields
2. Create a new field, select "Slideshow Config"
3. Add to entry types where custom config is needed
4. Configure in entries:
   • Navigation (on/off, visibility controls)
   • Pagination (on/off, type, visibility controls)
   • Autoplay (enabled, delay, disable on interaction)
   • Loop, Speed, Effect
   • Slides Per View, Spacing, Centered Slides
   • Grid Mode
   • Responsive Breakpoints

Global Settings

Configure default Swiper settings at Slideshow Manager → Settings:

• General: Plugin name, asset loading, caching, logging
• Basic Settings: Navigation, pagination, autoplay, effects, loop
• Layout & Responsive: Slides display, grid mode, breakpoints
• Controls: Keyboard, mousewheel, scrollbar, hash navigation
• Advanced: Free mode, lazy loading, parallax, zoom, virtual slides

Template Usage

Basic Slideshow

With Debug Logging

This outputs initialization details to the browser console.

With Runtime Overrides

With Visibility Classes

Visibility options:

• default - Always visible
• hide-mobile - Hidden on mobile, visible on desktop
• hide-desktop - Visible on mobile, hidden on desktop
• mobile-only - Only visible on mobile
• desktop-only - Only visible on desktop

Template Variables

settings

Access plugin settings:

Returns: Settings model with all plugin configuration

buildSwiperConfig(config, sliderId)

Transforms flat field structure into nested Swiper format:

Parameters:

• config (array) - Merged configuration (field + global)
• sliderId (string) - Unique identifier for this slider

Returns: Array ready for Swiper initialization

buildCssVars(cssVars)

Builds inline CSS custom properties for Swiper styling:

Parameters:

• cssVars (array|null) - Optional CSS variables (uses settings if null)

Returns: String of CSS custom properties for inline style

initSlider(sliderId, overrides, debug)

Initializes Swiper for a specific slider:

Parameters:

• sliderId (string, required) - The unique slider ID
• overrides (array, optional) - Override/extend config at runtime
• debug (bool, optional) - Enable console logging

Returns: Empty markup (JS is registered with Craft's view)

getVisibilityClasses(visibility)

Gets CSS classes for navigation/pagination visibility:

Parameters:

• visibility (string) - Visibility option (default, hide-mobile, hide-desktop, mobile-only, desktop-only)

Returns: CSS classes string

CSS Custom Properties

Slideshow Manager supports full Swiper styling customization via CSS custom properties. These can be configured globally in settings or per-slideshow via the buildCssVars() method.

Available CSS Variables

Theme

• themeColor - Main theme color

Navigation

• navigationSize - Navigation button size
• navigationTopOffset - Top offset for navigation
• navigationSidesOffset - Side offset for navigation
• navigationColor - Navigation icon color
• navigationInactiveColor - Inactive navigation color
• navigationBg - Navigation background
• navigationBgHover - Navigation background on hover
• navigationPadding - Navigation padding
• navigationBorderColor - Navigation border color
• navigationBorderColorHover - Navigation border color on hover
• navigationShadow - Navigation shadow
• navigationShadowHover - Navigation shadow on hover

Pagination

• paginationColor - Active pagination color
• paginationBulletSize - Bullet size
• paginationBulletWidth - Bullet width
• paginationBulletHeight - Bullet height
• paginationBulletInactiveColor - Inactive bullet color
• paginationBulletInactiveOpacity - Inactive bullet opacity
• paginationBulletOpacity - Active bullet opacity
• paginationBulletHorizontalGap - Horizontal gap between bullets
• paginationBulletVerticalGap - Vertical gap between bullets
• paginationFractionColor - Fraction text color
• paginationProgressbarBgColor - Progressbar background
• paginationProgressbarSize - Progressbar size
• paginationLeft - Left position
• paginationRight - Right position
• paginationTop - Top position
• paginationBottom - Bottom position

Scrollbar

• scrollbarBorderRadius - Scrollbar border radius
• scrollbarTop - Top position
• scrollbarBottom - Bottom position
• scrollbarLeft - Left position
• scrollbarRight - Right position
• scrollbarSidesOffset - Side offset
• scrollbarBgColor - Background color
• scrollbarDragBgColor - Drag handle background
• scrollbarSize - Scrollbar size

Other

• thumbActiveColor - Active thumbnail color
• slideBgColor - Slide background color

Usage Pattern

All CSS variables use a fallback pattern for easy customization:

This allows you to override in your own CSS:

Swiper Configuration

The plugin supports all Swiper.js configuration options. Configuration can be set:

1. Globally - In plugin settings or config file
2. Per-Entry - Using the Slideshow Config field
3. At Runtime - Via initSlider() overrides parameter

See Swiper API Documentation for all available options.

Examples

For comprehensive examples covering all features, see docs/examples.md.

Includes examples for:

• Basic slideshow setup
• Custom styling with CSS variables
• Runtime config overrides and debug mode
• Grid mode and different effects (fade, cube, coverflow, cards)
• Responsive visibility controls
• Autoplay configurations
• Responsive breakpoints
• Multiple sliders on one page
• Custom Swiper installation (npm/yarn/pnpm)
• Programmatic control and accessing Swiper instances
• Advanced techniques like thumbnail navigation

Logging

Slideshow Manager uses the LindemannRock Logging Library for centralized logging.

Log Levels

• Error: Critical errors only (default)
• Warning: Errors and warnings
• Info: General information
• Debug: Detailed debugging (includes performance metrics, requires devMode)

Configuration

Note: Debug level requires Craft's devMode to be enabled. If set to debug with devMode disabled, it automatically falls back to info level.

Log Files

• Location: storage/logs/slideshow-manager-YYYY-MM-DD.log
• Retention: 30 days (automatic cleanup via Logging Library)
• Format: Structured JSON logs with context data
• Web Interface: View and filter logs in CP at Slideshow Manager → Logs

Log Management

Access logs through the Control Panel:

1. Navigate to Slideshow Manager → Logs
2. Filter by date, level, or search terms
3. Download log files for external analysis
4. View file sizes and entry counts
5. Auto-cleanup after 30 days (configurable via Logging Library)

Requires: lindemannrock/logginglibrary plugin (installed automatically as dependency)

See docs/LOGGING.md for detailed logging documentation.

Troubleshooting

Slideshow Not Initializing

Check browser console:

• Look for JavaScript errors
• Verify Swiper.js is loaded
• Check data-swiper-config attribute exists

Verify auto-loading is enabled:

• Go to Settings → Slideshow Manager → General
• Ensure "Auto Load Swiper JS" is enabled

Clear caches:

Navigation/Pagination Not Showing

Check config:

• Verify navigation or paginationEnabled is true in your config
• Check visibility settings aren't hiding elements

Check element classes:

• Navigation: .swiper-button-prev-{{ sliderId }} and .swiper-button-next-{{ sliderId }}
• Pagination: .swiper-pagination-{{ sliderId }}

CSS Variables Not Working

Verify auto-loading:

• "Auto Load Swiper CSS" must be enabled in settings

Check config:

• CSS vars must be configured in settings or config file
• Use buildCssVars() in template

Browser support:

• CSS custom properties require modern browsers
• IE11 not supported

Field Not Saving

Check permissions:

• Verify user has permission to edit entries

Clear caches:

• Clear Craft caches and reload the entry
• Check browser console for errors

Verify Live Preview:

• Field works differently in Live Preview mode
• Save the entry to persist changes

Support

• Documentation: https://github.com/LindemannRock/craft-slideshow-manager
• Issues: https://github.com/LindemannRock/craft-slideshow-manager/issues
• Email: [email protected]

License

This plugin is licensed under the Craft License. See LICENSE.md for details.

Developed by LindemannRock