Skip to content

Latest commit

 

History

History
343 lines (291 loc) · 11.4 KB

README.md

File metadata and controls

343 lines (291 loc) · 11.4 KB
Raw

iosSlider

iosSlider is a jQuery plugin which turns any wide element into a touch enabled horizontal slider.

Features

    <li>Hardware accelerated using CSS3 for supported iOS, Android and WebKit browsers.</li>

<li>Responsive support to work with the most dynamic desktop and mobile sites.</li>

<li>Tons of API callbacks to get the perfect slider feel for your web application.</li>

<li>FF/Safari/Chrome/IE7+ Full modern browser support for desktop.</li>

<li>Infinitely looping Loop through your slides endlessly in both directions.</li>

<li>Auto-sliding Set your slider to automatically transition and pause on hover.</li>

Tutorial

Getting Ready

To get started, you will need to download the iosSlider script. Click here to download the latest version. This download contains the iosSlider script, the jQuery library, and source files for the examples shown above.

Include the Necessary JavaScript Files

The jQuery library and iosSlider Plugin scripts must be included in the HTML header of the web page. The jQuery library must be included first for the iosSlider plugin to function.

<!-- jQuery library -->
<script type = 'text/javascript' src = '/iosSlider/jquery-1.6.1.min.js'></script>

<!-- iosSlider plugin -->
<script type = 'text/javascript' src = '/iosSlider/jquery.iosslider.js'></script>

Add the HTML

Add the iosSlider HTML code within the body of the web page. The HTML can contain as little as one slide element, but if you want to leverage the snapToChildren setting, you will need to use multiple slides.

<!-- slider container -->
<div class = 'iosSlider'>
	
	<!-- slider -->
	<div class = 'slider'>
	
		<!-- slides -->
		<div class = 'slide'>...</div>
		<div class = 'slide'>...</div>
		<div class = 'slide'>...</div>

	</div>

</div>

Add the CSS

Place the CSS in your stylesheet. The required CSS attributes are included to guarantee optimal performance. Feel free to apply as many other CSS attributes as you want. To see some real-world examples of this, check the examples folder of the iosSlider download.

/* slider container */
.iosSlider {
	/* required */
	position: relative;
	top: 0;
	left: 0;
	overflow: hidden;
	
	/* optional */
	width: 630px;
	height: 214px;
}

/* slider */
.iosSlider .slider {
	/* required */
	width: 100%;
	height: 100%;
}

/* slide */
.iosSlider .slider .slide {
	/* required */
	float: left;

	/* optional */
	width: 630px;
	height: 214px;
}

Add the JavaScript

Add the code below to your JavaScript file. The following code uses the jQuery selector to fire the iosSlider jQuery plugin. If you are unfamiliar with jQuery, here is a tutorial to get you started.

$(document).ready(function() {

	/* basic - default settings */
	$('.iosSlider').iosSlider();
	
	/* some custom settings */
	$('.iosSlider').iosSlider({
		snapToChildren: true,
		scrollbar: true,
		scrollbarHide: false,
		desktopClickDrag: true,
		scrollbarLocation: 'bottom',
		scrollbarHeight: '6px',
		scrollbarBackground: 'url(_img/some-img.png) repeat 0 0',
		scrollbarBorder: '1px solid #000',
		scrollbarMargin: '0 30px 16px 30px',
		scrollbarOpacity: '0.75',
		onSlideChange: changeSlideIdentifier
	});

});

Settings & Options

You can pass along any of the following key/value pairs listed below to the iosSlider() function or modify them at the bottom of the the iosSlider() JavaScript file directly.

Key Value Description
elasticPullResistance 0.6 (decimal, 0.0 - 1.0) The elastic resistance when pulling on the slider edge.
frictionCoefficient 0.92 (decimal, 0.0 - 1.0) The friction coefficient applied to the momentum on touch release affecting the rate of deceleration.
elasticFrictionCoefficient 0.8 (decimal, 0.0 - 1.0) Additonal friction coefficient applied when momentum slides outside the bounds of the slider.
snapFrictionCoefficient 0.92 (decimal, 0.0 - 1.0) Friction applied to the slider when snapping to an element.
snapToChildren false (boolean) Slider will slide to the closest child element on touch release.
startAtSlide 1 (integer) Current slide when slider is initially loaded.
scrollbar false (boolean) Show or hide the scrollbar.
scrollbarHide true (boolean) Show or hide the scrollbar when it is idle.
scrollbarLocation 'top' (string, 'bottom' or 'top') Location that the scrollbar will appear.
scrollbarContainer '' (string) A jQuery selection (ex. $('#scrollbarContainer') ), the scrollbar will be loaded and contained by this selection. The scrollbar will width will be defined by this container.
scrollbarOpacity 0.4 (decimal) The css opacity of the scrollbar when visible.
scrollbarHeight '4px' (string) The css height in 'px' of the scrollbar.
scrollbarBorder 'none' (string) The css border of the scrollbar.
scrollbarMargin '5px' (string) The css margin of the scrollbar.
scrollbarBackground 'none' (string) The css background of the scrollbar.
scrollbarBorderRadius '100px' (string) The css border-radius of the scrollbar.
scrollbarShadow 'none' (string) The css box-shadow of the scrollbar.
desktopClickDrag false (boolean) Desktop click and drag fallback for the desktop slider.
responsiveSlideContainer true (boolean) Width of slide container becomes responsive to the width/height of its parent element. Slide container dynamically collapse to the width/height of the parent element when wider/taller.
responsiveSlides true (boolean) Width of slides becomes responsive to the width/height of its parent element. Slides dynamically collapse to the width/height of the parent element of the slider when wider/taller.
navSlideSelector null (string) A jQuery selection (ex. $('.navButtons .button') ), each element returned by the selector will activate navigation to each slide respectively. ie. element 0 when clicked (or touched) will animate to the first slide and so on.
navPrevSelector null (string) A jQuery selection (ex. $('#previousSlide') ), the element returned by the selector will navigate to the previous slide when clicked.
navNextSelector null (string) A jQuery selection (ex. $('#nextSlide') ), the element returned by the selector will navigate to the next slide when clicked.
autoSlide false (boolean) Enables automatic cycling through slides.
autoSlideTimer 5000 (integer) the time (in milliseconds) that a slide will wait before automatically navigating to the next slide.
autoSlideTransTimer 750 (integer) the time (in milliseconds) required for all automatic animations to move between slides. See navSlideSelector, navPrevSelector, navNextSelector for details on activating elements for automatic sliding.
autoSlideToggleSelector null (string) A jQuery selection (ex. $('#autoScrollToggle') ), the element returned by the selector will disable/enable automatic scrolling when clicked. Note: Only works when autoSlide is set to 'true'.
infiniteSlider false (boolean) Makes the slider loop in both directions infinitely with no end. When set to true, the option scrollbar is automatically disabled.
onSliderLoaded null (function) Executed when slider has finished loading initially.
Returned parameter: 'args' (array) { settings, sliderContainerObject, sliderObject, currentSlideObject, currentSlideNumber, numberOfSlides }
onSlideStart null (function) Executed when the slider has begun to move.
Returned parameter: 'args' (array) { settings, sliderContainerObject, sliderObject, currentSlideObject, currentSlideNumber, numberOfSlides }
onSlideChange null (function) Executed when the slider has entered the range of a new slide.
Returned parameter: 'args' (array) { settings, sliderContainerObject, sliderObject, currentSlideObject, currentSlideNumber, numberOfSlides }
onSlideComplete null (function) Executed when the slider has come to a stop on a new slide.
Returned parameter: 'args' (array) { settings, sliderContainerObject, sliderObject, currentSlideObject, currentSlideNumber, numberOfSlides }

Public Methods

<tbody>
	<tr>
		<td>$('div').iosSlider('destroy');</td>
		<td>Destroys the selected slider.<br /><em>Optional parameter: 'clearStyle' (boolean, default: true) when iosSlider is destroyed, all inline style applied to the slider will be removed.</em></td>
	</tr>
	
	<tr>
		<td>$('div').iosSlider('goToSlide', slideNum);</td>
		<td>Moves to the selected slide.<br /><em>Required parameter: 'slideNumber' (integer, default: null)</em></td>
	</tr>
</tbody>
Method Description

License

iosSlider is licensed under the Creative Commons – Attribution-NonCommercial 3.0 License.

Personal or non-profit

You may use iosSlider free for personal or non-profit purposes, without restriction. Attribution is not required but always appreciated.

Commercial

For commercial projects, you must purchase a license. You may download and play with the script before deciding to fully implement it in your project. Making sure you are satisfied, and knowing iosSlider is the right script for your project is paramount.

You are not permitted to make the resources found on iosscripts.com available for distribution elsewhere without prior consent. If you would like to feature iosSlider on your site, please do not link directly to the resource zip files. Please link to this page (http://iosscripts.com/iosslider) on iosscripts.com where users can find the download.