diff --git a/README.md b/README.md index af48fba..4a207d5 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,50 @@ # Silverstripe Carousel -A simple carousel for Silverstripe websites. The default template uses Bootstrap classes to power the carousel. If you are not using Bootstrap, you can use a custom template and include your own javascript. - -![CI](https://github.com/dynamic/silverstripe-carousel/workflows/CI/badge.svg) -[![codecov](https://codecov.io/gh/dynamic/silverstripe-carousel/branch/master/graph/badge.svg)](https://codecov.io/gh/dynamic/silverstripe-carousel) - -[![Latest Stable Version](https://poser.pugx.org/dynamic/silverstripe-carousel/v/stable)](https://packagist.org/packages/dynamic/silverstripe-carousel) -[![Total Downloads](https://poser.pugx.org/dynamic/silverstripe-carousel/downloads)](https://packagist.org/packages/dynamic/silverstripe-carousel) -[![Latest Unstable Version](https://poser.pugx.org/dynamic/silverstripe-carousel/v/unstable)](https://packagist.org/packages/dynamic/silverstripe-carousel) -[![License](https://poser.pugx.org/dynamic/silverstripe-carousel/license)](https://packagist.org/packages/dynamic/silverstripe-carousel) +A versatile carousel module for Silverstripe websites, featuring support for images and videos. The default template utilizes Bootstrap classes for seamless integration. + +[![CI](https://github.com/dynamic/silverstripe-carousel/workflows/CI/badge.svg)](https://github.com/dynamic/silverstripe-carousel/actions) +[![Latest Stable Version](https://poser.pugx.org/dynamic/silverstripe-carousel/v/stable)](https://packagist.org/packages/dynamic/silverstripe-carousel) +[![Total Downloads](https://poser.pugx.org/dynamic/silverstripe-carousel/downloads)](https://packagist.org/packages/dynamic/silverstripe-carousel) +[![License](https://poser.pugx.org/dynamic/silverstripe-carousel/license)](https://packagist.org/packages/dynamic/silverstripe-carousel) + +## Table of Contents + +- [Requirements](#requirements) +- [Installation](#installation) +- [Configuration](#configuration) +- [Usage](#usage) + - [Adding a Carousel to a Page](#adding-a-carousel-to-a-page) + - [Working with Images and Videos](#working-with-images-and-videos) +- [Customization](#customization) + - [Creating Custom Templates](#creating-custom-templates) +- [Other Modules Using Silverstripe Carousel](#other-modules-using-silverstripe-carousel) +- [Maintainers](#maintainers) +- [Bugtracker](#bugtracker) +- [Development and Contribution](#development-and-contribution) +- [License](#license) ## Requirements -- Silverstripe CMS ^5 +- Silverstripe CMS ^5.0 +- Bootstrap 5 (for default templates) ## Installation -`composer require dynamic/silverstripe-carousel` +Install via Composer: -## License +```sh +composer require dynamic/silverstripe-carousel +``` -See [License](LICENSE.md) +Run a dev/build to regenerate the manifest: -## Usage +```sh +./vendor/bin/sake dev/build +``` -To add a carousel to a page, apply `CarouselPageExtension` to a page type: +## Configuration + +Apply the `CarouselPageExtension` to your desired page types in your YAML configuration: ```yaml Page: @@ -32,35 +52,103 @@ Page: - Dynamic\Carousel\Extension\CarouselPageExtension ``` -In your template, include the `Carousel` template: +After applying the extension, run a dev/build to update the database schema. + +## Usage + +### Adding a Carousel to a Page -```html -<% include Dynamic/Carousel/Carousel %> +To display the carousel, include the following template in your page layout: + +```ss +<% include Dynamic/Carousel/Includes/Carousel %> ``` -### Template Notes +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've 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. -The default template assumes you are using [Bootstrap 5](https://getbootstrap.com/), and requires no additional javascript. If you are not using Bootstrap, you can use a custom template and include your own javascript. +Repeat these steps to add multiple images or videos as needed. -Note - if you are not including all of Bootstrap, you will need to manually include the carousel component. +## Customization +### Creating Custom Templates + +If you're not using Bootstrap or wish to customize the carousel's 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’s 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're using a different frontend framework, include its assets accordingly. + +For more information on custom templates, refer to the [Silverstripe CMS Documentation](https://docs.silverstripe.org/en/5/developer_guides/templates/). + +## Other Modules Using Silverstripe Carousel + +The Silverstripe Carousel module is used in other projects to extend functionality, such as: + +- [Silverstripe Elemental Carousel](https://github.com/dynamic/silverstripe-elemental-carousel) - Integrates carousel functionality with Silverstripe Elemental Blocks. ## Maintainers - * [Dynamic](http://www.dynamicagency.com) () + +- [Dynamic](http://www.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: +Bugs are tracked in the issues section of this repository. Before submitting an issue, please review existing issues to ensure yours is unique. + +If the issue appears to be new: + +- Create a new issue. +- Describe the steps required to reproduce your issue and the expected outcome. Unit tests, screenshots, and screencasts can help here. +- Provide details about your environment: + - Silverstripe version + - Browser and version + - PHP version + - Operating system + - Any installed Silverstripe modules - - 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. +**Security Issues:** +Please report security issues to the module maintainers directly. Avoid filing security issues in the bugtracker. -Please report security issues to the module maintainers directly. Please don't file security issues in the bugtracker. +## Development and Contribution + +We welcome contributions! Please ensure you raise a pull request and discuss with the module maintainers. + +## License -## 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. +This module is licensed under the BSD-3-Clause License. See the [LICENSE](LICENSE.md) file for details. \ No newline at end of file