FrameCarousel

A jQuery plugin to create carousels within frames

Responsive

Resizes itself for different screen sizes. Can even remove frame beyond a certain screen size.

Touch Friendly

Highly responsive to touch gestures on smart devices.

GPU Acceleration

Takes advantage of CSS3 3D acceleration so it runs smooth on every device.

Light Weight

Entire library is only 9kb.

Highly Customizable

A good number of customization options to make sure it fits nicely into your project.

Free to Use

Open source and free forever.

Getting Started

It's easy to get started:

  1. Download

    Download latest build here. Copy the folder dist and put it in a public directory of your project. Rename it to frame-carousel

  2. Include

    At minimum, you need these files included in your html page:

    <!-- You can override default styles in your CSS.-->
    <link rel="stylesheet" href="path/to/frame-carousel/jquery.frame-carousel.min.css">
    
    <script type="text/javascript" src="path/to/frame-carousel/jquery.frame-carousel.min.js"></script>
  3. Initializing

    We need an element in your HTML page that will host the carousel. It could be as simple as a div:

    <div class="host-element"></div>

    Now sprinkle some JavaScript:

    $('.host-element').frameCarousel();

    If the plugin is initialized without any parameter, default options will be used. If you want to tweak some setting, use following Options.

Options

Following are available options with default values:

$('.host-element').frameCarousel({
  // Enable/disable debug mode. Debug mode allows you to print
  // debug messages on top of the frame in cases when console.log/alert aren't
  // readily available.
  debug: false,

  // First screen when the plugin intializes. Must be an integer between 0
  // and image_count - 1, where image_count is total number of images you're
  // displaying inside the frame.
  first: 0,

  /*
  * swipeThreshold -- percentage of screen width
  *
  * Determines when to initiate a next transition when user
  * is sliding a screen.
  *
  * For example, a value of 10 says that
  * initiate a move-to-next screen transition, if user has lifted
  * her finger(s) after having dragged current screen towards left by
  * a distance of 10% or more.
  */
  swipeThreshold: 10,

  /**
   * Frame image that you'd like to use in the background.
   * The default value points to a phone frame included within
   * dist/sample directory.
   */
  frame: 'path/to/frame-carousel/sample/frame.png',

  /**
   * Width/height of the frame in pixels you'd like to apply in relation to different
   * screen sizes.
   *
   * If this option isn't specified at all, original dimensions of the frame image
   * will be used for all screen sizes.
   *
   * It takes an array of objects, each specifying frame dimensions in relation to a
   * particular screen width. For a given screen width, the plugin will iterate through
   * the array, and apply dimensions of the first matching object.
   *
   * If width isn't specified, but height is there, width would be calculated
   * using original image's aspect ratio. Same is true when height isn't specified,
   * but width is there. If neither height nor width are specified, original dimensions
   * of the image will be used.
   *
   * If width is set as -1, the frame will be removed for screens which match the criteria.
   */
  frameSize: [{
    width: [calculated at runtime],
    height: [calculated at runtime],
    minScreenWidth: 768,
    maxScreenWidth: 1024
  }],
  
  /**
   * Screen width in pixels. Removes frame and left/right buttons if current screen size
   * is less than or equal to this number.
   */
  collapseThreshold: 450,
  
  /**
   * Marks bounding box within frame image where images are to be rendered.
   * All values are in percentages, so they remain true no matter what pixel size frame ends
   * up with.
   */
  boundingBox: {
    left: '4.3%',
    top: '4.48%',
    width: '91.4%',
    height: '61.1%'
  },

  /**
   * An array of image links to be rendered within frame. Images don't have to adhere
   * to any size (they don't even have to have same size), but it'll help if their
   * aspect ratio is same as aspect ratio of boundingBox.
   */
  images: ['path/to/frame-carousel/sample/1.jpg',
    'path/to/frame-carousel/sample/2.jpg',
    ...
    'path/to/frame-carousel/sample/10.jpg']
});

Functions

// Grab the frameCarousel instance from host element
var frameCarousel = $('.host-element').data('frameCarousel');

// The argument 'options' is optional in all of the following functions.
// It is a hash/map with following possible properties (and defaults):
// animate: true (determines if you want transition immediate or with animation)

// Goes to next screen. If user is already at last screen,
// it'll stay intact.
frameCarousel.next( options );

// Goes to previous screen. If user is already at first screen,
// it'll stay intact.
frameCarousel.previous( options );

// Goes to screen identified by index. Stays intact if index
// is out of bounds.
frameCarousel.goto( index, options );

// Resizes the frame to given 'width' and 'height'. if no argument
// is passed, it'd resize to original applicable size.
// If only 'width' is passed, it'd determine 'height' by original
// aspect ratio. Same is true when only 'height' is passed
// and not 'width'.
frameCarousel.resize( options );

// Call this if you'd like remove frame image.
// Can be useful on smaller screens.
frameCarousel.removeFrame();

// Gracefully destructs the instance.
frameCarousel.destroy();

// If 'debug' mode is enabled (see options), any string passed to this method
// will be printed over screen. Useful for testing in situations
// when console.log/alert are not conveniently available.
frameCarousel.debug( message );

Events

// Grab the frameCarousel instance from host element.
// Each callback receives a hash/map 'e' with relevant
// information.
$('.host-element')

  // Triggers when a frameCarousel instance is ready.
  .on('fc-ready', function( e ){

  })

  // Triggers when a frameCarousel instance is destroyed.
  .on('fc-destroy', function( e ){

  })

  // Triggers when a screen transition begins.
  .on('fc-transition-start', function( e ){
    // e.from => screen index from where transition begun
    // e.to   => screen index to where transition has to end
  })

  // Triggers when a screen transition ends.
  .on('fc-transition-end', function( e ){
    // e.from => screen index from where transition begun
    // e.to   => screen index to where transition ended
  });

FAQs

  1. Why did you make another carousel?

    We wanted to make a carousel optimized for rendering sliders inside frame images. Two things were hard to do with existing carousels:

    1. Uniform Resizing of Images

      In one of our projects, we had to generate web pages with carousels within frames at runtime. We had to show user provided images, in uniform sizes, inside the carousel which originally could be different in sizes.

    2. Responsiveness

      On different screens, we wanted to resize the carousel accordingly, without ruining its placement position on the frame.

  2. Is it free?

    Yes.

  3. Can I use it in my commercial project?

    Yes.

  4. Can I make a feature request?

    Yes. Write to us at support@eastros.com.

  5. What is the license type?

    MIT

  6. Where to log issues?

    https://github.com/Eastros/FrameCarousel/issues

Contact

We are a small group of developers trying to make our share of contributions to the world. Did we succeed? Let us know by writing at support@eastros.com

Did you like Frame Carousel?

Subscribe to our mailing list to get early access to our future similar projects.

We will not spam you, pinky promise!