thumbslider

v0.0.4

Published

4 years ago

responsive javascript carousel with thumbnails

0High
0Medium
0Low

captison

carousel responsive scalable theme themed thumbnails

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

the first descendant of the content item found having a 'data-ts-thumb' attribute, or
the first non-text node in the content item, or
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!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Thumbslider

What is this?

Features

Fantastic! How do I get it?

npm

bower

What's the Setup?

How Does It All Work?

Configuration Options

Animators

Icon Controls

Selector Display

Content Scaling

Slide Transitions

Configuring Responsively

Generated Carousel HTML

Contextually Applied CSS Classes

Theming/Styling Guidelines

Thumbslider API

Module Functions

Carousel Interface

Carousel Events

Anything Else I Should Know?

Polyfilling

Links

Examples

Tests

Finally