Image Carousel 2: A Better One

CROQUEMBOUCHE'S TOPIA

DO NOT USE THIS COMPONENT!

It is a work in progress. At some point it will either be moved to the SCP Wiki, or deleted. Any pages that use it will break.

rewrite in something not-terrible DONEish
support loading images by full URL DONE
do not autoplay if prefers-reduced-motion DONE in js but not css
to be able to show text over the image in a contrast-friendly way
to have information about its current state very clearly broadcasted and not just have a bunch of shitty dots at the bottom
to be able to display a couple of different kinds of text - artist, context, links (though maybe this should be under/next to the image instead of on it)
to be able to display multiple links
not going big left-right swoosh all the fucking time
extract all english strings
progress bar for the timer (use rAF?)
dont just post it, warn rounder first

What this is

This component is an image carousel. It's an image block that, instead of showing just one image, cycles through many.

>>> DEMO <<<

Should you use this component?

Short answer: probably not. Use regular image blocks instead.

Longer answer:

If possible, I would recommend not using this component. Use a series of standard image blocks instead.

A carousel might be a good idea if all of the following describe your situation:

You have several images you want to display - between three and five.
You have a very limited amount of space.
Your images all have roughly the same width to height ratio.
It's fine if readers ignore your images entirely.
It's fine if readers are irritated or distracted by the constant motion.
You don't expect readers to want to see all of the images (as they'll have to wait to do so).
None of the images are particularly important (because none will be on-screen for long).

Additionally, do not use this component with images that would replace textual information (for example, do not use this component to display announcements that would otherwise be plain text). That is a black hole for users who use screen readers or translators to navigate the site.

Usage

Wherever you want your Image Carousel, slap in this code instead of your standard image block.

Configuring

The image carousel has a lot of different parameters, so I've split them up into different sections.

Parameters for each image

The following parameters are all lists. There should be one value for each image in the carousel, separated by commas.

For example, the images parameter is a list of sources, one for each image; and the links parameter is a list of URLs, one for each image.

It's important that each list has the same amount of items in it, or the carousel might not work as expected.

images	A list of image sources, separated by commas. These images will appear in the carousel in the order that you list them. The sources can be either full URLs or just the filenames.
links (Optional)	A list of URLs for each image to link to, separated by commas. Clicking on the image will take the user to this URL. If provided, there must be the same number of URLs as there are images.

Default values for image locations

The images parameter accepts both full URLs or just filenames. In the case of just filenames, the carousel needs to know where to find those files. If any of your image sources are just filenames, you'll need these two parameters to tell the carousel how to find them.

wiki	The name of the wiki that the images are uploaded to. For example, `scp-wiki` (NOT "scpwiki") or `scp-sandbox-3`.
page	The slug of the page that the images are uploaded to. Include the category, if any. (The 'slug' is the name of the page as seen in the URL - for example, for scp-botnik-j the slug is `scp-botnik-j`.)

This allows the carousel to construct its own URLs for those images.

Timing control

interval
(Optional)

The number of seconds to wait between 'rotations' of the carousel. After this many seconds, the currently-displayed image will change to the next one in the list.
If the number is 0, the carousel will never automatically rotate, but can still be manually rotated with the arrow buttons.
I recommend either 0 or at least 5.
Default value: 0

Size and position

width (Optional)	The width of the carousel. Default value: `300px`
height (Optional)	The height of the carousel. If not provided, the optimum height will be calculated based on the provided width and the average width/height of each image. Default: automatic
position (Optional)	The horizontal position of the carousel on the page. `left`, `right` or `center`. Default value: `right`

Caption

The image carousel has a single caption beneath it that looks like the caption of the standard image block. This caption cannot change based on the image that is currently displaying; it should describe the images that are in the carousel as a collective.

caption (Optional)	The caption that goes underneath the carousel. Default value: `{$caption}`
no-caption (Optional)	Either `true` or `false`. If you don't want there to be a caption below the carousel, set this to `true`. Default value: `false`

Appearance

background (Optional)	The background behind the images. Default value: `transparent`
style (Optional)	Custom CSS styling to add to the inside of the carousel. You can't style the inside of the carousel with a regular CSS module - this is the only way. If you have lots of image carousels and you want them all to be styled the same way, instead of copy-pasting the CSS into each one, I recommend putting that CSS into a code block somewhere and then `@import`ing it into each carousel.

I want the carousel to spread across the whole page!
Set width to 100% and position to center.

I set width and height to the size of my biggest image but it's way too big!
Pick a smaller number, or make your images smaller. Or, get rid of the height parameter and let the automatic optimiser handle it.

{$caption}

Codebase

JS to operate the carousel

+ show block

– hide block

// Is the carousel currently paused?
let isPaused = true
 
// Does the user have their mouse over the carousel?
let isHovered = false
 
// The list of all horses on the carousel
let horses = []
 
// The horse that is currently displaying
let currentHorse = 0
 
// Keeps track of image sizes for height calculations
const images = {  ratios: [],}
 
/**
 * A 'Horse' (i.e. the thing that goes around a carousel) represents an
 * individual image on the carousel.
 */
class Horse {
  constructor(imageSrc, link) {
    this.imageSrc = imageSrc
    this.link = link
    this.createElement()
  }
 
  /**
   * Constructs the <figure> element representing this horse.
   */
  createElement() {
    this.element = document.createElement("figure")
 
    const imageElement = document.createElement("img")
    imageElement.src = this.imageSrc
 
    if (this.link) {
      const linkElement = document.createElement("a")
      linkElement.href = this.link
      linkElement.target = "_blank"
      linkElement.appendChild(imageElement)
      this.element.appendChild(linkElement)
    } else {
      this.element.appendChild(imageElement)
    }
 
    return this.element
  }
 
  /**
   * Sends this horse to the past (left of the viewport).
   */
  toPast() {
    this.element.classList.add("past")
this.element.classList.remove("future")
  }
 
  /**
   * Brings this horse to the present (aligned with the viewport).
   */
  toPresent() {
    this.element.classList.remove("past")
this.element.classList.remove("future")
  }
 
  /**
   * Sends this horse to the future (right of the viewport).
   */
  toFuture() {
    this.element.classList.add("future")
this.element.classList.remove("past")
  }
}
 
/**
 * Rotates the carousel, sending the currently-displayed image to the left
 * and bringing in the next one from the right.
 *
 * If the carousel is not paused, repeats the process after a delay.
 *
 * @param {number} interval - The delay before rotating again.
 */
function rotate(interval) {
  setTimeout(() => {
    if (!isPaused && !isHovered) {
      nextHorse()
    }
    if (!isPaused) {
      rotate(interval)
    }
  }, interval * 1000)
}
 
/**
 * Increments which image is currently displaying.
 */
function nextHorse() {
  if (currentHorse < horses.length - 1) {
    currentHorse++
  } else {
    currentHorse = 0
  }
  horses.forEach(moveHorse)
}
 
/**
 * Decrements which image is currently displaying.
 */
function previousHorse() {
  if (currentHorse > 0) {
    currentHorse--
  } else {
    currentHorse = horses.length - 1
  }
  horses.forEach(moveHorse)
}
 
/**
 * Sets the current image to the given index.
 *
 * @param {number} index
 */
function setHorse(index) {
  currentHorse = index
  horses.forEach(moveHorse)
}
 
/**
 * Moves a given horse to its correct position.
 *
 * @param {Horse} horse - The Horse object representing a given image.
 * @param {number} horseIndex - The index of this horse in the list.
 */
function moveHorse(horse, horseIndex) {
  if (currentHorse > horseIndex) horse.toPast()
  if (currentHorse === horseIndex) horse.toPresent()
  if (currentHorse < horseIndex) horse.toFuture()
 
  const selector = document.getElementById("selectors").children[horseIndex]
  if (currentHorse === horseIndex) selector.classList.add("present")
 else selector.classList.remove("present")
}
 
/**
 * Appends CSS to the document as a new stylesheet.
 *
 * @param {string} style - Content of CSS stylesheet to append.
 */
function addCustomStyling(style) {
  if (!style) return
  const styleElement = document.createElement("style")
  styleElement.appendChild(document.createTextNode(style))
  document.head.appendChild(styleElement)
}
 
/**
 * Resumes carousel playback.
 *
 * @param {number} interval - The delay between carousel rotations.
 */
function play(interval) {
  if (interval) {
    isPaused = false
    rotate(interval)
  document.querySelector("button#play").classList.remove("paused")
  document.querySelector("button#play").classList.add("playing")
  }
}
 
/**
 * Pauses carousel playback.
 */
function pause() {
  isPaused = true
  document.querySelector("button#play").classList.add("paused")
  document.querySelector("button#play").classList.remove("playing")
}
 
/**
 * Creates a button for each image in the carousel that shows that image
 * when clicked.
 */
function createSelectorButtons() {
  horses.forEach((horse, horseIndex) => {
    const button = document.createElement("button")
    button.addEventListener("click", () => {
      setHorse(horseIndex)
      pause()
    })
    button.textContent = (horseIndex + 1).toString()
    document.querySelector("#selectors").appendChild(button)
  })
}
 
/**
 * Calculates the ideal height for the iframe based on the images that were
 * provided to it.
 *
 * This requires the dimensions of each image to be known, i.e. they have to
 * be downloaded and analysed. This could take a while. Luckily the images
 * need to be downloaded anyway, so it's not wasted time. The height will be a
 * bit janky in the interim but that's no different to normal images anyway.
 *
 * @param {string[]} imageSrcs - List of the URLs for each image.
 */
async function calculateIdealHeight(imageSrcs) {
  imageSrcs.forEach(src => {
    const image = new Image()
    image.addEventListener("load", function () {
      images.ratios.push(this.naturalHeight / this.naturalWidth)
      const averageRatio = images.ratios.reduce((a, b) => a + b, 0) / images.ratios.length
      document.querySelector(
        "main"
      ).style.height = `calc(${averageRatio * 100}vw - ${32 * averageRatio}px)`
     // TODO Get 32 automatically from CSS? It's the horizontal body padding
    })
    image.src = src
  })
}
 
// Tasks to run once everything has loaded
window.addEventListener("load", () => {
  addCustomStyling(carouselParameters.customStyling)
 
  // Get the list of image source URLs
  const imageSrcs = carouselParameters.imageSrcs
    .replace(/\s*/g, "")
    .split(",")
    .map(src => {
      if (!/^https?:/.test(src)) {
        const { wiki, page } = carouselParameters.defaultSource
        if (wiki === null || page === null) {
          console.error(
            "Image carousel: parameters 'wiki' and 'page' are missing;",
            `cannot resolve image ${JSON.stringify(src)}`
          )
          return null
        }
        // Make a full URL assuming the image is uploaded to the specified
        // page
        return `https://${wiki}.wdfiles.com/local--files/${page}/${src}`
      }
      return src
    })
 
  // The carousel has a known width, but the height should be calculated
  // automatically if not provided
  calculateIdealHeight(imageSrcs)
 
  // Get the list of image link URLs, if any
  const links = carouselParameters.imageLinks.replace(/\s*/g, "").split(",")
 
  // Assemble image sources and links into a list of 'horses' i.e the
  // things going round on the carousel
  horses = imageSrcs.map((src, index) => new Horse(src, links[index] || null))
 
  // Add each horse to the HTML
  horses.forEach((horse, horseIndex) => {
if (horseIndex > 0) horse.toFuture()
      document.querySelector("main").appendChild(horse.element)
    })
 
  // Check for prefers-reduced-motion
  const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)")
 
  // Implement index selector buttons
  createSelectorButtons()
 
  // Start the carousel
  const interval = carouselParameters.changeImageInterval
  if (interval === 0 || !mediaQuery || mediaQuery.matches) {
    pause()
  } else {
    play(interval)
  }
 
  // Set the background
  document.querySelector("main").style.background =
    carouselParameters.iframeBackground
 
  // Track hover state
  document.documentElement.addEventListener(
    "mouseover",
    () => (isHovered = true)
  )
  document.documentElement.addEventListener(
    "mouseout",
    () => (isHovered = false)
  )
 
  // Implement next image button
  document.querySelector("button#next").addEventListener("click", () => {
    nextHorse()
    pause()
  })
 
  // Implement previous image button
  document.querySelector("button#previous").addEventListener("click", () => {
    previousHorse()
    pause()
  })
 
  // Implement play button
  document.querySelector("button#play").addEventListener("click", () => {
    if (isPaused)   { 
 play(interval)
// User will be hovering, but will expect carousel to resume immediately
isHovered = false
}
else{ pause()}
  })
 
  // React to prefers-reduced-motion changes
  mediaQuery.addEventListener("change", () => {
    if (mediaQuery.matches) pause()
    else play(interval)
  })
})

CSS styling for the caption box

This CSS affects the exterior of the carousel (e.g. the caption box) and can be overridden with a normal CSS module.

+ show block

CSS styling for the interior

This CSS affects the interior of the carousel (e.g. the images, the transitions, the controls) and can be overridden by passing CSS to the style parameter of this component.

+ show block

– hide block

html {
  width: calc(100% - 32px);
  height: calc(100% - 4px);
  margin: 0;
  padding: 0;
}
 
body {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 2px 16px !important; /* override [[html]] styling */
  background: transparent;
}
 
main {
  position: relative;
  width: 100%;
  height: 100%;
  overflow-x: hidden;
  border: 1px solid #666;
  box-shadow: 0 1px 6px rgba(0, 0, 0, .25);
  box-sizing: border-box;
}
 
figure {
  position: absolute;
  height: 100%;
  width: 100%;
  top: 0;
  left: 0;
  transform: translate(0, 0);
  transition: transform 0.3s ease-in-out;
  margin: 0;
}
 
figure img {
  object-fit: contain;
  width: 100%;
  height: 100%;
}
 
figure.past {
  transform: translate(-100%, 0);
}
 
figure.future {
  transform: translate(100%, 0);
}
 
#next, #previous {
  height: 30px;
  width: 30px;
  border: 1px solid #666;
  border-radius: 50%;
  position: absolute;
  top: 50%;
  background: #eee;
  box-shadow: 0 1px 6px rgba(0, 0, 0, .25);
  cursor: pointer;
}
 
#next .icon, #previous .icon {
  height: 30px;
  width: 30px;
  position: absolute;
  top: 0;
  left: 0;
  background-position: 50% 50%;
  background-size: 80% 80%;
  background-repeat: no-repeat;
  opacity: 0.6;
  transition: opacity 0.1s ease-in-out;
}
 
#next[disabled], #previous[disabled] {
  cursor: default;
}
 
#next[disabled] .icon, #previous[disabled] .icon {
  opacity: 0;
}
 
#previous {
  left: 0;
  transform: translate(2px, -50%);
}
 
#previous .icon {
  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACQAAAAkCAQAAABLCVATAAAAdElEQVR4AezQJwKAMBQD0DCOjAfD9j1BXVUdR0OxkWzCJvHvD/x5aVxEDMZBWVfAIDB1JQwOY96IUSzGYjCaxdgMJuMwOQJ4c51jlnc0HgsCUs5pPbX82csozaQsFqVuSpksSjIpg0OJBdACqlorw7AEowAAblWUrl8sD5AAAAAASUVORK5CYII=');
}
 
#next {
  right: 0;
  transform: translate(-2px, -50%);
}
 
#next .icon {
  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACQAAAAkCAQAAABLCVATAAAAcUlEQVR4Ae3QpwJAUACF4WM+sU6xV9M0TdI8mmR389j+07878PfSHOjYnYAETTdtP5Sh4VAik8pZlMSkChYlM6mSRalLKWN2FqolVLNqGgsyOE/zOZ+9i5FZTMFgJBaT34gRWUzGYAABKYMZizvm75W1TreU8DMmtioAAAAASUVORK5CYII=');
}
 
#controls {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 0.25rem;
  position: relative;
}
 
#selectors {
  display: flex;
  flex-wrap: wrap;
  justify-content: flex-end;
  align-content: center;
}
 
#selectors button, #play {
  margin: 2.5px;
  height: 1.5rem;
  min-width: 1.5rem;
  transition: all 0.2s ease-in-out;
  background-color: #eee;
  border: 1px solid #666;
  border-radius: 2px;
  box-shadow: 0 1px 6px rgba(0, 0, 0, .25);
}
 
#selectors button.present {
  /* TODO This is terrible */
  font-weight: bold;
}
 
#selectors:hover button {
  height: 6px;
  width: 6px;
  margin: 2px;
  cursor: pointer;
}
 
#selectors:hover button.present {
  height: 12px;
  width: 12px;
  margin: -1px;
}
 
#play {
  background-size: contain;
}
 
#play.paused {
  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACQAAAAkCAQAAABLCVATAAAAgElEQVR4Ae2UQRWAIBBEJwIRjGAEI9hEG0ATaaINtIE0kAbqnrh4/M/Tzr//B7A78nzF0wvKraiAiF5ODYzIWBQIkXFpZETGqo4R2bkmRmTs6hmRERUIURsKQNSGAhBlQlSYqyXisQ/i+6tmYiA3YkUqs7SZqJHCFFtS+Lf8PZ4HilOsPBFiYmoAAAAASUVORK5CYII=');
}
 
#play.playing {
  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACQAAAAkCAYAAADhAJiYAAAAOUlEQVR4Ae3WoQ0AMAwDwY7ezdsFzKyg3EthBgdzJCl309X7opev3wMBAQEtAQEBAQEBAU09+ZL0AdrO+xGDE6h0AAAAAElFTkSuQmCC');
}
 
#progress {
  position: absolute;
  z-index: -1;
  width: 95%;
  height: 100%;
  top: 0;
  left: 2.5%;
  --progress: 33%;
  background: linear-gradient(to right, #ddd 0%, #ddd var(--progress), #eee var(--progress));
}
 
.invisible {
  display: none;
}

component

page revision: 96, last edited: 03 Jun 2021 16:20

Edit Rate (0) Tags Discuss History Files Print Site tools + Options

The Topiary

yes the bees >:)

What this is

Should you use this component?

Usage

Configuring

Parameters for each image

Default values for image locations

Timing control

Size and position

Caption

Appearance

Codebase

JS to operate the carousel

CSS styling for the caption box

CSS styling for the interior