AJAX-ZOOM jQuery responsive thumb and content slider (horizontal / vertical) - $.axZmThumbSlider(options)

Plugin version: 1.3
Date: 2014-09-02

Dependencies: jQuery 1.2+; jquery.mousewheel.js (optionally for mousewheel scrolling); jquery.axZm.js (supposed to be used with AJAX-ZOOM);

License: AJAX-ZOOM license - http://www.ajax-zoom.com/index.php?cid=download#heading_4

About: this thumb slider plugin can be used optionally / complementary to several AJAX-ZOOM implementations. It is not required to use it. In the AJAX-ZOOM examples where this slider is implemented it can be easily replaced by any other thumb slider.

Why an other thumb slider: for external usage ("around AJAX-ZOOM on several AJAX-ZOOM example pages") we have previously used "jCarousel". Howver the former major jCarousel version has been developed around 2006 and it seemed to have had it glorious days in the past. The current, newly released jCarousel did not fulfill our expectations. Some alternatives found on the web either. Compared to AJAX-ZOOM a "thumb slider" looked like couple lines of code so we have decided to write our own plugin to use with AJAX-ZOOM. From the perspective of a coder / designer axZmThumbSlider is quite easy to implement, can be configured over javascript / CSS, is responsive and has generally needed API / options available. It can also be used as "content scroller" (not just thumbs), but this functionality is not well elaborated yet.

Demo

Horizontal slider with fixed width
external controls / some API showcase

External controlls:
scrollTo thumb:
[first] [4] [8 last] [8 middle] [8 first] [12] [last] [random]
scrollTo %:
[20%] [50% last] [50% middle] [50% first] [80%]
scrollTo px:
[200px first] [800px last] [800px middle] [800px first] [1400px]
scrollBy %:
[20%] [-20%] [100%] [-100%]
scrollBy px:
[200px] [-200px] [500px] [-500px]
Toggle width:
47px 200px 500px 800px window width - 40 50% 80% 100%
Handle thumbs:
prependThumb appendThumb removeThumb (last) removeThumb (first)
insertThumbAfter (1) insertThumbBefore (3) removeAllThumbs

All methods except getters can be chained; some methods like "appendThumb" have also callbacks which arguments are referencing added thumb;

Horizontal slider with fixed width
and nothing to slide inside

If no height of the element is set the plugin will try to set it instantly
and complain about it in console if available.

Horiszontal slider without buttons,
custom scrollbar and wraped by other element

Simple slider, no mouse scroll, scrollBy: 3

Simple slider with mouseFlowMode enabled

Responsive horiszontal slider width 100%

Vertical sliders with fixed height
scrollbar left or right

Content Mode - vertical slider without thumbs
(experimental)

HTML Ipsum Presents

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis. Ut felis.

VoilĂ  - nested slider

Header Level 2

  1. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  2. Aliquam tincidunt mauris eu risus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus magna. Cras in mi at felis aliquet congue. Ut a est eget ligula molestie gravida. Curabitur massa. Donec eleifend, libero at sagittis mollis, tellus est malesuada tellus, at luctus turpis elit sit amet quam. Vivamus pretium ornare est.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis. Ut felis. Praesent dapibus, neque id cursus faucibus, tortor neque egestas augue, eu vulputate magna eros eu erat. Aliquam erat volutpat. Nam dui mi, tincidunt quis, accumsan porttitor, facilisis luctus, metus

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

Documentation

Options

$(selector).axZmThumbSlider(options);

OptionDefaultDescription
orientation 'horizontal' Orientation value, horizontal or vertical
smoothMove 12 Smoothness of the scrolling
pressScrollSpeed 6 Max speed of movement while pressing on the buttons
pressScrollSnap false Snap to thumb after pressing on the buttons
pressScrollTime 250 Time ms if it is not clicked to start continuous stepless scroll
contentMode false Simple content scroller instead of thumbs (experimantal)
circularClickMode false Pressing on next, prev buttons will result into scrolling to next el and click on it instantly. It will however not result into visual endless loop, instead the fokus will be turned to first thumb when last is reached
liImgAsBack true Images insude li tags (thumbs) will be removed and put as background of the li element
randomize false Randomize order of thumbs on load, see also API methods for randomizing
firstThumb 1 Thumb to show at first
firstThumbPos 'middle' Default position within the slider (if possible), possible values: first, middle, last
firstThumbTriggerClick false Trigger click on firstThumb
firstThumbHighlight false Highlight firstThumb if firstThumbTriggerClick is not enabled
posOnClick 'middle' Scroll the thumb to some position within the slider, possible values: false, 'first', 'middle', 'last'
scrollBy 'auto -1'
  • Integer - number of slides scrolled when clicked on the backward / forward button
  • Can be also 'auto' or expression with auto and integer as string, e.g. 'auto -1'
  • String e.g. '50%' or '150px'
mouseWheelScrollBy '20%' Use moousewheel for scrolling, requires Brandon Aaron's mousewheel.js; integer - number thumbs; string - px or % value, e.g. '50px' or '20%'
debugNumbers false Adds numbers to the thumbs, css .axZmThumbSlider div.debugNumbers
mouseFlowMode false Slider position upon mouse position on the slider
mouseFlowMargin 25 Margin from left/right or top/bottom where mouse position for mouseFlowMode is not captured
thumbLiStyle {} Quickly overwrite thumb style (e.g. width and height) without changing css file or write inline styles
thumbImgStyle {} Can be applied when "liImgAsBack" option is disabled
thumbLiSubClass{mousehover: 'mousehover', selected: 'selected', first: 'first', last: 'last'} Array like object representing thumb subclasses; you can disable by setting a value to false
ulClass 'axZmThumbSlider' Main class prefix for ul element
wrapClass 'axZmThumbSlider_wrap' Wrap class thumbs
contentClass 'axZmThumbSlider_content' Wrap class for contentMode
contentStyle/td> {} Ver. 1.3+ Wrap style for contentMode
wrapStyle {} Quickly override styles for the wraper
outerWrapPosition 'absolute' Ver. 1.3+ If parent conainer has padding, setting this value to 'relative' will preserve it
centerNoScroll true Center thumbnails in the slider when there is nothing to scroll
btn true Enable buttons instantly
btnOver false 1.3+ Button is put over thumbs
btnHidden false 1.3+ Hide button if it is disabled
btnClass 'axZmThumbSlider_button' Main class prefix for buttons
btnMargin null Distance from button to scroll area; this margin can be also set in CSS
btnBwdStyle null Quickly override css values of backword button instead of changing class
btnFwdStyle null Quickly override css values of forward button instead of changing class
btnLeftText '«' Text for backword button (horizontal orientation)
btnRightText '»' Text for forward button (horizontal orientation)
btnBwdObj null External backword button jQuery element
btnFwdObj null External forward button jQuery element
scrollbar false Enable / disable scrollbar
scrollBarIndicator false If true no actions will be attached to track or scrollbar
scrollbarMinDim 20 Min bar width for horizontal / height for vertical slider
scrollbarMaxDim null Max bar width for horizontal / height for vertical slider
scrollbarClass 'axZmThumbSlider_scrollbar' Scrollbar class
scrollbarMargin null Distance which shrinks the length of the scrollbar, can be set with css as well
scrollbarOffset null Offset of the scrollbar, can be set with css as well
scrollbarStyle {} Quickly overwrite position of the scrollbar
scrollbarContainerStyle {} Quickly set the margins of slider to fit buttons
scrollbarBarStyle {} Quickly set bar style (color, height, margin)
scrollbarTrackStyle {} Quickly set slidebar track style (color, height/width, margin)
scrollbarOpacity 0.85 Opacity while doing something
scrollbarIdleOpacity 0.35 Opacity in idle state
scrollbarIdleTimeout 350 If scrollbarIdleOpacity is not set to 1, apply it after this ms value
scrollBarIdleFadeoutT 200 Fadeout time of the scrollbar
scrollBarMouseShowBindTo 'both' Bind mouseenter opacity handle functions to scrollbar itself or container, possible values: 'scrollBar', 'container', 'both' or false
accVelocity 45 Acceleration velocity for touch devices
touchOpt {smoothMove: 12, pressScrollSpeed: 6} Override any options for touch devices, e.g. touchOpt: {btn: false, scrollBarIndicator: true, scrollbarIdleOpacity: 0}

Callbacks

Usage same as options; let us know if you need other callbacks.

Callback / OptionDefaultDescription
onPull null Function to execute after reached end or beginning of the slider, e.g. make a call to add other thumbs (see methods below)
holdPullPx 50 Min pixel to pull in either direction to trigger onPull
holdPullTime 750 Min time to pull in either direction to trigger onPull
onInit null Callback when plugin is created

Methods

$(selector).axZmThumbSlider(method, [arguments]); e.g. $('#slider1').axZmThumbSlider('scrollBy', '50px');

MethodDescriptionArguments
stop Stop initialized plugin -
run Run initialized plugin -
destroy Reward element to initial state -
rebuild Destroy and rebuild plugin -
scrollBy Scroll by a specified amount of pixels or prc String, px or % value, e.g. '20px' or '50%'
scrollTo Scroll to specified thumb or position
  1. Options object:
    • thumb: integer or string; integer e.g. 3 will scroll to third thumb; string e.g. '120px' or '50%' will scroll to this specified location
    • thumbPos: string; if thumb is integer (scroll to some thumb), the target position within visible area, possible values: first, middle or last
    • noAnm: bool; if true scrollTo position will be reached immediately without any animation
    • triggerClick: bool; trigger click on the thumb
    • highlight: bool; only highlight thumb
If agrument is not options object, then it will be interpreted as thumb, e.g. $('#slider1').axZmThumbSlider('scrollTo', {thumb: 7});
is same as
$('#slider1').axZmThumbSlider('scrollTo', 7);
appendContent Append content if in contentMode
  1. Well formated html as string
  2. Callback function
prependContent Prepend content if in contentMode
  1. Well formated html as string
  2. Callback function
removeAllThumbsRemove all thumbs
  1. Callback function
removeThumbRemove thumb
  1. Thumb number or selector, see also isThumb
  2. Callback function
appendThumbAppend thumb
  1. Thumb image path as tring, object or formated html as string
  2. Optional click function
  3. Optional callback function with first argument as jQuery reference to the appended element (thumb) and the second argument as thumb number e.g.
    								$('#slider1').axZmThumbSlider('appendThumb', 
    									'images/image_01.jpg', 
    									function(){
    										// Click event
    										alert('123');
    									}, 
    									function(el, no){
    										// Callback, after thumb added slide to it
    										$('#slider1').axZmThumbSlider('scrollTo', no);
    									}
    								); 
    								
prependThumbPrepend Thumb
  1. Thumb image path as tring, object or formated html as string
  2. Optional click function
  3. Optional callback function with first argument as jQuery reference to the prepended element (thumb) and the second argument as thumb number
insertThumbAfterInsert Thumb after some other thumb
  1. Thumb image path as tring, object or formated html as string
  2. Optional click function
  3. After as thumb number, selector, ...
  4. Optional callback function with first argument as jQuery reference to the inserted element (thumb) and the second argument as thumb number
insertThumbBeforeInsert Thumb before some other thumb
  1. Thumb image path as tring, object or formated html as string
  2. Optional click function
  3. Before as thumb number, selector, ...
  4. Optional callback function with first argument as jQuery reference to the inserted element (thumb) and the second argument as thumb number
unselectRemove "selected" class from all thumbs -
selectVer. 1.3+ Select specified thumb
  1. Thumb number or selector, see also isThumb
  2. Bool - trigger click
getNumberThumbsVer. 1.3+ Returns number of currently loaded thumbs -
isThumbReturns n - (thumb number) from passed argument;
  1. Argument can be just number to confirm it is there, selector or object
getVisibleThumbReturns number of thumb which is visible first
  1. If true returns thumb from right / bottom
randomize Shuffle thumbs within loader element -
getUlEll Returns scrolling content jQuery element (ul or div in contentMode) -
sortMapVer. 1.3+ Reorder thumbs in the slider upon data attribute value
  1. Object which maps the order, e.g. {1:3,2:1} which would mean, that at first place there will be thumb with specified data attribute equals to three, at second place thumb with data attribute equals to one
  2. String: name of data attribute, e.g. data-number
  3. Optional callback function