JP Carousel

Carousel library for GumGum creatives

Working example creatives can be found on the downloads-examples page.

CDN latest release:

• //cdn.justpremium.com/Justpremium/boilerplate/js/jp-carousel_0.2.0.js

CDN previous release:

• //cdn.justpremium.com/Justpremium/boilerplate/js/jp-carousel_0.1.9.js

Installation

• Ensure gsap is included in your html file; jp-carousel needs it.

• Include a script tag in your html file, after the gsap tag:

<script src="//cdn.justpremium.com/Justpremium/boilerplate/js/jp-carousel_0.2.0.js"></script>

Implementation

There are 2 ways to implement the carousel; either with an HTML element attribute (faster but reduced control and features) or with JavaScript (need to type a few lines of code but gives full control and features). Note that by default the carousel will have no width or height; this needs to be set.

Using an html attribute

Wrap elements for your carousel in a div with attribute jp-carousel. By default, the carousel will have horizontal transition and arrow navigation.

<div jp-carousel id="carousel">
    <div style="background-image:url(assets/frame-01.png)"></div>
    <div style="background-image:url(assets/frame-02.png)"></div>
    <video src="assets/video.mp4" playsinline muted poster="assets/poster.jpg"></video>
</div>

You can configure the carousel by setting keywords in the attribute value. Here are all the values jp-carousel accepts:

value	effect
vertical	transition type vertical
fade	transition type fade
infinite	items in an infinite loop
dotnav-top	add dot navigation at the top or left
dotnav-bottom	add dot navigation at the bottom or right
noarrownav	disable arrow navigation
arrowsrc:path/to/arrow.png	custom image for the arrow left/top nav button (rotated for use in both placements)
periphery:decimalvalue	peripery value, for cover-flow effect

Of course, you can add multiple key words together:

<div jp-carousel="vertical infinite arrowsrc:assets/arrow-up.png" id="carousel">
    <div style="background-image:url(assets/frame-01.png)"></div>
    <div style="background-image:url(assets/frame-02.png)"></div>
    <div style="background-image:url(assets/frame-03.png)"></div>
</div>

Using JavaScript

Using this implementation, do not add the jp-carousel attribute. Instead initiate it with JavaScript, passing the containing DIV as the first argument:

<div id="carousel">
    <img jp-noClick src="assets/men/frame-01.png" alt="">
    <img jp-noClick src="assets/men/frame-02.png" alt="">
    <img jp-noClick src="assets/men/frame-03.png" alt="">
</div>

var carouselEl = document.getElementById("carousel");
var carouselObj = new JPCarousel(carouselEl)

API

JPCarousel.getObject(targetElOrSelector)

Returns the jp-carousel object for targetElOrSelector. Use this object to control and get data from the carousel.

var carouselObj = JPCarousel.getObject(document.getElementById("carousel"));
// var carouselObj = JPCarousel.getObject("#carousel");
carouselObj.setActive(false);
var index = carouselObj.getCurrentIndex()

JPCarousel.callOnReady(targetElOrObject, callback)

callback is called when the jp-carousel instance for targetElOrObject is ready in the DOM.

// Using HTM implementation
var carouselEl = document.querySelector("#my-carousel")
JPCarousel.callOnReady(carouselEl, function(el, obj) {
    el === carouselEl // true
    obj === JPCarousel.getObject(carouselEl) // true
})

// Using JS implementation
var carouselObj = new JPCarousel(carouselEl);
JPCarousel.callOnReady(carouselObj, function(el, obj) {
    el === carouselEl // true
    obj === carouselObj // true
})

JPCarousel.UseTouchEvents

Override whether or not the carousel uses touch events or mouse events.

JPCarousel.UseTouchEvents = true;

JPCarousel(targetElOrOptions, type, navposition, infinite, arrowsrc, periphery, noshowitem, navcontainer, noarrownav, fadeoutotheritems, sizeratio)

Constructor to create a new JPCarousel instance

Parameter	Definition
targetElOrOptions	the element containing your carousel items OR an options object (see below) required
type	can be either JPCarousel.Horiz, JPCarousel.Vert or JPCarousel.Fade default: JPCarousel.Horiz
navposition	can be either JPCarousel.Bottom, JPCarousel.Right, JPCarousel.Top, JPCarousel.Left, or JPCarousel.None default: JPCarousel.Bottom
infinite	true will make the carousel loop infinitely default: false
arrowsrc	path to a custom arrow-nav button (pointing left or up - right/down will be rotated 180degs) optional
periphery	is how much of the space is taken by images in the periphery, for a cover-flow effect. From 0 to 1 optional
noshowitem	prevents automatic call to showItem(0) on init default: false
navcontainer	sets where the nav elements are added optional
noarrownav	true will hide the arrow navigation UI optional
fadeoutotheritems	true will have the other items fade out (only works for type=JPCarousel.Fade) optional
sizeratio	make the carousel maintain its own height based on its width optional

This can take the parameters directly in the constructor or it can take an options object:

var carouselObj = new JPCarousel(carouselEl, JPCarousel.Horiz, JPCarousel.Bottom, false, 
"assets/arrow.png", 0.6, false, document.body, true, true, 1.777);

OR

var options = {
    target: carouselEl,
    type: JPCarousel.Horiz,
    navposition: JPCarousel.Bottom,
    arrowsrc: "assets/arrow.png",
    infinite: false,
    periphery: .6,
    noshowitem:false,
    navcontainer:document.body,
    noarrownav:true,
    fadeoutotheritems:true,
    sizeratio:1.777 // ratio for 16/9
}
var carouselObj = new JPCarousel(options);

Please note, it is only necessary to define the values you need.

showItem(targetIndex, time)

Shows item at targetIndex in time seconds

autoShowTimer(time)

Sets/resets auto timer to time milliseconds | Turn off by sending undefined as the time

Events

Events constants are:

JPCarousel.Event_ShowItem // "showitem";
JPCarousel.Event_PrepShowItem // "prepshowitem";  
JPCarousel.Event_SwipeItem // "swipeitem";

on(‘showitem’, func)

Example:

// carouselObj.setCallOnShowItem(function(index) { // legacy method
carouselObj.on("showitem", function(index) {
   console.log("Carousel is showing item " + index);
})

on(‘prepshowitem’, func)

Example:

// carouselObj.setCallOnPrepareShowItem(function(index) { // legacy method
carouselObj.on("prepshowitem", function(index) {
   console.log("Carousel is preparing to show item " + index);
})

on(‘swipeitem’, func)

Example:

carouselObj.on("swipeitem", function(direction) {
   console.log("Carousel has been swiped to the " + direction);
})

Getters and Setters

getItems()

Returns an array of all the item elements

getCurrentIndex()

Returns the parsed current index

getAutoShowTime()

Gets current auto-show time

getCurrentItem(offset)

Gets current active item element.

Parameter	Definition
offset	integer offset from current: -1 for item before; 0 for current item; 1 for item after. Default:0

var currentItem = carouselObj.getCurrentItem();
var prevItem = carouselObj.getCurrentItem(-1);
var nextItem = carouselObj.getCurrentItem(1);

setAutoDeacSensitivity(v)

Sets the threshold allowed to swipe perpendicular the carousel motion | Default:50px

setIsSwipeEnabled(v)

Enables swiping | Default:true

setActive(active)

Sets carousel being active

setThreshold(v)

Sets minimum pixels needed to trigger a swipe | Default:20px

setTweenTime(v)

Sets the tween time for the transition | Default:.4

setTweenEase(v)

Sets the gsap ease for the transition

setTranslateFactor(v)

Sets how much the other items translate (only for periphery > 0)

Custom Styling

Use the following classes:

class	target element
jp-carousel	the whole carousel element
jp-carousel-main-view	the main view (without nav elements)
jp-carousel-item	individual item elements
jp-carousel-dotnav-holder	the div containing dots of dot navigation
jp-carousel-dotnav	the dots of the dot navigation
jp-carousel-dotnav-active	the active dot of the dot navigation
jp-carousel-arrownav-holder	the divs containing arrow nav buttons (the children of these elements is/are the arrow button)
jp-carousel-arrownav-holder-left	the div containing left/top arrow nav button
jp-carousel-arrownav-holder-right	the div containing right/bottom arrow nav button
jp-carousel-default-arrow-box	the box of the default arrow buttons
jp-carousel-default-arrow-shape	the arrow shape of the default arrow buttons