Touch Carousel

An any-element, flexible jQuery Carousel plugin with touch/swipe features.

Usage

Any element can have the .touchCarousel() method called on it, with a variety of optional settings being set. The method call and full list of settings can be seen below.

Implementation

---

There are a few starting requirements for your HTML structure:

• Your carousel container should have a class of .tc-tabs
• Each item within the carousel container should be given a class of .tc-tab

Basic

The most basic format of the carousel will turn a list into a carousel; for example:

<ul class='tc-tabs'>
  <li class='tc-tab'>
    <img src='http://dummyimage.com/300x150' alt='alt' />
  </li>
  <li class='tc-tab'>
    <img src='http://dummyimage.com/300x150' alt='alt' />
  </li>
</ul>

Larger images

Any <img> elements can be given a data-carousel attribute to change the image src attribute inside the item's hero version; for example:

<ul class='tc-tabs'>

  <li class='tc-tab'>
    <img src='http://dummyimage.com/300x150' data-carousel='http://dummyimage.com/1000x600' alt='alt' />
  </li>

  <li class='tc-tab'>
    <img src='http://dummyimage.com/300x150' data-carousel='http://dummyimage.com/1000x600' alt='alt' />
  </li>

</ul>

Linking Images

Basic linkage can be applied by wrapping the <img> in an <a class='tc-tab'>

<ul class='tc-tabs'>

  <li class='tc-tab'>
    <a href='#'>
      <img src='http://dummyimage.com/300x150' alt='alt' />
    </a>
  </li>

  <li class='tc-tab'>
    <a href='#'>
      <img src='http://dummyimage.com/300x150' alt='alt' />
    </a>
  </li>

</ul>

Mixing elements

.tc-tab elements don't have to just be <li> elements inside a <ul>! You can use any elements, given they keep the same classes; for example:

<div class='tc-tabs'>

  <img class='tc-tab' src='http://dummyimage.com/300x150' alt='alt' width='150' height='100' />

  <div class='tc-tab'>
    This is the second item
  </div>
  
  <a href='#' class='tc-tab'>
    <h2>Some title</h2>
    <p>Some text</p>
  </a>

</div>

The '-only' class

You can add custom elements anywhere within your .tc-tab to create a more custom structure. For example, in the following carousel an extra datetime is being shown only in the item's tabular form and is showing a header only in the hero form:

<div class='tc-tabs'>
  
  <article class='tc-tab'>
    <img src='http://dummyimage.com/300x150' data-carousel='http://dummyimage.com/1000x600' alt='alt' width='150' height='100' />
    <h2 class='tc-hero-only'>This is a title!</h2>
    <span class='date-published tc-tab-only'>Weds 8 August 2012. Last updated: 1.16AM</span>
  </article>

</div>

$.touchCarousel()

---

Options

slideDuration

How long an item is shown before going to the next item (milliseconds)
Default: 4000

transitionDuration

The length of sliding transition (milliseconds)
Default: 250

easing

Currently 'swing' or 'linear'
Default: 'swing'

width

Width in pixels or '100%' for flexible
Default: '100%'

showTimers

Whether the 'filling' timer bars should be displayed
Default: true

showTabs

Whether the tabs section should be displayed. Set to false if the carousel hero area is the only region to be shown.
Default: true

autoResizeTabs

Whether tabs should gain percentage widths of the tabs section (i.e. 'fill' the region)
Default: true

hoverActive

Set to false to disable all hover pausing, or use the below options of (heroHoverPause & tabsHoverPause) Default: true

heroHoverPause

Should the carousel pause when hovering the hero?
Default: true

tabsHoverPause

Should hovering the tabs change the carousel?
Default: true

Methods

.goToSlide( slideNumber )

The carousel will move onto the given slideNumber and proceed from there.

.nextSlide()

The carousel will move onto the next slide and proceed from there. If at the end of the carousel, it will return to the beginning.

.prevSlide()

The carousel will move onto the previous slide and proceed from there. If at the first slide, it will go to the last slide.

.resetCarousel()

This will restart the slider and reset all settings.

Update Log

Essential

• Transition-duration of .reel-timer to take main timer setting
• Touch timers to fix

Features

• Option extension for other easing types
• LR Pagination
• Dotted Pagination
• LR keyboard
• Hover pause w/button
• Pausing for tabs/hero/both can be set in options
• [?] Spacebar pause - Need to check whether this is more important than page scroll (option maybe?)
• Transitions (Wipe)
• Transitions (Fade)
• Scroll extra tabs
• Default tab % width setting
• Classes for Tab/Hero-only elements
• Conversion to plugin
• Extend plugin functions
• Header works off class, not tag
• Remove necessity for <a> tag within tabs
• Extend for images-only
• Extend for images in links
• Extend for complex structures

Project Files

The below table summarises the contents of each file throughout the structure of TouchCarousel:

/CSS
custom.css	Where custom stylings are kept. You should replace these with your styles, or implement them into your own site's stylesheets.
styles.css	Generic styling for the TouchCarousel
/JS
touchCarousel.js	This is the main jQuery file which runs carousel. It should be included as a script tag after your jQuery include.
touchCarousel.min.js	A minified version for use on live sites.
HTML These are a compliled example HTML files.
imageOnly.html	A very basic example of how a list of images can become a carousel.
imageLinks.html	An example with basic carousel image linking.
index.html	A more complex example.

Composite DOM Structures

Initial

The source-file HTML DOM structure of the carousel should be as follows:

+---.tc-tabs------------------------+
|  .tc-tab(s)                       |
+-----------------------------------+

Final

The final DOM structure of the carousel will be as follows:

+--.tc-root-------------------------------+
|                                         |
|  +---.tc-hero-wrapper----------------+  |
|  |  +----.tc-hero-reel------------+  |  |
|  |  | .tc-hero-item(s)            |  |  |
|  |  +-----------------------------+  |  |
|  +-----------------------------------+  |
|                                         |
|  +---.tc-tabs------------------------+  |
|  |  .tc-tab(s)                       |  |
|  +-----------------------------------+  |
|                                         |
+-----------------------------------------+