+ + + + +

jQuery Slides

+
• +
  + Example 1: Default +
  +
  +

  +$(".myElement").slides();
  +

  +
  +
+
• +
  + Example 2: Vertical, Click +
  +
  +

  +$(".myElement").slides({
  +	vertical:true,
  +	events: {
  +		activate:"click",
  +		deactivate:"click"
  +	}
  +});
  +

  +
  +
+
• +
  + Example 3: Limits +
  +
  +

  +$(".myElement").slides({
  +	limits: {
  +		min:30
  +	}
  +});
  +

  +
  +
+
• +
  + Example 4: Limits (advanced) +
  +
  +

  +$(".myElement").slides({
  +	limits: {
  +		min:10,
  +		0: {
  +			min:180
  +		},
  +		2: {
  +			min:180
  +		},
  +		4: {
  +			min:180
  +		},
  +		"-1": {
  +			min:180
  +		}
  +	}
  +});
  +

  +
  +
+
• +
  + Example 5: Limits, stayOpen, keyEvents +
  +
  +

  +$(".myElement").slides({
  +	active:0,
  +	stayOpen: true,
  +	keyEvents:true,
  +	limits: {
  +		min:400
  +	}
  +});
  +

  +
  +
+
• +
  + Example 6: Navigation Left (click) +
  +
  +

  +$(".myElement").slides({
  +	stayOpen: true,
  +	events: {
  +		activate:"click",
  +		deactivate:"click"
  +	},
  +	limits: {
  +		0: {
  +			min:30,
  +			max:30
  +		}
  +	}
  +});
  +

  +
  +
+
• + + Example 7: Resizable + +
+
• + + Example 8: Expandable Grid + +
+ +
• + + City University New York - Graduate Center + +
+
• + + The Book in Motion - Cooper Union + +

+
• About
+
• General
+
• Methods
+
• Options
+
• Callbacks
+
• License
+
• Download
+
• Author
+
• +
  + + + A lot of time and work went into this plugin! So when using it you might want consider to:
  + + Cheers! ;) +
  +
+

About

jQuery Slides plugin

A pretty flexible and highly customizable slideshow/accordion plugin for jQuery.

This plugin is inspired by the jQuery UI Accordion and Kwicks for Mootools / Kwicks for jQuery.

The main reason to start to develop this plugin where a certain set of specifications and customizaitions I needed for The Book in Motion website i've been developing, that none of the above where quite offering.

So here are these specifications and features that this plugin provides - plus some others (I kinda got into it):

+
• The Slideshow is resizable without javascript -> so no jittering even when using a fullscreen slideshow.
+
• There are NO gaps and spaces between the slides during the animation.
+
• Limits (max-/min-width) can be set for all slides but also for one single slide (or two).
+
• The plugin doesn't require a predefined markup like an unordered list or h3 headers and divs.. it just takes what it gets.
+
• You can mess around with the css on runtime and the plugin still finds the proper position for each slide when its next event is triggered.
+
• Lots of options to turn things on and off..
+
• And a lots of callbacks and events that allow to customize, extend and manipulate the plugins behaviour to make it really flexible. Also its easy to add new callbacks where they're needed.
+
• Fully browser compatible: IE 7.0+ (haven't tested on IE6 - screw it!), Firefox 3+, Safari 3.1+, Opera 9.6+ and Google Chrome.
+

So as said above, this plugin has been developed for The Book in Motion website and this website is probably the best way to see what this plugin is capable of.

Also it's used on the frontpage of the City University of New York - Graduate Center as well as image gallery on some subpages.

What follows here is FINALLY the documentation of the plugin. It's been a lot of work that went into it and I'm very happy to finally make it available for everybody.

I'm happy for any feedback, suggestions and bug reports (well not happy, but grateful in the last case :) )

And when you come to use the plugin: SHOW ME! I would love to see what you're doing with it!

General

To start off, get the newest version of the jQuery Slides plugin (downloads) move it into your project folder.

Include the file into your HTML and you're ready to go:

+jQuery(document).ready(function(){
+	$(".myElement").slides();
+});
+

All child elements of .myElement element will be turned into slides.

So the code above will turn each one of these:

+<ul class="myElement">
+	<li></li>
+	<li></li>
+</ul>
+

+<div class="myElement">
+	<div></div>
+	<div></div>
+</div>
+

+<div class="myElement">
+	<a></a>
+	<div></div>
+</div>
+

Into a slideshow that's markup will look (in the first case: <ul>) like this:

+<ul class="myElement greenishSlides gsHorizontal/gsVertical">
+	<li class="gsSlide [gsActive] [gsPositionActive] [top/left] [bottom/right] [gsDeactivating]"></li>
+	<li class="gsSlide [gsActive] [gsPositionActive] [top/left] [bottom/right] [gsDeactivating]"></li>
+</ul>
+

Methods

+$(".myElement").slides([Object options]);               
+

Initialize / Update Options

Initialize the plugin on a set of HTML Elements.

Optional you can pass an object with options (see below) to the function.

Also you can change options with this at any time after initialisation.

+"activate"			$(".mySlide",".myElement").slides("activate");           
+

Activate Slide

Activates the slide this method is called on.

+"deactivate"			$(".mySlide", ".myElement").slides("deactivate");            
+

Deactivate Slide

Deactivates the slide this method is called on.

+"update"			$(".myElement").slides("update");            
+

Update Slide Positions.

Updates the position of all slides.

Needs to be called adding a new slide or after a resize happened without the resize option enabled.

+"next"				$(".myElement").slides("next", [Integer goFromSlideId]);       
+

Activates Next Slide.

Activates the next slide to the left/bottom of the active slide. + Optionaly you can pass the index of a slide to take its next.

+"prev"				$(".myElement").slides("prev", [Integer goFromSlideId]);
+

Activates Previous Slide.

Activates the next slide to the right/top of the active slide. + Optionaly you can pass the index of a slide to take its previous.

+"bindCallback"			$(".myElement").slides("bindCallback", Function);         
+

Bind a Callback/Event

Registers or binds a callback function to a certain event. (see below).

+"clearCache"			$(".myElement").slides("clearCache");            
+

Clear Cache

Removes all cached informations. (Caching can be enabled by option).

Options

Options can be set or changed by passing an object to the slides() function. This can be done on initialisation or afterwards to change any value (for example limits).

Here are all the possibile options (set to their default values):

+$(".myElement").slides({
+	vertical:false,
+	resizable:false,
+	active:false,
+	transitionSpeed: 400,
+	easing:"swing",
+	events: {
+		activate:"mouseover",
+		deactivate:"mouseout"
+	},
+	handle:".gsSlide",
+	stayOpen: false,
+	keyEvents:false,
+	circle : false,
+	classes:{
+		active:"gsAactive",
+		vertical:"gsVertical",
+		horizontal:"gsHorizontal",
+		slide:"gsSlide",
+		deactivating:"gsDeactivating",
+		positionActive:"gsPositionActive"
+	},
+	cache:false,
+	limits : {},
+	callbacks : {}
+});
+

Option Details

+vertical:                       Boolean                                 Default: false
+

Defines the orientation of the Slides element.

+resizable:                      Boolean                                 Default: false
+

Defines if the Slides element can be resized on runtime.

If true slides on the left side of the active slide will be positioned differently from the ones on the right, to allow resizing without javascript.

Still if there are limits set to any slide, resizing may need an event handler that will also be set if necessary.

Be aware that this needs some extra calculations and (more important) some DOM changes which will influence the performance so only switch this on if you really need it.

+active:				Boolean                                 Default: false
+				Object  (jQuery Object)             
+				String  (jQuery Selector)               
+				Integer (Slide Index)               
+

Defines the active Slide after initialisation.

+
• false: No Slide (or the first Slide if stayOpen:true) is active.
+ +
• true: The first Slide is active.
+ +
• 0 : The first Slide is active.
+ +
• -1 : The last Slide is active.
+

+transitionSpeed:                Integer (ms)                            Default: 400
+

Defines the duration of the animations in milliseconds.

+easing:                         String                                  Default: "swing"
+

Defines what kind of easing algorythem should be used in the animations. Works with the jQuery easing plugin.

+events: {                                               
+	activate:		String                                  Default: "click"
+	deactivate:		String                                  Default: "click"
+}
+

Lets you define what browser events will trigger the activation/deactivation events of a slide.

+handle:                         String  (jQuery Selector)               Default: ".gSSlide"
+				Object  (jQuery Object)             
+

Defines on which element the activation/deactivation events are bound.

+stayOpen:                       Boolean                                 Default: false
+

If true the there is always one active slide. No deactivation is possible so none will be triggered.

+keyEvents:                      Boolean                                 Default: false
+

If true the arrow keys can be used to move from one slide to the next.

+circle:                         Boolean                                 Default: false
+

Defines if after the last slide follows the first when the "next" event is triggered.

+classes: {                                              
+	active:			String                                  Default: "gsActive"
+	vertical:		String                                  Default: "gsVertical"
+	horizontal:		String                                  Default: "gsHorizontal"
+	slide:			String                                  Default: "gsSlide"
+	deactivating:		String                                  Default: "gsDeactivating"
+	positionActive:		String                                  Default: "gsPositionActive"
+}
+

Lets you customize the css classes that are set by the plugin.

+cache:                          Boolean                                 Default: false
+

Enables the caching functionality. Caches certain valus and calucalation. Use this if there are no runtime changes at all (no resizing, adding of slides etc.)

To be honest I kind of expected more of a speed improvement from this than it actually does.. so its usefulness is questionable.. but it does definitely no harm so why not use it.

+limits: {                                                               Default: {}
+	min:			Integer (px)
+				String
+	max:			Integer (px)
+				String
+	0: {
+		min:		Integer (px)
+				String
+		max:		Integer (px)
+				String
+	}                           
+	"-1": {
+		min:		Integer (px)
+				String
+		max:		Integer (px)
+				String
+	}   
+}
+

This allows you to set a minimum height/width and a maximum height/width (in px) for all slides or a single slide.

+
• limits.min: Sets a min width/height for every slide. No slide can be smaller than i.e. 20px
+ +
• limits[0].min: Sets a min width/height for the first slide.
+ +
• limits[-1].min: Sets a min width/height for the last slide.
+

All min/max definitions are optional and can be combined in any ways possible.

Limits can also be set by css with min-width, max-width, min-height, max-height. Css limits always override limits that where set in the options. Also, limits for one single slide override the limits set for all slides.

min-width > limits[0].min > limits.min

Because min-width doesn't have a default like none, 0px is handled as undefined and limits[0].min will be used instead. To define "min-width:0px" use 0% which will then override limits[0].min.

+callbacks: {								Default: {}
+	"callbackName":		Function(callback function)
+				Object  (multiple callback functions)
+				Array   (multiple callback functions)   
+}   
+

Allows to register callback functions during initialisation.

To learn more about the available callbacks look at the Callbacks/Events chapter below.

Callbacks/Events

During the runtime of the plugin a bunch of callbacks are fired.

Callbacks can be registered by adding the functions to the options object or by calling the "bindCallback" method.

Every callback function receives the data object as first parameter while the following parameters can change.

By returning false in the callback the plugin cancels the current event and stopps its action.

This is a list of all the callbacks that are available at the moment (to find them in the code search for #CALLBACK):

+"preInit"                       function(data, opts)		Context: $(".myElement")
+

Called on initialisation before anything else is done.

Because the new options are not yet integrated into the data object, they are passed as second parameter.

+"init"                          function(data)                  Context: $(".myElement")
+

Called on initialisation after all the classes and styles are set.

+"postInit"                      function(data)                  Context: $(".myElement")
+

Called after the initialisation is complete.

+"activateEvent"                 function(data)                  Context: Slide Handle
+

Called every time the activation event is triggered.

+"deactivateEvent"               function(data)                  Context: Slide Handle
+

Called every time the deactivation event is triggered.

+"preActivate"                   function(data)                  Context: $(".mySlide", ".myElement")
+

Called before a slide is activated.

+"preDeactivate"                 function(data)                  Context: $(".mySlide", ".myElement")
+

Called before a slide is deactivated.

+"preUpdate"                     function(data)                  Context: $(".active", ".myElement")
+

Called before all slides are updated

+"preActivateAnimation"          function(data)                  Context: $(".myElement")
+"preDeactivateAnimation"        function(data)                  Context: $(".myElement")
+"preUpdateAnimation"            function(data)                  Context: $(".myElement")
+

Called after all caculations are done just before the animation starts.

+"postActivate"                  function(data)                  Context: $(".active", ".myElement")
+

Called after a slide is activated.

+"postDeactivate"                function(data)                  Context: Deactivated Slide
+

Called after a slide is deactivated.

+"postUpdate"                    function(data)                  Context: $(".active", ".myElement")
+

Called after all slides are updated

+"step"                          function(data)                  Context: $(".active", ".myElement")
+

Called at every step of the animation function.

The data object contains the current position of everyslide at that moment of the animation.

Also have a look at the step callback of the jQuery animation function.

Add New Callback

If you need a new callback that is missing, feel free to add it in the code! + Just put the following at the place you need the call:

+[context].slides("_triggerCallback","myCallbackName" [,parameterOne, parameterTwo, ...]);
+

Notice that the new callback will come with all the features of the default ones:

+
• The data object will always be passed as the first parameter. (And you can add as many additional parameters as you wish.)
+
• return false will stop the further execution of the acutal event.
+

When you added a new callback, tell me about it! So I can consider adding it to the default callbacks.

License

The MIT license.

Copyright © 2011-2012 Philipp C. Adrian

Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE.

Download

+ You can download this project in either + zip or + tar formats. +

You can also clone the project with Git by running:

$ git clone git://github.com/greenish/slides

Or get the source code on GitHub : greenish/slides

Author

Philipp C. Adrian (greenish), graphic designer from Basel, Switzerland.

+ www.philippadrian.com +