Notoriously Pedantic Magistrate

    famous-carousel

    1.0.1 • Public • Published

    Famo.us Carousel

    A responsive carousel / slideshow / slider powered by Famo.us. Supports mouse, touch/swipe and keyboard navigation.


    BREAKING CHANGES: 1.0.0 introduces customizable transitions with an updated data format. Refer to the documentation and the example project.


    famous-carousel preview

    After cloning the repo:

    npm install
    

    Start the example project at port 8080:

    npm run example
    

    Usage

    famous-carousel uses Browserify require. Refer to the example folder for boilerplate setup. Also supported are ES6 imports as well as a global version:

    //-------------------------------------------------
    // CommonJS:
    var Carousel = require("famous-carousel").Carousel;
    
    // or...
    //-------------------------------------------------
    // ES6:
    import { Carousel } from "famous-carousel";
    
    // or...
    //-------------------------------------------------
    // Global (boo)
    var Carousel = famousCarousel.default( {...} );
    
    // Then create a new instance of the Carousel:
    var myCarousel = new Carousel("myDivSelector", {
                            // add options here
                            // ...
                        }
                    );
    

    Carousel Options

    The following keys are supported in the options object. Only carouselData is required, all others are optional.

    • #### selector Type: String or Object
      Default: body
      As a string, selector is a CSS selector of the element to render into.
      As an object, selector is assumed to be a Famous node. The node's container should have overflow set to hidden.

    • #### carouselData (required) Type: Object
      This specifies the content of the slides and optional custom transitions.
      The transitions key specifies the global entry and exit transitions. Each slide may have its own transitions which overrides the global ones.

    "transitions": {
        "initialAlign": [x, y, z],  // 0 < x, y, z < 1
        "initialPosition": [x, y, z],
        "initialRotation": [x, y, z],  // 0 < x, y, z < 1
        "entryTransition": {
            "transform": string, // "align", "rotate", "position"
            "transformParams": [x, y, z],
            "curve": string, // famous fixed curves
            "duration" : number, // ms
        },
        "exitTransition": {
            // Same keys as entryTransition
        }
    }

    The slides key is an array of objects, each containing type, data, and optionally backgroundSize & transition keys.
    type: may be image, markup, or node.
    data: must be a url for image, any valid html for markup, or a Famo.us node object.
    class: optional CSS class to apply to the slide.
    backgroundSize: [optional] CSS background-size attribute (default contain)
    transition: [optional] custom transition for the given slide only (see above for format).
    Example data:

    "slide": {
        [
            {   "type": "image",
                "data": "http://myDomain/myPicture.jpg",
                "backgroundSize": "cover"
            },
            {   "type": "markup",
                "data": "<div style='color:blue'>Hello World<BR><BR>It's me!</div>"
            },
            {   "type": "node",
                "data": myFamousNode
            }
        ]
    }
    • #### animStartCallback Type: Function (node, index)
      Callback fires when a slide starts to move into the center position. Parameters (node, index) are the slide's node and its corresponding carouselData index.

    • #### animDoneCallback Type: Function (node, index)
      Callback fires when a slide has finished settling in the center visible position. Parameters (node, index) are the visible slide's node and its corresponding carouselData index.

    • #### initialIndex Type: Integer
      Default: 0
      Initial slide number to show (zero-based). If larger than the number of slides, it will cap to the final slide.

    • #### wrapAround Type: Boolean
      Default: false
      By default, navigation stops at the ends of the slide set. Setting wrapAround to true allows navigation to wrap from one end to the other.

    • #### autoPlay Type: Integer
      Default: 0
      Automatically transition slides, pausing on each slide for the number of milliseconds specified. When the user navigates manually, automatic playback stops.

    • #### autoSlidesToAdvance Type: Integer
      Default: 1
      Number of slides to advance during automatic playback.

    • #### manualSlidesToAdvance Type: Integer
      Default: 1
      Number of slides to advance when user navigates.

    • #### dotWidth Type: Integer
      Default: 10
      Width of dots along bottom.

    • #### dotSpacing Type: Integer
      Default: 5
      Spacing of dots along bottom.

    • #### dotForeColor Type: String
      Default: "white"
      Navigation dot foreground color (CSS style).

    • #### dotBackColor Type: String
      Default: "transparent"
      Navigation dot background color (CSS style).

    • #### dotOpacity Type: Float
      Default: 1.0
      Navigation dot opacity (CSS style).

    • #### dotSelectedClass Type: String
      CSS class to style the selected dot. This overrides the other dot* CSS options (dotWidth & dotSpacing continue to be honored).

    • #### dotUnselectedClass Type: String
      CSS class to style unselected dots. This overrides the other dot* CSS options (dotWidth & dotSpacing continue to be honored).

    • #### arrowFillColor Type: String
      Default: "white"
      Navigation arrow fill color (CSS style).

    • #### arrowOutlineColor Type: String
      Default: "transparent"
      Navigation arrow outline color (CSS style).

    • #### arrowClass Type: String
      CSS class to style dots. This overrides the other arrow* CSS options.

    Public methods

    • #### updateData() Updates the slide data. This calls clearSlides() to reinitialize the slides. There is an issue with the dots not re-rendering properly.

    • #### clearSlides() Removes the slides.

    • #### clearAll() Removes the carousel instance entirely. NOTE: Famo.us 0.5.2 has a bug causing it not to remove the DOMElement. famous-carousel removes the div.famous-dom-renderer element for now.

    Building

    To build self-contained bundles:

    $ npm run build
    

    Builds

    • CommonJS version (dist/famous-carousel.min.js)

    • global version (dist/global/famous-carousel.min.js), and global debug version (dist/global/famous-carousel.debug.js).
      The global build uses the variable name famousCarousel.
      To see the global version in action open browser to local port 8080/global.html after:

      $ npm run example

    To build optional es5 code:

     $ npm install -g babel
     $ npm run build-es5
    

    Run tests (linter & style checks for now):

    npm run test
    

    FAQ

    Q: The arrows & dots show, but the slides are invisible.
    A: famous-carousel sizes to its container's dimensions. Due to CSS box model rules, if no height is specified for the container, the default auto height computes to 0. Short answer: set a height for its parents all the way up to the root element.

    Q: The slides appear from outside the containing element when animating.
    A: Famous-carousel sets the container's overflow property to hidden. Check if something has overridden that property.

    Q: How to center the slides?
    A: Create a parent div of the container and set these properties:

    .myContainersParent {
        overflow:hidden;
        position:absolute;
        left:0; right:0;
        top:0; bottom:0;
        margin:auto;
    }
    

    Q: The arrows/dots aren't visible [against a white background].
    A: dotBackColor and arrowOutlineColor default to transparent. Set them to a different color.

    Q: The slides are shifted down and to the right.
    A: The selector element must not have any padding. The work-around for this Famous engine bug is to wrap the selector element in a container element which has the padding. Remove all padding from the selector element. See example/index.html for... an example.

    Q: Safari allows the user to vertically drag the page. How do I stop that?
    A: Touch events on the body must be disabled. A ready to use solution is iNoBounce.

    Q: I upgraded the famous-carousel version and everything broke.
    A1: Delete node_modules and run npm install again.
    A2: Check that the data format matches what is required by the given version of famous-carousel.

    To Do

    Pull requests are welcome. When submitting a PR, please make sure npm run test passes.

    • Unit tests.
    • Add exit transition.
    • Add more user-configurable options such as slide transitions, nav arrow images...
    • Re-implement physics option for customizable transitions.
    • Option to auto-hide navigation arrows & dots.
    • Navigate by clicking on dots.
    • Auto start/stop videos in slides.
    • Option for vertical scrolling.
    • Support CSS class for slides?

    License

    This project is based on the Famo.us Carousel tutorial and bound by the same MIT license. Refer to the LICENSE file.

    Install

    npm i famous-carousel

    DownloadsWeekly Downloads

    1

    Version

    1.0.1

    License

    MIT

    Last publish

    Collaborators

    • peace
    • talves