Documentation

Version 1.4 (last updated February 15th, 2016).

XProSlider is professionally tailored slider control. It is easy to implement and offers limited and targeted set of features at its best with highest quality and performance. XProSlider is versatile, multimodes, can be implemented as a slider, a scroller or a gallery. It is control to enhance your website whether as website banner, picture or video gallery, news scroller or rss news scroller, etc.

Key features:

• Slide any html content such image, text or video (support Youtube, Vimeo and HTML5 video).
• Fully responsive, adjust width or height accordingly.
• XProSlider not only a slider but also carousel/scroller and a gallery. Can be configured to scroll content item continuously as running text or news bar.
• Auto Height mode to adjust height proportionally or fit content.
• Smart navigation, navigate to target slide instantly, doesn’t scroll all the way through target slide.
• Touch/swipe slide enable(on touch screen), click & drag (with mouse) & keyboard support.
• Support vertical/horizontal orientation.
• Support image, tab style or bullet style thumbnail (horizontal or vertical).
• Multiple transition effects: slide, fate, zoom, shrink etc.
• Layer animation support multiple effects with declarative syntax.
• Ken Burns effect, add Ken Burns effect with declarative syntax.
• Responsive Sticky Layer.
• HTML 5 video slide and background.
• Slide out animation.
• Ajax/lazy loading, external content linking, RSS and more.
• Automatically switch slide orientation at specified width.
• Automatically swith thumbnail orientation at specified width.
• Automatically distribute items evently in news/carousel mode.
• Slide in floating lightbox.
• Built-in lightbox to show content, image or video.
• Info Panel, display additional information for each slide.
• Automatic slide and manual slide. External control to slide is also supported.
• Loop content.
• Fit image in slider by width, height or auto detect.
• Set Image vertical alignment to top, center or bottom.
• Show progress during interval between slide.
• Dynamic API to add content at runtime.
• Compatible with all major browsers including mobile browser.
• Easy to implement, no complex template and scripting.
• 25+ real world implementation templates.

Browser compatibility:

All major browsers: IE8+, Safari, Chrome, Firefox, Opera, Mobile Chrome, Mobile Safari.

Note that layer animation is not available in IE8. Ken Burns effect is not available in IE8 and IE9.

Getting Started

Installing Scripts

XProSlider is javascript component, there is no special requirement in installation. Unzip the
slider package into your project folder. All the required scripts and stylesheets are in scripts/ folder

Include Slider Script and stylesheet in Page

<script src="sliderfolder/scripts/jquery-1.9.1.min.js"></script>

<script src="sliderfolder/scripts/slider.js"></script>

and the stylesheet

<link rel="stylesheet" href="sliderfolder/scripts/slider_base.css" />

Note that slider_base.css is basic css. Don’t edit this file directly, create new css file and import slider_base.css using CSS @mport then override the rules just like css file found in templates/ folder.
You can also use CSS file template folder as reference.

Create Slider Content

Slider content defined in the page are regular html elements with special css class marker. Below is the basic slider’s html template structure:

<div class="xpro-slider-container">
    <div id="scroller" class="xpro-slider">
        <div class="xpro-slider-content">
            <div class="xpro-slider-item">
                content 1
            </div>
            <div class="xpro-slider-item">
                content 2
            </div>
            <div class="xpro-slider-item">
                content 3
            </div>
            <div class="xpro-slider-item">
                content 4
            </div>
        </div>
    </div>    
</div>

Notice the element with class=”xpro-slider” should have id
assigned to be used in later script initialization. In this example the id is scroller

Initialize the Slider

Create slider object using the following syntax:

var slider = new XPRO.Controls.Slider();
slider.initSlider("element id", {options});

The function initSlider takes 2 arguments:

• (string) element id, id of slider template element
• (object) slider options

Put the initialization code in page load or jQuery ready event:

jQuery(document).ready(
    function() {
        var slider = new XPRO.Controls.Slider();
        slider.initSlider("scroller", {
                "mode"              : "slide",
                "iniWidth"          : 700,
                "iniHeight"         : 350,
                "autoHeightMode"    : "maintainratio",
                "thumbnails"        : {"navigation": false,
                                       "thumb_type": "bullet"}
        });     

    }
);            

Notice the first argument is scroller which is the id of slider template element.

Slider HTML Template

XProSlider template is very simple and easy to setup, it doesn’t change along with slider mode/configuration, all use the same template.
Below is the basic template structure:

<div class="xpro-slider-container">
    <div id="scroller" class="xpro-slider">
        <div class="xpro-slider-content">
            <div class="xpro-slider-item">
                Slider item 1 content here...
            </div>
            <div class="xpro-slider-item">
                Slider item 2 content here...
            </div>
            <div class="xpro-slider-item">
                Slider item 3 content here...
            </div>
            <div class="xpro-slider-item">
                Slider item n content here...
            </div>
        </div>
    </div>    
</div>

You just need to put slider content in item marked with class xpro-slider-item.
Content can be any html elements such as block, paragraph, image or video.

Image Item

Image item added using html <img> tag. For the image to be responsive, don’t specify dimension
(width or height, if you have to, use relative unit such as %)

<div class="xpro-slider-item">
    <img src="sample.jpg" />
</div>

Special CSS class for image.

A special css class xpro-slider-image can be apply for image item.
Only images with this class are affected by slider’s imageFit and imageVAlign option otherwise, image is positioned as document flow.

<div class="xpro-slider-item">
    <img src="sample.jpg" class="xpro-slider-image" />
</div>

Video Item

Video item is added using a <div> tag with following required attributes:

• class=“xpro-video-item”
• data-videourl=“youtube full url, vimeo full url or ‘html5′”
• data-display=“lightbox”, optional, if not specified, open the video inline.
• data-title=“some text”, optional, show video title at the bottom of item.

<div class="xpro-slider-item">
    <div style="width:100%" class="xpro-video-item" data-videourl="http://www.youtube.com/watch?v=Dsz4zNtHQ9k">
        <img src="images/avatar.jpg" />
    </div>
</div>

You can add image inside the element as video avatar.

HTML 5 Video Item

For html 5 video, set “html5” to data-videourl property.
Video source property should be defined inside video item using special markup class xpro-video-prop.

<div class="xpro-slider-item">
    <div style="width:100%" class="xpro-video-item" data-videourl="html5">
        <div class="xpro-video-prop" data-videourl="images/pedestrian.mp4" data-videotype="video/mp4"></div>
        <div class="xpro-video-prop" data-videourl="images/pedestrian.ogg" data-videotype="video/ogg"></div>
        <!-- Below you can add preview screen/avatar or other text to be displayed when video inactive.-->
        <img src="images/avatar.jpg" />
    </div>
</div>

Lazy Loaded Item

Lazy loading enable the slider to load image when it is about to slide. This are required attributes:

• class=“xpro-lazy”
• data-src=“image url”

<div class="xpro-slider-item">
    <img class="xpro-lazy" src="images/ajax-loader.gif" data-src="images/sample1.jpg" />
</div>

The example above lazy loads an image. You can display a small loading icon/animated as default image.

As of version 1.1, another way to lazy load image is introduced by using special markup class xpro-image-placeholder:

<div class="xpro-slider-item">
    <div class="xpro-image-placeholder" data-src="images/colorful_jelly.jpg" data-class="xpro-slider-image"></div>
</div>

Animated Layer

Add animation to slider with animated layer. You can add more than one layer to slider item.
Animated layer is added using <div> tag with the following attributes:

• class=“xpro-item-layer”
• data-effect=“(transition function)”

  Below are animation function currently supported:

  • As of 1.2, new universal animate() function is introduced with more declarative animation options:

    animate({X:’50px’, Y:’0px’, flip:”, rotate:”, zoom:”, skew:”, opacity:’0.7′, delay:’0.8s’, duration:’0.6s’, easing:’ease-in-cubic’})

    All options are optional except delay and duration.

    • X, translate horizontally in X unit. Pixel (px) or percent (%) is supported.
    • Y, translate vertically in Y unit. Pixel (px) or percent (%) is supported.
    • flip, flip horizontal or vertical:
      in-up, in-down, in-left, in-right
      out-up, out-down, out-left, out-right
    • rotate, rotate left or right:
      in-left, in-right
      out-left, out-right
    • zoom, zoom the layer:
      in, out
    • skew, skew layer:
      in-up, in-down, in-left, in-right
      out-up, out-down, out-left, out-right
    • opacity, set opacity.
    • delay, set delay before animation start in format ‘0.5s’ or ‘500ms’
    • duration, set animation duration in format ‘0.5s’ or ‘500ms’
    • easing, set easing function.

      For list of supported easing function, check Slider Modes.

  • This is still supported but animate() is recommended.

    slide({X:’50px’, Y:’0px’, delay:’0.8s’, duration:’0.6s’, opacity:’0.7′, easing:’ease-in-cubic’})

    This moves the layer X coordinate offset ’50px’ and Y offset ‘0px’ and target opacity 0.7 after ‘800ms’. The animation duration is ‘600ms’. The value of offset can be nagative.

    Other valid examples:

    slide({X:’50px’, Y:’0px’, delay:’0.8s’, duration:’0.6s’})
    slide({X:’-150px’, delay:’0.8s’, duration:’0.6s’})
    slide({Y:’-50px’, delay:’0.8s’})

  • This is still supported but animate() is recommended.

    fadeIn({delay:’1s’, duration:’0.8s’})

    Fade in effect. This can be achieved with slide({X:’0px’, Y:’0px’, delay:’0.6s’, duration:’0.8s’}) function above.

• data-effect-out=“(transition function)”
  This specify animation that run before a slide is fade out or slide out.
• data-apply-on-width=[width from]-[width to]

  Examples:

  • data-apply-on-width=”900″: apply only if width >= 900
  • data-apply-on-width=”500-700″: apply only if width >= 500 and width <= 700

  Animated layer in XProSlider are all responsive and scaled depends on screen. Unless it is necessary, you may not need to use this attribute.

    <div class="xpro-slider-item">
        <img src="images/sample2.jpg" />
        <div class="xpro-item-layer"
             data-effect="slide({X:'50px', Y:'40px', delay:'1s', duration:'0.8s'})"
             data-apply-on-width="500-700"
             style="top:0px;left:0px;opacity:0;background-color:rgba(255,255,255, 0.8);border:#ffffff 1px solid;">
            <h1 style="color:#ff0011;padding:10px 20px;margin:0px;">this is animated layer.</h1>
        </div>
    </div>

Animated layer with class xpro-item-layer can be nested.

Responsive Animated Layer

In addition to data-apply-on-width attribute for animated layer responsiveness, xproslider supports automatic scale on animated layer to make sure responsiveness.
Note that only positional and dimensional inline style attributes will be scaled. Scale depends on initial slider’s width and height (slider’s iniWidth & iniHeight option).

For non animated layer elements (elements inside slider item but not animated layer) and elements inside animated layer to scale automatically, use special class xpro-item-layer-responsive, otherwise the element will not be scaled.

    <div class="xpro-slider-item">
        <img src="images/sample2.jpg" />
        <h1 class="xpro-item-layer-responsive" style="color:#ff0000;padding:10px 20px;margin:10px;">this is title.</h1>
        <div class="xpro-item-layer"
             data-effect="slide({X:'50px', Y:'40px', delay:'1s', duration:'0.8s'})"
             style="top:0px;left:0px;opacity:0;background-color:rgba(255,255,255, 0.8);border:#ffffff 1px solid;">
            <h1 class="xpro-item-layer-responsive" style="color:#ff0011;padding:10px 20px;margin:0px;">this is animated layer.</h1>
        </div>
    </div>

Ken Burns Effect

Ken Burns effect (pan and zoom effect) can be applied to image or an element.
There are 9 predefined Ken Burns effect you can add to image or element,
as simple as adding css class.

• xpro-kenburns-dir-topleft
• xpro-kenburns-dir-topright
• xpro-kenburns-dir-top
• xpro-kenburns-dir-bottomleft
• xpro-kenburns-dir-bottomright
• xpro-kenburns-dir-bottom
• xpro-kenburns-dir-left
• xpro-kenburns-dir-right
• xpro-kenburns-dir-random, slider will randomly play the effect.

By default all this effect plays zoom out effect, for zoom in, add another special class to element xpro-kenburns-in

Example:

    <!--This specifies effect in top left direction and zoom out-->
    <div class="xpro-slider-item">
        <img src="images/sample2.jpg" class="xpro-kenburns-dir-topleft" />
    </div>

    <!--This specifies effect in random direction and zoom in-->
    <div class="xpro-slider-item">
        <img src="images/sample2.jpg" class="xpro-kenburns-dir-random xpro-kenburns-in" />
    </div>

This class can be applied to lazy loaded image.

Manually specify Ken Burns Effect

In case you need to manually specify Ken Burns effect for image or element, set data-effect attribute in animated layer with kenBurns() function:

    <div class="xpro-slider-item">
        <div class="xpro-item-layer"
             data-effect="kenBurns({X:'100px', Y:'50px', scale:'1.2', delay:'0.5s', duration:'6s'})"
             style="top:0px;left:0px;">
            <img src="images/image.jpg" />
        </div>
    </div>

HTML 5 Video Slide

Use HTML 5 video as slide background as alternative to image.
Just define html 5 video tag in side slider item. Slider will play/stop automatically during slide.

    <div class="xpro-slider-item">
        <video loop='loop' poster="images/skateboard.jpg" style="width: 100%; height: auto; visibility: visible;">
            <source src="images/skateboard.mp4" type="video/mp4">
            <source src="images/skateboard.ogg" type="video/ogg">
        </video>
        <!--You can add other layers here including animated layer-->
        ...
    </div>

Responsive Sticky Layer

Sticky layer always visible in slider, sticked on top of slider. You can show text, icon or image as sticky item.

    <div class="xpro-sticky-item" style="left:0px;right:0px;top:0px;" >
        <div style="background-color:rgba(0,0,0,0.5);margin:0px 40px;padding:10px 10px;">
            <h3 class="xpro-item-layer-responsive" style="text-align:center;font-size:14px;">HTML 5 Video Demo </h3>
        </div>
    </div>

Thumbnail

If thumbnail is enabled, you can provide html thumbnail for each slide.
This is done by adding a <div> tag with required attribute:

• class=“xpro-thumb-item”

    <div class="xpro-slider-item">
        <img src="images/sample2.jpg" />
        <div class="xpro-thumb-item"><img src="images/thumbs/sample_thm1.jpg" /></div>
    </div>

Note: Defining thumbnail template doesn’t automatically enable the thumbnails,
you have to enable thumbnail in slider configuration.

Float Thumb

Float thumb is floating hint displayed when mouse hover over navigation or thumbnails.

To enable this, create thumbnail markup using class xpro-thumb-item as described in previous section and enable floatThumb option in slider initialization.

jQuery(document).ready(
    function() {
        var slider = new XPRO.Controls.Slider();
        slider.initSlider("scroller", {
                "mode"              : "slide",
                "iniWidth"          : 700,
                "iniHeight"         : 350,
                "autoHeightMode"    : "maintainratio",
                "thumbnails"        : {"navigation": false,
                                       "thumb_type": "bullet"},
                "floatThumb"        : true
        });     

    }
);            

Item Info

Item info is extra information for each slider item. You can add extra information like title or short description to each slide.
Item info is added by using a <div> tag with required attribute:

• class=“xpro-slider-info”

<div class="xpro-slider-item">
        <img src="images/sample2.jpg" />

        <div class="xpro-slider-info">
            <h3>Slide 7</h3>
            <p>Some text ... Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
            <p>Some text ... Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
            <p><a href="http://www.xprojs.com/slider">Click here for more information.</a></p>
        </div>

    </div>

Note: Info item doesn’t automatically show in slider, you have to enable the info panel in slider configuration.

Built-in Lightbox

Add link to open image, video or html page in lightbox. Attributes:

• data-display, required, value ‘inline’.
• href, required, html page url, image or youtube/vimeo url.
• data-display-type, depends on HREF:
  • If image, this attribute is ignored.
  • If youtube/vimeo, the value should be ‘video’.
  • If html page, it is optional, if value is ‘iframe’ it display page in iframe, otherwise it displays the page inline, .

<a href="image.jpg" data-display="lightbox"></a>
<a href="youtube-url" data-display="lightbox" data-display-type="video"></a>
<a href="somepage.htm" data-display="lightbox" data-display-type="iframe"></a>

Slider Modes

Slider mode set the transition mode from one slide to another.

jQuery(document).ready(
    function() {
        var slider = new XPRO.Controls.Slider();
        slider.initSlider("scroller", {
                "mode"              : "slide",
                "iniWidth"          : 700,
                "iniHeight"         : 350,
                "autoHeightMode"    : "maintainratio",
                "thumbnails"        : {"navigation": false,
                                       "thumb_type": "bullet"}
        });     

    }
);            

There are 5 modes supported:

slide

Slide current item out while sliding next item in.

carousel

Slide current item out while sliding next item in with visible near by slides.

slideOut

Slide current item out

fade

Fade in next item.

custom

if this is selected, slide effect for each slider item must be provided. To set slide effect, set data-effect attribute to slider item

    <div class="xpro-slider-item" data-effect="slideOut({dir:'up', easing:'ease-in-cubic'})" style="" >
        <img src="images/sample1.jpg" />
        <h1 class="xpro-item-layer-responsive" style="color:#ff0000;padding:10px 20px;margin:10px;">this is title.</h1>
        ...
    </div>
    <div class="xpro-slider-item" data-effect="shrinkOut({easing:'ease-out-cubic'})" style="" >
        <img src="images/sample2.jpg" />
        ...
    </div>

Here are list of effect functions currently supported:

• slideOut({dir:’up’, delay:’1s’, duration:’0.8s’, easing:’ease-in-cubic’})
• fadeOut({delay:’1s’, duration:’0.8s’, easing:’ease-in-cubic’})
• zoomOut({delay:’1s’, duration:’0.8s’, easing:’ease-in-cubic’})
• shrinkOut({delay:’1s’, duration:’0.8s’, easing:’ease-in-cubic’})

The options are optional, for example data-effect=’zoomOut’ will still work with default value.

List of supported easing function

• ease
• ease-in
• ease-out
• ease-in-out
• linear
• ease-in-cubic
• ease-in-expo
• ease-in-circ
• ease-in-bounce
• ease-out-cubic
• ease-out-expo
• ease-out-circ
• ease-out-bounce
• ease-inout-cubic
• ease-inout-expo
• ease-inout-circ
• ease-inout-bounce

Slider Options

Stylesheet Reference

This section detail the css rule used in slider.

This are basic css classes use in XProSlider. For complete rules, please check base stylesheet located in scripts/skins/base/slider.css.
Also note that all skins/templates class should derive from this base stylesheet using css @import.

API Reference

Slider is created using class XPRO.Controls.Slider class.

FAQ

This section provide general and frequently asked questions and the answer.

1. What is XProSlider
2. There are many slider script out there, how are XProSlider different?
3. What are the requirement for XProSlider?
4. How about update is it available for free?
5. What kind of support you provide?

What is XProSlider

XProSlider is professionally tailored slider control.
It is easy to implement and offers limited and targeted set of features at its best with highest quality and performance.
XProSlider is versatile, responsive, multimodes, can be implemented as a slider, a scroller or a gallery.
It is control to enhance your website whether as website banner, picture or video gallery, news scroller or rss news scroller, etc.

There are many slider script out there, how are XProSlider different?

XProSlider is multipurpose and verastile slider component. It focus on functionality as well as
usability. XProSlider not only implemented as banner as most slider do but also can be implemented
as image gallery with options like lightbox, ajax, navigation. It can also be implemented as news slider
or news bar, content can be added/loaded at runtime. This features mostly not found in other slider component.

What are the requirement for XProSlider?

XProSlider only requires jQuery core script and it runs on all most popular browsers.

How about update is it available for free?

Yes, update is free whenever it is available.

What kind of support you provide?

We provide email support, just contact us whenever you have problem.