README

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

Table of Contents

• Requirements
• Installation
• Configuration
• Usage
  • Adding a Carousel to a Page
  • Working with Images and Videos
• 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:

1. In the CMS, navigate to the page where you have enabled the carousel.
2. Click on the "Carousel" tab.
3. Use the "Add Slide" button to add either an Image or Video.
4. For Images:
   • Upload or select an image from the files.
   • Optionally, add a caption or link.
5. 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.

Customization

Creating Custom Templates

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

1. Locate the Default Template
   The default template is located at:

   templates/Dynamic/Carousel/Includes/Carousel.ss
   

2. 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
   

3. 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

4. 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 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