JP Carousel v0.1.8

Carousel library for JustPremium creatives.

cdn: //cdn.justpremium.com/Justpremium/boilerplate/js/jp-carousel_0.1.7.js
cdn(beta): //cdn.justpremium.com/Justpremium/boilerplate/js/jp-carousel_0.1.8.js

Installation

• Ensure gsap is included in your html file; jp-carousel needs it (note since v0.1.6 you must use the new gsap ^3.0)

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

<script src="//cdn.justpremium.com/Justpremium/boilerplate/js/jp-carousel_0.1.8.js" charset="utf-8"></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:

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:

<!-- HTML -->
<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>

// Javascript
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 jp-carousel for targetElOrObject is ready in the DOM.

// Using HTM implementation
var carouselEl = document.getElementById("#my-carousel")
JPCarousel.callOnReady(carouselEl, function(el) {
    // carousel for carouselEl is ready
})

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

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)

constructor to create a new carousel instance

targetElOrOptions is the element containing your carousel items OR an options object (see below) (required)
type can be eitherJPCarousel.Horiz, JPCarousel.Vert or JPCarousel.Fade (optional)
navposition can be either JPCarousel.Bottom, JPCarousel.Right, JPCarousel.Top, JPCarousel.Left, or JPCarousel.None (optional)
infinite true will make the carousel loop infinitely (optional)
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 (optional)
navcontainer sets where the nav elements are added (optional)
noarrownav true will hide the arrow navigation UI

This can take the parameters directly in the constructor call OR since v0.1.8, 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);

// 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
}
var carouselObj = new JPCarousel(options);

showItem(targetIndex, time)

Shows item at targetIndex in time seconds

autoShowTimer(time)

Sets/resets auto timer to time milliseconds

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

setActive(active)

Sets carousel being active

getItems()

Returns an array of all the item elements

getCurrentIndex()

Returns the parsed current index

setIsFadeOutOtherItems(v)

Sets whether or not the other items fade out (only works for type=JPCarousel.Fade)

setAutoDeacSensitivity(v)

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

setIsSwipeEnabled(v)

Enables swiping | Default:true

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)

getAutoShowTime()

Gets current auto-show time

Custom Styling

Use the following classes: