Foxy Documentation

Introduction

Foxy and friends are a lightweight group of slideshows. They use vanilla JS and CSS, and are otherwise without dependencies. They use grid and flexbox for layout, and won't interfere with the rest of your template.

Foxy is designed to display individual elements. All elements are layered on top of one another, and Foxy will expand to fit the largest element.

Fennecs is an extension to Foxy that displays multiple elements in a single slide. It is responsive, and will rearrange the elements to neatly fit inside a slide.

Fox Parade is designed to display a row or column of elements of arbitrary width/height. Unlike the other slideshows, it uses flex instead of grid for layout.

Installation

Yarn / NPM

1. Add Foxy to your dependencies in package.json:

   
   {
   	"dependencies":
   	{
   		"foxy": "git+https://Rizanola@bitbucket.org/Rizanola/foxy.git"
   	}
   }
   

2. Run the appropriate install command:

   • Yarn:
     yarn install

   • NPM:
     npm install

Manual Installation

1. Download the latest version of Foxy from Bitbucket

2. Unzip the archive and place the folder in amongst your website's files

Getting started

1. Include the Foxy stylesheet:

   <link rel="stylesheet" type="text/css" href="foxy/src/foxy.css" />

2. Include the Foxy JavaScript:

   • Global Foxy objects:
     <script type="text/javascript" src="foxy/dist/foxy.min.js"></script>

   • As an ES6 module:
     import { Foxy, Fennecs, FoxParade, FoxyDirection } from "foxy/dist/foxy.es6.js";

3. Add the foxy / fennecs / fox-parade classes to the element you wish to add the slideshow to. This sets up the base styles, and prevents a FOUC from occurring.

   
   <div class="foxy">
   	<img src="image-1.png" />
   	<img src="image-2.png" />
   	<img src="image-3.png" />
   </div>
   <div class="fennecs">
   	<img src="image-1.png" />
   	<img src="image-2.png" />
   	<img src="image-3.png" />
   </div>
   <div class="fox-parade">
   	<img src="image-1.png" />
   	<img src="image-2.png" />
   	<img src="image-3.png" />
   </div>
   

4. Trigger the Foxy.init() / Fennecs.init() / FoxParade.init() method on your element in one of the following ways:

   • With a selector:
     Foxy.init(".js-foxy", options);
Fennecs.init(".js-fennecs", options);
FoxParade.init(".js-fox-parade", options);

   • With a single element:
     Foxy.init(myElement, options);
Fennecs.init(myElement, options);
FoxParade.init(myElement, options);

   • With an entire array of elements:
     Foxy.init(myElements, options);
Fennecs.init(myElements, options);
FoxParade.init(myElements, options);

   The options parameter is an object containing various settings to pass to Foxy. A description of the options can be found in the options section below.

   Make sure that the element is available (added to the DOM), before you try to initialise Foxy on it.

Options

The following options can be passed to the Foxy init() and set() methods

All Slideshows

arrows

A boolean indicating whether to enable arrows or not. Defaults to true.

arrowsParent

Either a DOM selector or an HTMLElement for an external element to place the arrows into. This will only be used if arrows are set to true.

timer

The amount of time, in milliseconds, before automatically switching to the next slide, or null to disable. Default is 3000.

Foxy and Fennecs

animation

The name of the animation to use. Foxy will add a class of foxy-ANIMATION_NAME to the base foxy element. Native animation functions are fade, fade-in, instant, slide and vertical-slide, but you can easily create your own. Default is slide.

bullets

A boolean indicating whether to enable bullets or not. Defaults to true.

dragging

A boolean indicating whether the user can drag the slides in order to switch between them.

onMove

A closure to call every time the slide animation is triggered. It takes three parameters, the index for the new slide, the index for the old slide and the direction that the slideshow is moving. Default is undefined.

Fennecs Only

rows

The number of rows that should be displayed per slide. Note: In order to better support responsive layouts, this can be set via CSS by setting the --rows custom property.

Methods

Foxy supports the following methods:

Static methods

init(elements, options)

Sets up Foxy on an element or group of elements. The elements parameter is either a query string, a single HTMLElement or an array of HTMLElements the options parameter is described in the options section above.

get(element)

Given an HTMLElement, it will return the Foxy instance associated with it. Will return undefined if Foxy has not been initialised on that element.

Instance methods

set(option, value)

Changes a value in the slideshow options. This returns the current slideshow, so you can chain it, e.g. foxy.set("timer", 4000).set("bullets", false);

getElements()

Gets all the child elements that weren't added by Foxy

getElementsInSlide(slide)

Gets all the elements that belong to a specific slide

getSlideCount()

Gets the number of slides currently in the slideshow

getCurrent()

Gets the current slide, returns an array of HTMLElements

getIndex(element)

Gets the index for a specific element. Takes an HTMLElement, and returns the slide index for that element

getCurrentIndex()

Gets the index for the current slide

moveTo(slide, direction)

Triggers the slideshow to move to a specific slide. Takes either an HTMLElement or an slide index for the first parameter. The second parameter is optionally one of the FoxyDirection constants. If left on FoxyDirection.default, it will animate relative to the order of the slides.

next()

Moves to the next slide in order, or the first slide if we're currently on the last one. Always uses the FoxyDirection.forward animation.

previous()

Moves to the previous slide in order, or the last slide if we're currently on the first one. Always uses the FoxyDirection.backward animation

deinit()

Removes all foxy classes, elements, variables, timers and listeners that were originally added during initialisation.

Styling

Foxy tries to be lightweight and unobtrusive, however custom styling has the potential to conflict with the standard Foxy styles:

• Foxy is built on top of CSS grid. This means that slide dimensions are responsively handled by the browser. Please refrain from changing the display property. You can use the inline-grid class to switch to an inline slideshow.

• In order to setup columns for Fennecs, just use the normal grid-template-columns property that you'd use for a regular grid. e.g. grid-template-columns: repeat(auto-fill, minmax(200px, 1fr))

• If you want the slideshow to flow vertically, especially with Fennecs or Fox Parade, you should add the foxy-vertical class to your slideshow element.

• Foxy uses transform for slide animations, and opacity for fade animations. It also uses the various animation properties to handle animations. If your elements need these styles as well, you might consider wrapping them in <div> elements, which Foxy can style independently.

• By default, Foxy centres all slides vertically and horizontally. This is convenient, but a pain to reset sometimes, so you can add a class of foxy-custom-alignment to the slideshow element in order for Foxy not to set the slide alignment.

• If you're creating your own animation, the classes Foxy uses on its current and previous slides are foxy-current and foxy-departed. Foxy sets foxy-direction-forward and foxy-direction-backward on the slideshow element in order to animate directions correctly.

• Foxy uses CSS variables to control the animations. If you're making custom animations, you'll want to keep track of these variables:

  • The --animation-speed variable defines how quickly an animation should run. This variable is set by the CSS, so can be overridden.

  • The --full-width and --full-height variables define the width and height of the slideshow element. You can use this to calculate relative positions for sliding animations. These variables are calculated by JavaScript, so they shouldn't be used for initial styling.

    Fox Parade doesn't use --full-width or --full-height, but it uses --inner-width and --inner-height for calculating the internal scroll dimension.

  • It can sometimes look a little strange to have slides immediately abutting each other during a sliding animation, so if you want a visible gap between slides during the "slide" or "vertical-slide" animations, you can use the --slide-gap variable to define extra spacing.

  • The --animation-delay variable uses the --animation-speed variable and the drag distance to work out how far the animation should be negatively delayed while dragging. Foxy automatically applies this to all top level slides, but you may need to tinker with things a little if you have multiple levels of animation.

    In addition; while the foxy-dragging class is applied to the slideshow element, slideshow specific animations should be paused.