Miss any of our Open RFC calls?Watch the recordings here! »

thumbslider

0.0.4 • Public • Published

Thumbslider

What is this?

A responsive javascript carousel with thumbnails.

Features

  • Creates thumbnails from slide content
  • Carousel structure is responsive and scalable within container dimensions
  • Plain Javascript - no reliance on any framework (animation is pluggable)

Fantastic! How do I get it?

npm

npm install thumbslider --save

bower

bower install thumbslider --save

What's the Setup?

Add thumbslider resources to your html <head>.

<link href="../dist/thumbslider.min.css" rel="stylesheet" />
 
<script src=".../dist/thumbslider.min.js"></script>

Polyfills are available also (See Polyfilling section).

Next, you need to have a container element with some content

<div id="carousel_container" class="ts-theme-default">
  ...
</div>

Make sure the container is styled to have a width and height.

Finally, to create and render the carousel (with default options)

var carousel = thumbslider.create('carousel_container');
carousel.start(); // start rotation

Animation can be plugged into thumbslider.

For instance, if you have JQuery in your page, you can create the carousel like so:

var carousel = thumbslider.create('carousel_container', { animator: thumbslider.tweeners.jquery });

How Does It All Work?

To start, here's some example content:

<div id="carousel_container" class="ts-theme-default">
  <div>
    <h1>
      <span data-ts-thumb>Top Header</span>
    </h1>
    <p>Paragraph Content</p>
  </div>
  <div data-ts-name="sub-topic">
    <h2>Sub Header</h2>
  </div>
  More Content Here!
  <img src="http://www.server.com/path/to/some/image.png" />
</div>

thumbslider assumes that every top-level non-text child node of the container is a content item.

In the above example content, the content items would be the two top level <div> elements and the <img> element.

Each content item is given an identifier in the carousel. This name comes from its 'data-ts-name' attribute.

<div data-ts-name="sub-topic">
  ...
</div>

If no attribute is specified a random identifier is generated.

A thumbnail node for the content item is derived from the content itself. This node will be selected as

  1. the first descendant of the content item found having a 'data-ts-thumb' attribute, or
  2. the first non-text node in the content item, or
  3. the content item itself

So, in the above example

  • the first <div> content item uses the <span> as its thumbnail item
  • the second <div> will have it's <h2> element as its thumbnail
  • and the <img> content item will also double as the thumbnail itself

The content item is always cloned and copied to the selector as a thumb element. You can instead have the thumb element moved from its current location by specifying 'remove' as the value of 'data-ts-thumb'.

<div>
  <h1>
    <span data-ts-thumb="remove">Top Header</span>
  </h1>
  ...
</div>

Here's a quick ref for the content attributes.

  • data-ts-name (optional: for top-level container child)
    Gives the content item a name. A random name is generated if not specified.

  • data-ts-thumb (optional: for any descendant of a content item)
    Identifies element to be used as thumbnail for the content item. Specify 'remove' as value for attribute to prevent cloning. The first non-text node in the content item or the content item itself is used if not specified.

Configuration Options

var config = { ... }
thumbslider.create('my_carousel_id', config);
option type default description
activeClass* string 'active' CSS class name to add to the current content item
animator function (default non-animating function) Function for animation (See Animators section)
icons* Object (css triangles) Class names for the nav icons (See Icon Controls section)
pauseOnMouseover* boolean true Pause carousel rotation on mouseover?
responsive object { xs: 480, sm: 768, md: 1024, lg: 1200 } Responsive labels and thresholds (See Configuring Responsively section)
rotateDuration* number 0.8 Seconds of carousel rotation animation
rotateEasing* any null Library-specific easing value for carousel rotation
rotateInterval* number 3 Seconds between each rotation
rotateIntermission* number 3 Seconds to wait before restarting rotation after user interaction
selectorDisplay* string 'visible' Display as 'hidden', 'visible', 'transient', or 'overlay' (See Selector Display section)
selectorHideDelay* number 0 number of seconds before hiding a displayed 'transient' selector. Set to 0 to disable
selectorPosition* string 'bottom' Position selector at 'top', 'bottom', 'left', or 'right'
selectorSize* number 0.2 Size of selector (either height or width dependent upon selectorPosition) as percentage of container
showIconsOnHover* boolean true Show controls on carousel mouse hovers? (Controls always shown for false)
showSelector* boolean true Display 'transient' selector initially?
showThumbContent* boolean true Display content for thumbnails?
shuffle* boolean false Shuffle the carousel content items?
slideScaleType* object { img: 'content-max', def: 'none' } Slide scaling by tag or class name (See Content Scaling section)
slideTransition* function (default 'slide' function) Content slide transition animation (See Slide Transitions section)
startAt* string or number (first content item) Content item name or index to display when carousel loads
thumbScaleType* object { img: 'content-max', def: 'viewer' } Thumb scaling by tag or class name (See Content Scaling section)
thumbSize* number 1.0 ratio of secondary to primary dimension (at 1.0 carousel tries to maintain square-shaped thumbs)
toggleDuration* number 0.8 Seconds of 'transient' selector toggle
toggleEasing* any null Library-specific easing value for 'transient' selector toggle
viewerOrientation* string 'horizontal' Direction of viewer scroll ('vertical' or 'horizontal')

* = option can be configured responsively

Animators

JQuery

{ animator: thumbslider.tweeners.jquery }

GreenSock (requires TweenMax and ScrollToPlugin)

{ animator: thumbslider.tweeners.gsap }

No animation (the default)

{ animator: thumbslider.tweeners.none }

Custom

{ animator: function(element, time, params) { ... } }

Animator Function Parameters

param type description
element object DOM Element to be animated
time number Animation duration in seconds
params object Additional animation parameters
params.after function function to execute when/after animation completes
params.attrs object element attributes to be animated
params.before function function to execute when/before animation begins
params.during function function to execute for each frame of animation
params.ease any easing value for animation
params.styles object element styles to be animated

Note that individual animation requests will generally include only a subset of params.

Icon Controls

There are four possible values for config.icons, and the defaults are

{
    icons:
    {
        top: 'deficon',
        left: 'deficon',
        bottom: 'deficon',
        right: 'deficon'
    }
}

The class name values are added directly to the <i> tag for the control.

<i class="deficon"></i>

The default 'deficon' class simply makes black css triangles for the nav controls.

To use actual icons you can use your favorite icon provider.

For instance, here is an example using Font Awesome.

{
    icons:
    {
        top: 'fa fa-chevron-up',
        left: 'fa fa-chevron-left',
        bottom: 'fa fa-chevron-down',
        right: 'fa fa-chevron-right',
    }
}

This uses the library's 'chevron' icons for nav controls. Don't forget to properly setup your icon provider in your html.

Selector Display

There are four possible values for config.selectorDisplay.

value viewable offsets viewer details
hidden never no Selector is hidden from view and not updated
visible always yes Selector is part of content pane
transient toggle no User can toggle selector display
overlay always no Similar to 'transient' but without toggle

Note that the following config options have no effect unless selector display is 'transient'.

  • selectorHideDelay
  • showSelector
  • toggleDuration
  • toggleEasing

Content Scaling

HTML content can be scaled for either the slide or the thumbnail, and this scaling is specified by element tagname or css classname.

For instance, to scale all image content items to completely fill the thumbnail,

{ thumbScaleType: { img: 'content-max' } }

Or, to scale content items with a 'scale-me' class to fit in the slide,

{ slideScaleType: { 'scale-me': 'content-min' } }

There are four possible values for config.slideScaleType and config.thumbScaleType.

  • none
    No content scaling is performed.

  • content-max
    The content element is scaled up or down so that its smallest dimension fits in the slide or thumbnail. The content is then centered for the opposite dimension.

  • content-min
    The content element is scaled up or down so that its largest dimension fits in the slide or thumbnail. The content is then centered for the opposite dimension.

  • viewer
    The content container (ts-slide-content or ts-thumb-content) has its size increased to the size of the viewer area to allow content to flow and then (css transform) scaled back down by 50%. This is obviously more useful for thumbnails.

Slide Transitions

You can specify the transition for slide rotation in the configuration.

{ slideTransition: thumbslider.transitions.xxx }

Replace 'xxx' in the above with one of the following:

  • fade
    Fades in the next slide while fading out the current one.

  • slide
    Slides in the next slide while sliding out the current one.

  • stack
    Slides the next slide onto the current one.

  • unstack
    Slides the current slide off to reveal the next one.

Configuring Responsively

The default responsive setup is

{ responsive: { xs: 480, sm: 768, md: 1024, lg: 1200 } }

Use responsive labels ('xs', 'sm', etc.) inside other config options to have those values change responsively.

{
    selectorDisplay: { xs: 'hidden', def: 'transient' },
    selectorSize: { sm: 0.2, lg: 0.24, def: 0.3 }
}

Remember that/to

  • responsiveness is based on carousel container width, not window width.
  • the responsive label whose value is greater than or equal to the current container width will be in effect.
  • always specify a default (def) value in a config option to catch width values beyond the defined responsive configuration.
  • if a config option does not specify a value for the responsive label currently in effect the next level label (or def) will be used.

Generated Carousel HTML

<div class="ts-carousel">
  <div class="ts-viewer">
    <div class="ts-control ts-prev">
      <i class=""></i>
    </div>
    <div class="ts-view">
      <div class="ts-slides">
        <div class="ts-slide" data-ts-name="[CONTENT_NAME]">
          <div class="ts-slide-content">
            < content element >
          </div>
        </div>
        ... (repeated slide elements)
      </div>
    </div>
    <div class="ts-control ts-next">
      <i class=""></i>
    </div>
  </div>
  <div class="ts-selector">
    <div class="ts-select">
      <div class="ts-thumbs">
        <div class="ts-focus"></div>
        <div class="ts-thumb" data-ts-name="[CONTENT_NAME]">
          <div class="ts-thumb-overlay">
            <div class="ts-thumb-content">
              < content element >
            </div>
          </div>
        </div>
        ... (repeated thumb elements)
      </div>
    </div>
    <div class="ts-toggle"></div>
  </div>
</div>

Note that above HTML will replace original container contents.

Contextually Applied CSS Classes

  • For 'ts-content' element:

    • 'ts-selector-xxx'
      Applied with 'xxx' as the current config.selectorDisplay value

    • 'ts-selector-xxx'
      Applied with 'xxx' as the current config.selectorPosition value. This is not applied if config.selectorDisplay is 'hidden'.

    • 'ts-selector-xxx'
      Applied with 'xxx' as the current orientation of the selector ('horizontal' or 'vertical'). This is not applied if config.selectorDisplay is 'hidden'.

  • For 'ts-slide' and 'ts-thumb' elements:

    • config.activeClass
      Applied as these content items become current via selection or rotation.

Theming/Styling Guidelines

Remember that the carousel container must have height and width set.

When applying CSS styles to the generated HTML elements know that

properties
top, left, bottom, right, position should not be changed
z-index, overflow can be set as necessary but not recommended
height, width are ignored (values calculated and set inline)

In general, you should use pixel measurements (px) for styling your carousel.

There are a few themes available in /dist/themes that you can use outright or as a starting point for your own theme.

Thumbslider API

Module Functions

The following functions are available on the thumbslider module.

  • create(name:string, options:object):Carousel
    Creates a new carousel instance.

  • get(name:string):Carousel
    Returns a given carousel instance or null if not found.

  • names():array
    Returns a list of all carousel names.

  • options(name:string):object
    Returns a copy of the configuration options used to create a given carousel instance or null if not found.

  • update(name:string, options:object):Carousel
    Resets the given carousel with the specified configuration changes (i.e., these changes are merged with the carousel's original configuration)

Carousel Interface

There are a few methods that can be called on a thumbslider carousel instance.

  • currentIndex():number
    Returns the index of the current content item.

  • getName():string
    Returns the name (container id) of the carousel instance.

  • getSlide(id:string|number):node
    Returns the DOM element for the content slide by index or name.

  • getThumb(id:string|number):node
    Returns the DOM element for the content thumbnail by index or name.

  • itemCount():number
    The number of content items in the carousel.

  • remodel():this
    Recalculates the display of the carousel. Call this if you make style or other display changes to the carousel.

  • start():this
    Starts carousel rotation.

  • stop():this
    Stops carousel rotation.

Also see Carousel Events below for event registration methods available on the carousel interface.

Carousel Events

thumbslider uses event-mixer for event emission.

Event registration methods are mixed into the carousel interface using the below event names.

event name data params default preventable? details
rotate nextIndex:number yes occurs just before the next content item is displayed
toggle shown:boolean willShow:boolean yes occurs just before a transient selector is hidden/shown. This can be fired even if shown == willShow

Anything Else I Should Know?

Polyfilling

The polyfill-candidate language features needed by thumbslider include

    Array.isArray
    Array.prototype.filter
    Array.prototype.find
    Array.prototype.forEach
    Array.prototype.indexOf
    Array.prototype.map
    Array.prototype.reduce
    document.querySelector
    Element.prototype.classList
    getComputedStyle
    Object.assign
    Object.keys
    Symbol

You can use these by including 'thumbslider.poly.js' rather than 'thumbslider.js'.

<script type="text/javascript" src="../dist/thumbslider.poly.min.js"></script>

This makes the thumbslider export a function. Pass this function a callback that will get executed once the polyfills are loaded.

thumbslider(function(ts)
{
    // Create carousel instances here
    ts.create( ... );
});

The first call to this function adds script tag to <head> that grabs the necessary polyfills from the Polyfill.io CDN. Subsequent calls are queued or executed immediately if the features are already loaded.

Links

{ distrib } { updates } { feedback } { license } { versioning }

Please be sure to check 'updates' link when upgrading to a new version.

Examples

There are a few thumbslider examples in the /examples folder. These will be posted online somewhere soon.

Tests

thumbslider uses Jasmine for testing and Istanbul for coverage analysis.

Test coverage is imcomplete at this time.

npm test

In browsers thumbslider works as intended in the latest versions of Firefox, Chrome, Safari, and Opera. It works well in Edge also. There are some issues with IE for now.

Finally

Happy Carouselling!

Install

npm i thumbslider

DownloadsWeekly Downloads

3

Version

0.0.4

License

MIT

Last publish

Collaborators

  • avatar