From 0444d2cfe53390d6eaf86e8a6f6976309bb0ad25 Mon Sep 17 00:00:00 2001 From: "Patrick H. Lauke" Date: Tue, 29 Nov 2022 07:20:35 +0000 Subject: [PATCH] Docs: rewrite/reorganise carousel docs page (#37354) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Instantiate/initialize all non-autoplaying carousels in docs pages * Rewrite/reorganise carousel docs page * start with static/non-autoplaying examples * explicitly mention that carousels currently need to be manually initialized * split out and explain autoplaying and the weird "autoplay after first interaction" behaviour, as well as the pause on hover/focus * Add callout about autoplaying and accessibility * Don't have the dark variant example autoplay * Add "autoplaying" to cspell custom dictionary * Tweal wording, move Page Visibility API to autoplay section * Tweak explanation for methods, add line break in js code for consistency with last code block on the page * Tweak method descriptions * Tweak headings (plural "carousels") * Move some paragraphs out of intro and into basic example, reword the nested and accessibility paragraph * Tweak warning about `.active` slide * Tweak callout wording * Further prose tweaks move the sentence about not double-initialising autoplaying carousels to the callout right at the top instead of talking about `data-bs...` attributes, talk about the "option" instead, as authors may be setting these not via data attributes, but at instatiation time with options in the constructor remove the incorrect statement about pausing when keyboard focus is in the carousel * Instantiate/initialize all non-autoplaying carousels in docs pages * Rewrite/reorganise carousel docs page * start with static/non-autoplaying examples * explicitly mention that carousels currently need to be manually initialized * split out and explain autoplaying and the weird "autoplay after first interaction" behaviour, as well as the pause on hover/focus * Add callout about autoplaying and accessibility * Don't have the dark variant example autoplay * Add "autoplaying" to cspell custom dictionary * Tweal wording, move Page Visibility API to autoplay section * Tweak explanation for methods, add line break in js code for consistency with last code block on the page * Tweak method descriptions * Tweak headings (plural "carousels") * Move some paragraphs out of intro and into basic example, reword the nested and accessibility paragraph * Tweak warning about `.active` slide * Tweak callout wording * Further prose tweaks move the sentence about not double-initialising autoplaying carousels to the callout right at the top instead of talking about `data-bs...` attributes, talk about the "option" instead, as authors may be setting these not via data attributes, but at instatiation time with options in the constructor remove the incorrect statement about pausing when keyboard focus is in the carousel * Fix relative link * Update site/assets/js/snippets.js Co-authored-by: GeoSot * Fix snippet.js * Tweak content organisation just a bit Co-authored-by: GeoSot Co-authored-by: Julien Déramond Co-authored-by: Julien Déramond Co-authored-by: Mark Otto --- .cspell.json | 1 + site/assets/js/snippets.js | 9 + site/content/docs/5.2/components/carousel.md | 167 +++++++++++++------ 3 files changed, 123 insertions(+), 54 deletions(-) diff --git a/.cspell.json b/.cspell.json index d528823b1d..752acd5218 100644 --- a/.cspell.json +++ b/.cspell.json @@ -8,6 +8,7 @@ "autohiding", "autoplay", "autoplays", + "autoplaying", "blazingly", "Blockquotes", "Bootstrappers", diff --git a/site/assets/js/snippets.js b/site/assets/js/snippets.js index 53f8a786ec..43b8a095cf 100644 --- a/site/assets/js/snippets.js +++ b/site/assets/js/snippets.js @@ -96,6 +96,15 @@ }) } + // -------- + // Carousels + // -------- + // Instantiate all non-autoplaying carousels in a docs or StackBlitz page + document.querySelectorAll('.carousel:not([data-bs-ride="carousel"])') + .forEach(carousel => { + bootstrap.Carousel.getOrCreateInstance(carousel) + }) + // ------------------------------- // Checks & Radios // ------------------------------- diff --git a/site/content/docs/5.2/components/carousel.md b/site/content/docs/5.2/components/carousel.md index 95f4bf0301..dca8e9a792 100644 --- a/site/content/docs/5.2/components/carousel.md +++ b/site/content/docs/5.2/components/carousel.md @@ -8,28 +8,24 @@ toc: true ## How it works -The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators. +- The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators. -In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibility/) is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.). +- For performance reasons, **carousels must be manually initialized** using the [carousel constructor method](#methods). Without initialization, some of the event listeners (specifically, the events needed touch/swipe support) will not be registered until a user has explicitly activated a control or indicator. + + The only exception are [autoplaying carousels](#autoplaying-carousels) with the `data-bs-ride="carousel"` attribute as these are initialized automatically on page load. If you're using autoplaying carousels with the data attribute, **don't explicitly initialize the same carousels with the constructor method.** + +- Nested carousels are not supported. You should also be aware that carousels in general can often cause usability and accessibility challenges. {{< callout info >}} {{< partial "callouts/info-prefersreducedmotion.md" >}} {{< /callout >}} -Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards. +## Basic examples -## Example - -Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they're not explicitly required. Add and customize as you see fit. - -**The `.active` class needs to be added to one of the slides** otherwise the carousel will not be visible. Also be sure to set a unique `id` on the `.carousel` for optional controls, especially if you're using multiple carousels on a single page. Control and indicator elements must have a `data-bs-target` attribute (or `href` for links) that matches the `id` of the `.carousel` element. - -### Slides only - -Here's a carousel with slides only. Note the presence of the `.d-block` and `.w-100` on carousel images to prevent browser default image alignment. +Here is a basic example of a carousel with three slides. Note the previous/next controls. We recommend using ` - {{< /example >}} -### With indicators +Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they're not explicitly required. Add and customize as you see fit. -You can also add the indicators to the carousel, alongside the controls, too. +**You must add the `.active` class to one of the slides**, otherwise the carousel will not be visible. Also be sure to set a unique `id` on the `.carousel` for optional controls, especially if you're using multiple carousels on a single page. Control and indicator elements must have a `data-bs-target` attribute (or `href` for links) that matches the `id` of the `.carousel` element. + +### Indicators + +You can add indicators to the carousel, alongside the previous/next controls. The indicators let users jump directly to a particular slide. {{< example >}} -