README

A versatile carousel module for Silverstripe websites, featuring support for images and videos. The default template utilizes Bootstrap classes for seamless integration.

Requirements
Installation
Configuration
Usage
- Adding a Carousel to a Page
- Working with Images and Videos
Maintenance tasks
- Removing slides no carousel uses
Customization
- Creating Custom Templates
Other Modules Using Silverstripe Carousel
Maintainers
Bugtracker
Development and Contribution
License

Requirements

PHP: ^8.3
silverstripe/recipe-cms: ^6
fromholdio/silverstripe-embedfield: ^5.1
jonom/focuspoint: ^6
silverstripe/linkfield: ^5
symbiote/silverstripe-gridfieldextensions: ^5
unclecheese/display-logic: ^4.0

Installation

composer require dynamic/silverstripe-carousel

Features

Multi-format Slides: Support for both image and video slides in a single carousel
Image Management: Integration with Jonom FocusPoint for smart image cropping and focal points
Video Embedding: Embed videos from YouTube, Vimeo, and other platforms via EmbedField
Link Integration: Use SilverStripe LinkField for flexible slide linking (pages, URLs, files, email)
Customizable Display: Configure autoplay, interval timing, pause on hover, and show/hide indicators
Bootstrap 5 Templates: Default templates using Bootstrap 5 carousel component for responsive design
Drag-to-Reorder: Easy slide management with GridField OrderableRows
Page Extension: Simple integration via CarouselPageExtension for any page type

Configuration

Apply the CarouselPageExtension to your desired page types in your YAML configuration:

Page:
  extensions:
    - Dynamic\Carousel\Extension\CarouselPageExtension

After applying the extension, run a dev/build to update the database schema.

Usage

Adding a Carousel to a Page

To display the carousel, include the following template in your page layout:

<% include Dynamic/Carousel/Includes/Carousel %>

Ensure that your template has access to the $Carousel variable, which contains the carousel data.

Working with Images and Videos

The module supports two types of content:

Images: For displaying images.
Videos: For embedding videos.

To add these:

In the CMS, navigate to the page where you have enabled the carousel.
Click on the "Carousel" tab.
Use the "Add Slide" button to add either an Image or Video.
For Images:
- Upload or select an image from the files.
- Optionally, add a caption or link.
For Videos:
- Provide the video URL (supports platforms like YouTube and Vimeo).
- Optionally, add a caption.

Repeat these steps to add multiple images or videos as needed.

Maintenance tasks

Removing slides no carousel uses

Because a Slide can be in more than one carousel, removing a carousel never removes its slides (see issue #55), so slides that no carousel lists any more stay in the database, and there is no CMS screen for them. This task finds them:

# List them (dry run, the default - changes nothing)
sake tasks:carousel-unused-slide-cleanup

# Archive them, on draft and live
sake tasks:carousel-unused-slide-cleanup --archive

Archiving, not deleting: doArchive() drops the row from draft and live but keeps its version history, so a mistaken run is not data loss - the slide comes back with Versioned::get_latest_version(Slide::class, $id)->writeToStage(Versioned::DRAFT). Slide has no CMS screen of its own, so that restore is code rather than a button. The task refuses to archive anything if a carousel owner could not be read, since that owner's slides would then look unused; it warns and exits non-zero instead.

Customization

Creating Custom Templates

If you are not using Bootstrap or wish to customize the carousel appearance:

Locate the Default Template
The default template is located at:
```
templates/Dynamic/Carousel/Includes/Carousel.ss
```
Copy to Your Theme
Copy the Carousel.ss file to your theme directory, maintaining the folder structure:
```
themes/your-theme/templates/Dynamic/Carousel/Includes/Carousel.ss
```
Modify the Template
Edit the copied Carousel.ss to fit your design requirements. You can:
- Change the HTML structure
- Update CSS classes
- Add or remove elements as needed
Include Necessary Assets
Ensure that any required JavaScript or CSS for your custom carousel implementation is included in your project.
If you are using a different frontend framework, include its assets accordingly.

For more information on custom templates, refer to the Silverstripe CMS Documentation.

Other Modules Using Silverstripe Carousel

The Silverstripe Carousel module is used in other projects to extend functionality, such as:

Silverstripe Elemental Carousel - Integrates carousel functionality with Silverstripe Elemental Blocks.

Upgrading to 3.1

CarouselPageExtension::$cascade_deletes is now empty. Slides can be shared between carousels, so archiving or deleting a carousel no longer deletes its slides; a slide no carousel uses stays in the database, like a File. To restore the old behaviour, add it back on the class that carries the extension:

Dynamic\Elements\Carousel\Elements\ElementCarousel:
  cascade_deletes:
    - Slides

Upgrading from version 2

Silverstripe Carousel 3.0 is compatible with SilverStripe 6. Key changes:

Updated to SilverStripe CMS 6
Requires PHP 8.3 or higher
Updated LinkField from ^4 to ^5
Updated FocusPoint from ^5 to ^6
Updated EmbedField: migrated from nathancox/embedfield to fromholdio/silverstripe-embedfield (SS6 compatible fork)
Updated GridField Extensions from ^4 to ^5
Updated Display Logic from ^3 to ^4

See the SilverStripe 6 Upgrade Guide for more details.

Maintainers

Dynamic (dev@dynamicagency.com)

Bugtracker

Bugs are tracked in the issues section of this repository. Before submitting an issue please read over existing issues to ensure yours is unique.

If the issue does look like a new bug:

Create a new issue
Describe the steps required to reproduce your issue, and the expected outcome. Unit tests, screenshots and screencasts can help here.
Describe your environment as detailed as possible: SilverStripe version, Browser, PHP version, Operating System, any installed SilverStripe modules.

Please report security issues to the module maintainers directly. Please don't file security issues in the bugtracker.

Development and Contribution

If you would like to make contributions to the module please ensure you raise a pull request and discuss with the module maintainers.

License

See License

dynamic / silverstripe-carousel

Package info

Security

Fund package maintenance!

Statistics