Skip to content

Latest commit

 

History

History
338 lines (277 loc) · 22.8 KB

README.textile

File metadata and controls

338 lines (277 loc) · 22.8 KB

AnythingSlider jQuery Plugin

Just what the world needs, another jQuery slider. YAWN. I know, check this one out though, it’s got lots of cool features.

Here on CSS-Tricks, I’ve created a number of different sliders. Three, in fact. A “featured content” slider, a “start/stop slider”, and “moving boxes”. Each of them had some cool interesting feature that I needed to build at the time. All were well-received, but as is the case with these things, people want them to do X, Y, and Z in addition to what they already did.

This new AnythingSlider is an attempt at bringing together the functionality of all of those previous sliders and adding new features. In other words, to create a really “full featured” slider that could be widely useful. This is the first time (on CSS-Tricks) that one of these sliders is an actual plugin as well, which should make implementing it and customizing it much easier.

Keep Reading | See a Demo!

Features

  • Panels are HTML Content (can be anything).
  • Multiple AnythingSliders allowable per-page.
  • Add or remove content, then easily update the slider.
  • Infinite/Continuous sliding (always slides in the direction you are going, even at “last” slide).
  • Optionally resize each panel (specified per panel in css).
  • Optional Next / Previous Panel Arrows.
  • Use keyboard navigation or tabs that are built and added dynamically (any number of panels).
  • Link to specific slides or go forward or back one slide from static text links.
  • Each panel has a hashtag (can link directly to specific panels).
  • Optional custom function for formatting navigation text.
  • Auto-playing slideshow (optional feature, can start playing or stopped)
  • Pauses playing YouTube videos when not in view and resumes them when in view (if files are hosted on the web).
  • If slideshow is active, a playing video will complete before the slideshow continues.
  • Pauses slideshow on hover (optional).
  • Optionally play the slideshow once through, stopping on the last page.
  • Optional FX extension to add animation to panels elements as they scroll into and out of view. See the demo page.

Default Options

$('#slider1, #slider2').anythingSlider({
  // Appearance
  width               : null,      // Override the default CSS width
  height              : null,      // Override the default CSS height
  resizeContents      : true,      // If true, solitary images/objects in the panel will expand to fit the viewport
  tooltipClass        : 'tooltip', // Class added to navigation & start/stop button (text copied to title if it is hidden by a negative text indent)
  theme               : 'default', // Theme name
  themeDirectory      : 'css/theme-{themeName}.css', // Theme directory & filename {themeName} is replaced by the theme value above

  // Navigation
  startPanel          : 1,         // This sets the initial panel
  hashTags            : true,      // Should links change the hashtag in the URL?
  enableKeyboard      : true,      // if false, keyboard arrow keys will not work for the current panel.
  buildArrows         : true,      // If true, builds the forwards and backwards buttons
  toggleArrows        : false,     // if true, side navigation arrows will slide out on hovering & hide @ other times
  buildNavigation     : true,      // If true, builds a list of anchor links to link to each panel
  enableNavigation    : true,      // if false, navigation links will still be visible, but not clickable.
  toggleControls      : false,     // if true, slide in controls (navigation + play/stop button) on hover and slide change, hide @ other times
  appendControlsTo    : null,      // A HTML element (jQuery Object, selector or HTMLNode) to which the controls will be appended if not null
  navigationFormatter : null,      // Details at the top of the file on this use (advanced use)
  forwardText         : "»", // Link text used to move the slider forward (hidden by CSS, replaced with arrow image)
  backText            : "«", // Link text used to move the slider back (hidden by CSS, replace with arrow image)

  // Slideshow options
  enablePlay          : true,      // if false, the play/stop button will still be visible, but not clickable.
  autoPlay            : true,      // This turns off the entire slideshow FUNCTIONALY, not just if it starts running or not
  startStopped        : false,     // If autoPlay is on, this can force it to start stopped
  pauseOnHover        : true,      // If true & the slideshow is active, the slideshow will pause on hover
  resumeOnVideoEnd    : true,      // If true & the slideshow is active & a youtube video is playing, it will pause the autoplay until the video is complete
  stopAtEnd           : false,     // If true & the slideshow is active, the slideshow will stop on the last page
  playRtl             : false,     // If true, the slideshow will move right-to-left
  startText           : "Start",   // Start button text
  stopText            : "Stop",    // Stop button text
  delay               : 3000,      // How long between slideshow transitions in AutoPlay mode (in milliseconds)
  animationTime       : 600,       // How long the slideshow transition takes (in milliseconds)
  easing              : "swing",   // Anything other than "linear" or "swing" requires the easing plugin

  // Callbacks
  onBeforeInitialize  : null,      // Callback before the plugin initializes
  onInitialized       : null,      // Callback when the plugin finished initializing
  onShowStart         : null,      // Callback on slideshow start
  onShowStop          : null,      // Callback after slideshow stops
  onShowPause         : null,      // Callback when slideshow pauses
  onShowUnpause       : null,      // Callback when slideshow unpauses - may not trigger properly if user clicks on any controls
  onSlideInit         : null,      // Callback when slide initiates, before control animation
  onSlideBegin        : null,      // Callback before slide animates
  onSlideComplete     : null,      // Callback when slide completes

  // Interactivity
  clickArrows         : "click",         // Event used to activate arrow functionality (e.g. "click" or "mouseenter")
  clickControls       : "click focusin", // Events used to activate navigation control functionality
  clickSlideshow      : "click",         // Event used to activate slideshow play/stop button

  // Misc options
  addWmodeToObject    : "opaque",  // If your slider has an embedded object, the script will automatically add a wmode parameter with this setting, if swfobject.js is active
  maxOverallWidth     : 32766      // Max width (in pixels) of combined sliders (side-to-side); set to 32766 to prevent problems with Opera
});

Setup

Add the following inside the <head></head> of your page

<!-- Required -->
<link type="text/css" href="css/anythingslider.css" rel="stylesheet" media="screen" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
<script type="text/javascript" src="js/jquery.anythingslider.js"></script>
<script type="text/javascript">
$(function () {
 $('#slider1').anythingSlider(); // add any non-default options here
});
</script>

<!-- Optional -->
<script type="text/javascript" src="js/jquery.easing.1.2.js"></script>
<script type="text/javascript" src="js/swfobject.js"></script>

Example HTML

 <ul id="slider1">
  <li><div class="text">Put anything you want here</div></li>
  <li><img src="image1.jpg" /></li>
  <li><object>...</object></li>
  <li>
   <div class="list">
    <h4>Title</h4>
    <ul>
     <li>List item #1</li>
     <li>List item #2</li>
    </ul>
   </div>
  </li>
 </ul>

Usage

Updating the Slider (content added or removed) – options will be ignored.

  • Any options added inside the anythingSlider call will be ignored.
  • Note that if you are removing any panels from AnythingSlider, make sure your script ignores the cloned panels (they have a ‘cloned’ class). See the page source of “index.html” for an example.
$(‘#slider1’)
.append(‘<li><img src="some-image.jpg" alt="" /></li>’)
.anythingSlider(); // update the slider

Getting current slide:
$(‘#slider1’).data(‘AnythingSlider’).currentPage; // returns page #

Setting current slide. External link example:
<a href=“#” id=“slide-jump”>Slide 4</a>
$(“#slide-jump”).click(function(){
$(‘#slider2’).anythingSlider(4);
});

External Slideshow Control
$(‘#slider1’).data(‘AnythingSlider’).startStop(true);  // start the slideshow
$(‘#slider2’).data(‘AnythingSlider’).startStop(false); // stops the slideshow
$(‘#slider1’).data(‘AnythingSlider’).goForward(); // go forward one slide
$(‘#slider1’).data(‘AnythingSlider’).goBack(); // go back one slide

Extending – Event Hooks (callback functions)
Note: Changed bind function returned arguments to make more straightforward values available, see callback arguments below.

  • before_initialize (onBeforeInitialize) – triggered right after creating the anythingSlider object. Read note.
  • initialized (onInitialized) – triggered after creating the anythingSlider object.
  • slideshow_start (onShowStart) – slideshow started.
  • slideshow_stop (onShowStop) – slideshow stopped.
  • slideshow_paused (onShowPause) – slideshow paused.
  • slideshow_unpaused (onShowUnpause) – slideshow unpaused – may not trigger properly or match a pause event if user clicks play/stop button.
  • slide_init (onSlideInit) – triggered when panel slide is initialized (before controls animate).
  • slide_begin (onSlideBegin) – triggered before panel slide animation.
  • slide_complete (onSlideComplete) – triggered after panel slide animation.

Please note that at when the onBeforeInitialize event triggers/callback is called, almost nothing has been set:

  1. The anythingSlider object has been attached to the ul.
  2. The class anythingBase was added to the ul.
  3. The ul was wrapped in two divs (div.anythingSlider div.anythingWindow).

That’s it! If you want to use some anythingSlider functionalities, you probably want to wait for the initialization to be completed (and register to the event initialized or use the onInitialized option).

Binding to Events and using Callbacks:
You can bind to any of the custom event triggers as follows (see this page source for another example):

$('#slider1').bind('slide_complete', function(e, slider){
 $('#status').text( 'Now on page #' + slider.currentPage );
 // Do something else
});
$('.anythingSlider').bind('slideshow_start slideshow_stop', function(e, slider){
 var msg = (e.type == "slideshow_start") ? 'Someone started the #^&%$! slideshow!' : 'Whew, thanks for stopping the slideshow';
 $('#status').text( msg );
});

or use one of the callback functions:

$('#slider').anythingSlider({
 onSlideComplete : function(slider){
  alert('Welcome to Slide #' + slider.currentPage);
 }
})

Callback Arguments ( examples are if you use “slider” in the callback function, e.g. function(slider){…}, or in the trigger function, e.g. function(e, slider){…} )

Callback Argument – Description

  • slider.$currentPage – jQuery object of the Target page – not the same page as “slider.currentPage”.
  • slider.$lastPage – jQuery object of the previous page – same page as “slider.currentPage” until “slide_complete” is called.
  • slider.currentPage – Currently displayed page/slide number. Updated when the animation completes.
  • slider.pages – Number of pages contained in the slider.
  • slider.playing – Is true if the slideshow is currently playing (is false when slideshow is paused, but true while youtube video is playing).
  • slider.hovered – Is true if the slider is currently being hovered.
  • slider.options.{name} – Access any of the options (e.g. slider.options.theme). Trying to set the options this way may break the slider.

Formatting Navigation Text
To use the navigationFormatter option, you must have a function that accepts two parameters, and returns a string of HTML text.

  • index = integer index (1 based);
  • panel = jQuery wrapped LI item this tab references
  • Function must return a string of HTML/Text
  • Here is a sample formatter (view index.html page source for another example):
    $(‘#slider’).anythingSlider({
    navigationFormatter : function(index, panel){
    return " Panel #" + index; // This would have each tab with the text ‘Panel #X’ where X = index
    }
    })

Changelog

Version 1.5.1

  • Added enableKeyboard option which will allow you to disable keyboard navigation controls. Added because if you have a slideshow with no clickable controls, using the keyboard will stop the slideshow and there is no way to start it back up.
  • Added enableNavigation option which, when false, will allow visible navigation links to be unclickable. You’ll have to change the CSS to stop the hover effect.
  • Added enablePlay option which, when false, will allow a visible play/stop button to be unclickable. You’ll have to change the CSS to stop the hover effect.
  • Fixed a problem with clicking control links inside a slider (links that take the slider to other panels). This also required that all links in the cloned panels are modified (changed into spans) – this will mess up any FX you add to these links but only in the first and last panels.
  • Added the following changes that Midu (Stefano B) made in his branch. Thanks for the great mods! I would have just merged your changes into the core, but I still suck at using git LOL :P
  • Added appendControlsTo which allows you to attach the slider controls (navigation tabs & play/stop button) to another object on the page. This wasn’t throughly tested, but I know you’ll need to include custom CSS to style these links outside the slider.
  • Added event hook & callback before_initialize (onBeforeInitialize) which is triggered immediately after the slider is initialized, see the note above for more details.
  • Added event hook & callback initialized (onInitialized) which is triggered after the AnythingSlider has completed its setup.
  • Optimized how callbacks functions are called – you shouldn’t notice a difference.

Version 1.5

  • Modified core to allow updating the AnythingSlider content (change the number of slides).

Version 1.4.8

  • Added an optional extension "AnythingSlider FX" to add animation effects to each panel.
  • Added an AnythingSlider FX demo page with examples, code, and multiple methods to achieve the same effects. Thanks to Paal Joachim for input on which demos were needed.
  • Added activePage class to the visible slider; but it is not updated until just before the slide_complete event.
  • Fixed a bug where setting buildArrows to false and toggleArrows to true would cause errors.

Version 1.4.7

  • Added jQuery Objects for $currentPage and $lastPage which are accessible to the bind & callback functions for easy access to the pages. Added these callback arguments and more detail to the information above.
  • Improved the hash tag code so it will now work with multiple AnythingSliders on the page. The hash tag will still only update when clicking on the navigation links and not the navigation arrows.

Version 1.4.6

  • SWFObject script (swfobject.js) is now a required dependency to make YouTube videos pause when not in view & resume play when in view. This was added so IE will also have this functionality.
  • Commented out previous code which added the above YouTube functionality to non-IE browsers. Will consider completely removing it if users are okay with the SWFObject script dependency.

Version 1.4.5

  • Added Curtis Scott’s Portfolio theme from his site. Thanks for sharing! – don’t use the control toggle option as it messes up the page layout.
  • Fixed the flickering problem that was occuring when the slider moved from the last slide to the first.

Version 1.4.4

  • Added CSS to fix a problem with CSS3 transitions occurring during the animation. Added noTransitions class to the arrows, navigation and slider.
  • Added callback functions: onShowStart, onShowStop, onShowPause, onShowUnpause, onSlideInit, onSlideBegin & onSlideComplete.
  • Added instructions on callback argument useage as values and access to internal functions.
  • Changed triggered event callback argument to make using them easier – see the Event Hooks section above.

Version 1.4.3

  • Added options to modify interactivity: clickArrows, clickControls & clickSlideshow.
  • Added custom events – slideshow start, stop, pause & unpause as well as slide begin, start & stop. See the “Extending – Event Hooks” section above for a more detailed description.
  • Updated instructions on how to use custom events.

Version 1.4.2

  • Added addWmodeToObject. When a slider has an embedded object (like a youtube video), the script adds a wmode parameter with the value from this option (“opaque” by default).

Version 1.4.1

  • Added theme option and several themes. Themes can now be added to individual AnythingSliders (although they are based largely on CSS).
  • Added tooltipClass option which adds the assigned class name to the navigation and play/stop button only if the text is hidden (negative text-indent). The tooltip plugin must be added separately.
  • Added toggleArrows option. This option (if true) will slide out (reveal) the arrows while hovering & hide them at other times.
  • Added toggleControls option. This option (if true) will slide down (reveal) the navigation links and play/stop button while hovering & hide them at other times. Adding this option required a new “anythingControls” class that wraps both the navigation links and the play/stop button.

Version 1.4

  • Added maxOverallWidth option. This sets the max width (in pixels) of all combined sliders (side-to-side) due to problems with Opera.
  • Added new classes to the base UL (“anythingBase”) and its immediate children LIs (“panels”) to reduce and clarify the CSS.
  • Added hover class to arrows and start/stop button to indicate the link has focus (while tabbing through the page)
  • Fixed flickering problem completely :P – numerous changes made to script & CSS.
  • Bumped version to 1.4 because of significant differences from version 1.3.

Version 1.3.7

  • Added startPanel option.
  • Added playRtl option to reverse the play direction.
  • Added back stopAtEnd option (not should how it was removed from the options).
  • Added resumeOnVideoEnd option to prevent an active slideshow from pausing a video.
  • Changed location of reverse reference from the wrapping div (“anythingSlider” class) to the original ul (“silder1” id in the first example) – updated instructions.
  • Fixed height/width options to accept strings (e.g. “400px” instead of a number, it may not work properly if values are other than the numnber of pixels).
  • Fixed setting to accept strings (e.g. $(slider).anythingSlider(" 1 ")) as well as numbers.
  • Fixed problem with objects (youtube videos) flickering in Firefox by setting resizeContent to false.
  • Fixed problem that occurs when using an incorrect easing function name (submitted ticket: http://dev.jquery.com/ticket/7064 )
  • Reorganized, cleaned up the code and updated the demos & instructions.

Version 1.3.6

  • Fixed minor bug with links to specific slides and updated example to reflect changes and be less confusing
  • Tweaked start/stop button css to be more maleable

Version 1.3.5

  • Added resizePanel option – does not support percentage sizing.
    • When true, it will resize all panels & solitary content to the size settings (CSS or the script options).
    • When false, the AnythingSlider wrapper will resize to fit the panel (set inline or in the CSS for each panel).
  • Fixed keyboard navigation to work with multiple AnythingSliders on a page.
  • Added tabbed navigation. Both the links within panels and the thumbnail navigation will activate it.

Version 1.3.4

  • Added keyboard navigation.
  • Embeded objects will now resize to fit the panel.
  • YouTube videos will pause the video when it is not in view and play (if already started) if it is in view.
    Note: this feature only works in non-IE browsers and when the files are hosted on a webserver as the flash player restricts calls between local files and the internet.
  • Modified code according to JSLint & added minified version.

Version 1.3.3

  • Previous / Next arrows are now optional
  • Clicking start button immediately begins transition instead of waiting for the delay

Version 1.3.2

  • Greatly refactored CSS for a more fluid resizing behavior
  • Dimensions can be passed via javascript or modified at the top of the css file
  • Merged all Github forks
  • Wrapper DIVs (<div class="anythingSlider"><div class="wrapper">) no longer required in html. Divs are generated in jquery
  • Improved CSS scope and classes, Javascript degredation behaves differently however
  • Hash URLS now work for multiple panels

Version 1.3

  • Accessibility improvements by Matt Lawson
  • Some generic JavaScript/HTML/CSS code cleaning
  • Move to GitHub entirely
  • Ensures unique panel ID’s
  • Removes navigation if there is only one panel
  • Added option to stop on the last page when autoPlay is set to true

Version 1.2

  • Bug Fix: When autoPlay was set to false, any interaction with the control would cause a javascript error.

Version 1.1

  • Changed default easing to “swing” so didn’t depend on any other plugins
  • Removed extra junk (other plugins used for design, etc)
  • Added Pause on Hover option
  • Added options for passing in HTML for the start and stop button
  • Added option to use custom function for formatting the titles of the navigation
  • Added public interface for linking directly to certain slides

Version 1.0

  • First version