README.md

Carousel

A Ruby on Rails engine that adds an image carousel to your application.

Author	Tim Morgan
Version	1.0 (Apr 20, 2012)
License	Released under the MIT license. Portions released under a different license (see Sub-Licenses below).

About

This gem adds assets to your Rails application allowing you to display a simple but effective carousel of images. The carousel can be displayed horizontally or vertically. It uses Ajax to incrementally load images rather than loading them all at once.

Requirements

• Rails 3.1: This gem uses Rails engines.
• jQuery: The carousel and lightbox is rendered and managed using jQuery.
• Sass: The carousel layout is written using SCSS.

Optional

• Paperclip: The carousel includes native support for Paperclip, but does not depend on it.

Installation

To use this gem, add to your Gemfile:

gem 'carousel'

To your application.css file (or some other CSS manifest file), add:

/*
 *= require jquery.lightbox-0.5
 *= require carousel
 */

To your application.js file (or some other JavaScript manifest file), add:

//= require jquery.lightbox-0.5
//= require carousel

You may also need to add the following if it is not already there:

//= require jquery

Usage

The carousel loads images using an Ajax action. You will need to write such an action that returns JSON information about the images the carousel should load in an "infinite scrolling" manner. The JSON should have the format shown in the following example:

[
    {
        "caption": "Parents' house from the air",
        "id": 26,
        "preview_url": "http://s3.amazonaws.com/flightseein/photographs/26/images/carousel-ac52ff7c1f101e9fe86b1bbe0c7e8dab.png",
        "url": "http://s3.amazonaws.com/flightseein/photographs/26/images/original-ac52ff7c1f101e9fe86b1bbe0c7e8dab.jpeg"
    },
    {
        "caption": "Mt. Diablo",
        "id": 27,
        "preview_url": "http://s3.amazonaws.com/flightseein/photographs/27/images/carousel-9bcf168a861a840be7cdd2914bb3e539.png",
        "url": "http://s3.amazonaws.com/flightseein/photographs/27/images/original-9bcf168a861a840be7cdd2914bb3e539.jpeg"
    },
    {
        "caption": "UC Berkeley",
        "id": 28,
        "preview_url": "http://s3.amazonaws.com/flightseein/photographs/28/images/carousel-663d4602da82c6b2bd0f88cd5be2da7d.png",
        "url": "http://s3.amazonaws.com/flightseein/photographs/28/images/original-663d4602da82c6b2bd0f88cd5be2da7d.jpeg"
    }
]

All fields are required except for caption.

Your controller should also correctly manage the infinite-scrolling feature by accepting a parameter last_record. This parameter will be the ID of the last photo previously loaded. You should load the next group of photos from that ID. What you define "ID" as, and how you order the photos, and how many photos you include in a batch, are all up to you.

In your view, instantiate a Carousel object like so:

$('#carousel-container').carousel("<%= photographs_url %>", 'horizontal');

where $('#carousel-container') is the jQuery-wrapped DOM element to contain the carousel, and photographs_url is the URL endpoint for the controller you wrote above. The second parameter can be either horizontal or vertical and describes the orientation of your carousel.

Sub-Licenses

Portions of this code were written by Leandro Vieira Pinho. These portions are distributed under the CCAttribution-Share-Alike 2.5 (Brazil) license.