/hippo/src/main/webapp/yui/carousel/carousel.js

/*
Copyright (c) 2009, Yahoo! Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.net/yui/license.txt
version: 2.7.0
*/
/**
 * The Carousel module provides a widget for browsing among a set of like
 * objects represented pictorially.
 *
 * @module carousel
 * @requires yahoo, dom, event, element
 * @optional animation
 * @namespace YAHOO.widget
 * @title Carousel Widget
 * @beta
 */
(function () {

    var WidgetName;             // forward declaration

    /**
     * The Carousel widget.
     *
     * @class Carousel
     * @extends YAHOO.util.Element
     * @constructor
     * @param el {HTMLElement | String} The HTML element that represents the
     * the container that houses the Carousel.
     * @param cfg {Object} (optional) The configuration values
     */
    YAHOO.widget.Carousel = function (el, cfg) {

        YAHOO.widget.Carousel.superclass.constructor.call(this, el, cfg);
    };

    /*
     * Private variables of the Carousel component
     */

    /* Some abbreviations to avoid lengthy typing and lookups. */
    var Carousel    = YAHOO.widget.Carousel,
        Dom         = YAHOO.util.Dom,
        Event       = YAHOO.util.Event,
        JS          = YAHOO.lang;

    /**
     * The widget name.
     * @private
     * @static
     */
    WidgetName = "Carousel";

    /**
     * The internal table of Carousel instances.
     * @private
     * @static
     */
    var instances = {},

    /*
     * Custom events of the Carousel component
     */

    /**
     * @event afterScroll
     * @description Fires when the Carousel has scrolled to the previous or
     * next page.  Passes back the index of the first and last visible items in
     * the Carousel.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    afterScrollEvent = "afterScroll",

    /**
     * @event allItemsRemovedEvent
     * @description Fires when all items have been removed from the Carousel.
     * See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    allItemsRemovedEvent = "allItemsRemoved",

    /**
     * @event beforeHide
     * @description Fires before the Carousel is hidden.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    beforeHideEvent = "beforeHide",

    /**
     * @event beforePageChange
     * @description Fires when the Carousel is about to scroll to the previous
     * or next page.  Passes back the page number of the current page.  Note
     * that the first page number is zero.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    beforePageChangeEvent = "beforePageChange",

    /**
     * @event beforeScroll
     * @description Fires when the Carousel is about to scroll to the previous
     * or next page.  Passes back the index of the first and last visible items
     * in the Carousel and the direction (backward/forward) of the scroll.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    beforeScrollEvent = "beforeScroll",

    /**
     * @event beforeShow
     * @description Fires when the Carousel is about to be shown.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    beforeShowEvent = "beforeShow",

    /**
     * @event blur
     * @description Fires when the Carousel loses focus.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    blurEvent = "blur",

    /**
     * @event focus
     * @description Fires when the Carousel gains focus.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    focusEvent = "focus",

    /**
     * @event hide
     * @description Fires when the Carousel is hidden.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    hideEvent = "hide",

    /**
     * @event itemAdded
     * @description Fires when an item has been added to the Carousel.  Passes
     * back the content of the item that would be added, the index at which the
     * item would be added, and the event itself.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    itemAddedEvent = "itemAdded",

    /**
     * @event itemRemoved
     * @description Fires when an item has been removed from the Carousel.
     * Passes back the content of the item that would be removed, the index
     * from which the item would be removed, and the event itself.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    itemRemovedEvent = "itemRemoved",

    /**
     * @event itemSelected
     * @description Fires when an item has been selected in the Carousel.
     * Passes back the index of the selected item in the Carousel.  Note, that
     * the index begins from zero.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    itemSelectedEvent = "itemSelected",

    /**
     * @event loadItems
     * @description Fires when the Carousel needs more items to be loaded for
     * displaying them.  Passes back the first and last visible items in the
     * Carousel, and the number of items needed to be loaded.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    loadItemsEvent = "loadItems",

    /**
     * @event navigationStateChange
     * @description Fires when the state of either one of the navigation
     * buttons are changed from enabled to disabled or vice versa.  Passes back
     * the state (true/false) of the previous and next buttons.  The value true
     * signifies the button is enabled, false signifies disabled.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    navigationStateChangeEvent = "navigationStateChange",

    /**
     * @event pageChange
     * @description Fires after the Carousel has scrolled to the previous or
     * next page.  Passes back the page number of the current page.  Note
     * that the first page number is zero.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    pageChangeEvent = "pageChange",

    /*
     * Internal event.
     * @event render
     * @description Fires when the Carousel is rendered.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    renderEvent = "render",

    /**
     * @event show
     * @description Fires when the Carousel is shown.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    showEvent = "show",

    /**
     * @event startAutoPlay
     * @description Fires when the auto play has started in the Carousel.  See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    startAutoPlayEvent = "startAutoPlay",

    /**
     * @event stopAutoPlay
     * @description Fires when the auto play has been stopped in the Carousel.
     * See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    stopAutoPlayEvent = "stopAutoPlay",

    /*
     * Internal event.
     * @event uiUpdateEvent
     * @description Fires when the UI has been updated.
     * See
     * <a href="YAHOO.util.Element.html#addListener">Element.addListener</a>
     * for more information on listening for this event.
     * @type YAHOO.util.CustomEvent
     */
    uiUpdateEvent = "uiUpdate";

    /*
     * Private helper functions used by the Carousel component
     */

    /**
     * Create an element, set its class name and optionally install the element
     * to its parent.
     * @method createElement
     * @param el {String} The element to be created
     * @param attrs {Object} Configuration of parent, class and id attributes.
     * If the content is specified, it is inserted after creation of the
     * element. The content can also be an HTML element in which case it would
     * be appended as a child node of the created element.
     * @private
     */
    function createElement(el, attrs) {
        var newEl = document.createElement(el);

        attrs = attrs || {};
        if (attrs.className) {
            Dom.addClass(newEl, attrs.className);
        }

        if (attrs.parent) {
            attrs.parent.appendChild(newEl);
        }

        if (attrs.id) {
            newEl.setAttribute("id", attrs.id);
        }

        if (attrs.content) {
            if (attrs.content.nodeName) {
                newEl.appendChild(attrs.content);
            } else {
                newEl.innerHTML = attrs.content;
            }
        }

        return newEl;
    }

    /**
     * Get the computed style of an element.
     *
     * @method getStyle
     * @param el {HTMLElement} The element for which the style needs to be
     * returned.
     * @param style {String} The style attribute
     * @param type {String} "int", "float", etc. (defaults to int)
     * @private
     */
    function getStyle(el, style, type) {
        var value;

        if (!el) {
            return 0;
        }

        function getStyleIntVal(el, style) {
            var val;

            /*
             * XXX: Safari calculates incorrect marginRight for an element
             * which has its parent element style set to overflow: hidden
             * https://bugs.webkit.org/show_bug.cgi?id=13343
             * Let us assume marginLeft == marginRight
             */
            if (style == "marginRight" && YAHOO.env.ua.webkit) {
                val = parseInt(Dom.getStyle(el, "marginLeft"), 10);
            } else {
                val = parseInt(Dom.getStyle(el, style), 10);
            }

            return JS.isNumber(val) ? val : 0;
        }

        function getStyleFloatVal(el, style) {
            var val;

            /*
             * XXX: Safari calculates incorrect marginRight for an element
             * which has its parent element style set to overflow: hidden
             * https://bugs.webkit.org/show_bug.cgi?id=13343
             * Let us assume marginLeft == marginRight
             */
            if (style == "marginRight" && YAHOO.env.ua.webkit) {
                val = parseFloat(Dom.getStyle(el, "marginLeft"));
            } else {
                val = parseFloat(Dom.getStyle(el, style));
            }

            return JS.isNumber(val) ? val : 0;
        }

        if (typeof type == "undefined") {
            type = "int";
        }

        switch (style) {
        case "height":
            value = el.offsetHeight;
            if (value > 0) {
                value += getStyleIntVal(el, "marginTop")        +
                        getStyleIntVal(el, "marginBottom");
            } else {
                value = getStyleFloatVal(el, "height")          +
                        getStyleIntVal(el, "marginTop")         +
                        getStyleIntVal(el, "marginBottom")      +
                        getStyleIntVal(el, "borderTopWidth")    +
                        getStyleIntVal(el, "borderBottomWidth") +
                        getStyleIntVal(el, "paddingTop")        +
                        getStyleIntVal(el, "paddingBottom");
            }
            break;
        case "width":
            value = el.offsetWidth;
            if (value > 0) {
                value += getStyleIntVal(el, "marginLeft")       +
                        getStyleIntVal(el, "marginRight");
            } else {
                value = getStyleFloatVal(el, "width")           +
                        getStyleIntVal(el, "marginLeft")        +
                        getStyleIntVal(el, "marginRight")       +
                        getStyleIntVal(el, "borderLeftWidth")   +
                        getStyleIntVal(el, "borderRightWidth")  +
                        getStyleIntVal(el, "paddingLeft")       +
                        getStyleIntVal(el, "paddingRight");
            }
            break;
        default:
            if (type == "int") {
                value = getStyleIntVal(el, style);
            } else if (type == "float") {
                value = getStyleFloatVal(el, style);
            } else {
                value = Dom.getStyle(el, style);
            }
            break;
        }

        return value;
    }

    /**
     * Compute and return the height or width of a single Carousel item
     * depending upon the orientation.
     *
     * @method getCarouselItemSize
     * @param which {String} "height" or "width" to be returned.  If this is
     * passed explicitly, the calculated size is not cached.
     * @private
     */
    function getCarouselItemSize(which) {
        var carousel = this,
            child,
            size     = 0,
            vertical = false;

        if (carousel._itemsTable.numItems === 0) {
            return 0;
        }

        if (typeof which == "undefined") {
            if (carousel._itemsTable.size > 0) {
                return carousel._itemsTable.size;
            }
        }

        if (JS.isUndefined(carousel._itemsTable.items[0])) {
            return 0;
        }

        child = Dom.get(carousel._itemsTable.items[0].id);

        if (typeof which == "undefined") {
            vertical = carousel.get("isVertical");
        } else {
            vertical = which == "height";
        }

        if (vertical) {
            size = getStyle(child, "height");
        } else {
            size = getStyle(child, "width");
        }

        if (typeof which == "undefined") {
            carousel._itemsTable.size = size; // save the size for later
        }

        return size;
    }

    /**
     * Return the index of the first item in the view port for displaying item
     * in "pos".
     *
     * @method getFirstVisibleForPosition
     * @param pos {Number} The position of the item to be displayed
     * @private
     */
    function getFirstVisibleForPosition(pos) {
        var num = this.get("numVisible");

        return Math.floor(pos / num) * num;
    }

    /**
     * Return the scrolling offset size given the number of elements to
     * scroll.
     *
     * @method getScrollOffset
     * @param delta {Number} The delta number of elements to scroll by.
     * @private
     */
    function getScrollOffset(delta) {
        var itemSize = 0,
            size     = 0;

        itemSize = getCarouselItemSize.call(this);
        size     = itemSize * delta;

        // XXX: really, when the orientation is vertical, the scrolling
        // is not exactly the number of elements into element size.
        if (this.get("isVertical")) {
            size -= delta;
        }

        return size;
    }

    /**
     * Scroll the Carousel by a page backward.
     *
     * @method scrollPageBackward
     * @param {Event} ev The event object
     * @param {Object} obj The context object
     * @private
     */
    function scrollPageBackward(ev, obj) {
        obj.scrollPageBackward();
        Event.preventDefault(ev);
    }

    /**
     * Scroll the Carousel by a page forward.
     *
     * @method scrollPageForward
     * @param {Event} ev The event object
     * @param {Object} obj The context object
     * @private
     */
    function scrollPageForward(ev, obj) {
        obj.scrollPageForward();
        Event.preventDefault(ev);
    }

    /**
     * Set the selected item.
     *
     * @method setItemSelection
     * @param {Number} newpos The index of the new position
     * @param {Number} oldpos The index of the previous position
     * @private
     */
     function setItemSelection(newpos, oldpos) {
        var carousel = this,
            cssClass   = carousel.CLASSES,
            el,
            firstItem  = carousel._firstItem,
            isCircular = carousel.get("isCircular"),
            numItems   = carousel.get("numItems"),
            numVisible = carousel.get("numVisible"),
            position   = oldpos,
            sentinel   = firstItem + numVisible - 1;

        if (position >= 0 && position < numItems) {
            if (!JS.isUndefined(carousel._itemsTable.items[position])) {
                el = Dom.get(carousel._itemsTable.items[position].id);
                if (el) {
                    Dom.removeClass(el, cssClass.SELECTED_ITEM);
                }
            }
        }

        if (JS.isNumber(newpos)) {
            newpos = parseInt(newpos, 10);
            newpos = JS.isNumber(newpos) ? newpos : 0;
        } else {
            newpos = firstItem;
        }

        if (JS.isUndefined(carousel._itemsTable.items[newpos])) {
            newpos = getFirstVisibleForPosition.call(carousel, newpos);
            carousel.scrollTo(newpos); // still loading the item
        }

        if (!JS.isUndefined(carousel._itemsTable.items[newpos])) {
            el = Dom.get(carousel._itemsTable.items[newpos].id);
            if (el) {
                Dom.addClass(el, cssClass.SELECTED_ITEM);
            }
        }

        if (newpos < firstItem || newpos > sentinel) { // out of focus
            newpos = getFirstVisibleForPosition.call(carousel, newpos);
            carousel.scrollTo(newpos);
        }
    }

    /**
     * Fire custom events for enabling/disabling navigation elements.
     *
     * @method syncNavigation
     * @private
     */
    function syncNavigation() {
        var attach   = false,
            carousel = this,
            cssClass = carousel.CLASSES,
            i,
            navigation,
            sentinel;

        // Don't do anything if the Carousel is not rendered
        if (!carousel._hasRendered) {
            return;
        }

        navigation = carousel.get("navigation");
        sentinel   = carousel._firstItem + carousel.get("numVisible");

        if (navigation.prev) {
            if (carousel.get("numItems") === 0 || carousel._firstItem === 0) {
                if (carousel.get("numItems") === 0 ||
                   !carousel.get("isCircular")) {
                    Event.removeListener(navigation.prev, "click",
                            scrollPageBackward);
                    Dom.addClass(navigation.prev, cssClass.FIRST_NAV_DISABLED);
                    for (i = 0; i < carousel._navBtns.prev.length; i++) {
                        carousel._navBtns.prev[i].setAttribute("disabled",
                                "true");
                    }
                    carousel._prevEnabled = false;
                } else {
                    attach = !carousel._prevEnabled;
                }
            } else {
                attach = !carousel._prevEnabled;
            }

            if (attach) {
                Event.on(navigation.prev, "click", scrollPageBackward,
                         carousel);
                Dom.removeClass(navigation.prev, cssClass.FIRST_NAV_DISABLED);
                for (i = 0; i < carousel._navBtns.prev.length; i++) {
                    carousel._navBtns.prev[i].removeAttribute("disabled");
                }
                carousel._prevEnabled = true;
            }
        }

        attach = false;
        if (navigation.next) {
            if (sentinel >= carousel.get("numItems")) {
                if (!carousel.get("isCircular")) {
                    Event.removeListener(navigation.next, "click",
                            scrollPageForward);
                    Dom.addClass(navigation.next, cssClass.DISABLED);
                    for (i = 0; i < carousel._navBtns.next.length; i++) {
                        carousel._navBtns.next[i].setAttribute("disabled",
                                "true");
                    }
                    carousel._nextEnabled = false;
                } else {
                    attach = !carousel._nextEnabled;
                }
            } else {
                attach = !carousel._nextEnabled;
            }

            if (attach) {
                Event.on(navigation.next, "click", scrollPageForward,
                         carousel);
                Dom.removeClass(navigation.next, cssClass.DISABLED);
                for (i = 0; i < carousel._navBtns.next.length; i++) {
                    carousel._navBtns.next[i].removeAttribute("disabled");
                }
                carousel._nextEnabled = true;
            }
        }

        carousel.fireEvent(navigationStateChangeEvent,
                { next: carousel._nextEnabled, prev: carousel._prevEnabled });
    }

    /**
     * Synchronize and redraw the Pager UI if necessary.
     *
     * @method syncPagerUi
     * @private
     */
    function syncPagerUi(page) {
        var carousel = this, numPages, numVisible;

        // Don't do anything if the Carousel is not rendered
        if (!carousel._hasRendered) {
            return;
        }

        numVisible = carousel.get("numVisible");

        if (!JS.isNumber(page)) {
            page = Math.ceil(carousel.get("selectedItem") / numVisible);
        }
        numPages = Math.ceil(carousel.get("numItems") / numVisible);

        carousel._pages.num = numPages;
        carousel._pages.cur = page;

        if (numPages > carousel.CONFIG.MAX_PAGER_BUTTONS) {
            carousel._updatePagerMenu();
        } else {
            carousel._updatePagerButtons();
        }
    }

    /**
     * Handle UI update.
     * Call the appropriate methods on events fired when an item is added, or
     * removed for synchronizing the DOM.
     *
     * @method syncUi
     * @param {Object} o The item that needs to be added or removed
     * @private
     */
    function syncUi(o) {
        var carousel = this;

        if (!JS.isObject(o)) {
            return;
        }

        switch (o.ev) {
        case itemAddedEvent:
            carousel._syncUiForItemAdd(o);
            break;
        case itemRemovedEvent:
            carousel._syncUiForItemRemove(o);
            break;
        case loadItemsEvent:
            carousel._syncUiForLazyLoading(o);
            break;
        }

        carousel.fireEvent(uiUpdateEvent);
    }

    /**
     * Update the state variables after scrolling the Carousel view port.
     *
     * @method updateStateAfterScroll
     * @param {Integer} item The index to which the Carousel has scrolled to.
     * @param {Integer} sentinel The last element in the view port.
     * @private
     */
    function updateStateAfterScroll(item, sentinel) {
        var carousel   = this,
            page       = carousel.get("currentPage"),
            newPage,
            numPerPage = carousel.get("numVisible");

        newPage = parseInt(carousel._firstItem / numPerPage, 10);
        if (newPage != page) {
            carousel.setAttributeConfig("currentPage", { value: newPage });
            carousel.fireEvent(pageChangeEvent, newPage);
        }

        if (carousel.get("selectOnScroll")) {
            if (carousel.get("selectedItem") != carousel._selectedItem) {
                carousel.set("selectedItem", carousel._selectedItem);
            }
        }

        clearTimeout(carousel._autoPlayTimer);
        delete carousel._autoPlayTimer;
        if (carousel.isAutoPlayOn()) {
            carousel.startAutoPlay();
        }

        carousel.fireEvent(afterScrollEvent,
                           { first: carousel._firstItem,
                             last: sentinel },
                           carousel);
    }

    /*
     * Static members and methods of the Carousel component
     */

    /**
     * Return the appropriate Carousel object based on the id associated with
     * the Carousel element or false if none match.
     * @method getById
     * @public
     * @static
     */
    Carousel.getById = function (id) {
        return instances[id] ? instances[id].object : false;
    };

    YAHOO.extend(Carousel, YAHOO.util.Element, {

        /*
         * Internal variables used within the Carousel component
         */

        /**
         * The Animation object.
         *
         * @property _animObj
         * @private
         */
        _animObj: null,

        /**
         * The Carousel element.
         *
         * @property _carouselEl
         * @private
         */
        _carouselEl: null,

        /**
         * The Carousel clipping container element.
         *
         * @property _clipEl
         * @private
         */
        _clipEl: null,

        /**
         * The current first index of the Carousel.
         *
         * @property _firstItem
         * @private
         */
        _firstItem: 0,

        /**
         * Does the Carousel element have focus?
         *
         * @property _hasFocus
         * @private
         */
        _hasFocus: false,

        /**
         * Is the Carousel rendered already?
         *
         * @property _hasRendered
         * @private
         */
        _hasRendered: false,

        /**
         * Is the animation still in progress?
         *
         * @property _isAnimationInProgress
         * @private
         */
        _isAnimationInProgress: false,

        /**
         * Is the auto-scrolling of Carousel in progress?
         *
         * @property _isAutoPlayInProgress
         * @private
         */
        _isAutoPlayInProgress: false,

        /**
         * The table of items in the Carousel.
         * The numItems is the number of items in the Carousel, items being the
         * array of items in the Carousel.  The size is the size of a single
         * item in the Carousel.  It is cached here for efficiency (to avoid
         * computing the size multiple times).
         *
         * @property _itemsTable
         * @private
         */
        _itemsTable: null,

        /**
         * The Carousel navigation buttons.
         *
         * @property _navBtns
         * @private
         */
        _navBtns: null,

        /**
         * The Carousel navigation.
         *
         * @property _navEl
         * @private
         */
        _navEl: null,

        /**
         * Status of the next navigation item.
         *
         * @property _nextEnabled
         * @private
         */
        _nextEnabled: true,

        /**
         * The Carousel pages structure.
         * This is an object of the total number of pages and the current page.
         *
         * @property _pages
         * @private
         */
        _pages: null,

        /**
         * Status of the previous navigation item.
         *
         * @property _prevEnabled
         * @private
         */
        _prevEnabled: true,

        /**
         * Whether the Carousel size needs to be recomputed or not?
         *
         * @property _recomputeSize
         * @private
         */
        _recomputeSize: true,

        /*
         * CSS classes used by the Carousel component
         */

        CLASSES: {

            /**
             * The class name of the Carousel navigation buttons.
             *
             * @property BUTTON
             * @default "yui-carousel-button"
             */
            BUTTON: "yui-carousel-button",

            /**
             * The class name of the Carousel element.
             *
             * @property CAROUSEL
             * @default "yui-carousel"
             */
            CAROUSEL: "yui-carousel",

            /**
             * The class name of the container of the items in the Carousel.
             *
             * @property CAROUSEL_EL
             * @default "yui-carousel-element"
             */
            CAROUSEL_EL: "yui-carousel-element",

            /**
             * The class name of the Carousel's container element.
             *
             * @property CONTAINER
             * @default "yui-carousel-container"
             */
            CONTAINER: "yui-carousel-container",

            /**
             * The class name of the Carousel's container element.
             *
             * @property CONTENT
             * @default "yui-carousel-content"
             */
            CONTENT: "yui-carousel-content",

            /**
             * The class name of a disabled navigation button.
             *
             * @property DISABLED
             * @default "yui-carousel-button-disabled"
             */
            DISABLED: "yui-carousel-button-disabled",

            /**
             * The class name of the first Carousel navigation button.
             *
             * @property FIRST_NAV
             * @default " yui-carousel-first-button"
             */
            FIRST_NAV: " yui-carousel-first-button",

            /**
             * The class name of a first disabled navigation button.
             *
             * @property FIRST_NAV_DISABLED
             * @default "yui-carousel-first-button-disabled"
             */
            FIRST_NAV_DISABLED: "yui-carousel-first-button-disabled",

            /**
             * The class name of a first page element.
             *
             * @property FIRST_PAGE
             * @default "yui-carousel-nav-first-page"
             */
            FIRST_PAGE: "yui-carousel-nav-first-page",

            /**
             * The class name of the Carousel navigation button that has focus.
             *
             * @property FOCUSSED_BUTTON
             * @default "yui-carousel-button-focus"
             */
            FOCUSSED_BUTTON: "yui-carousel-button-focus",

            /**
             * The class name of a horizontally oriented Carousel.
             *
             * @property HORIZONTAL
             * @default "yui-carousel-horizontal"
             */
            HORIZONTAL: "yui-carousel-horizontal",

            /**
             * The element to be used as the progress indicator when the item
             * is still being loaded.
             *
             * @property ITEM_LOADING
             * @default The progress indicator (spinner) image CSS class
             */
            ITEM_LOADING: "yui-carousel-item-loading",

            /**
             * The class name that will be set if the Carousel adjusts itself
             * for a minimum width.
             *
             * @property MIN_WIDTH
             * @default "yui-carousel-min-width"
             */
            MIN_WIDTH: "yui-carousel-min-width",

            /**
             * The navigation element container class name.
             *
             * @property NAVIGATION
             * @default "yui-carousel-nav"
             */
            NAVIGATION: "yui-carousel-nav",

            /**
             * The class name of the next Carousel navigation button.
             *
             * @property NEXT_NAV
             * @default " yui-carousel-next-button"
             */
            NEXT_NAV: " yui-carousel-next-button",

            /**
             * The class name of the next navigation link. This variable is
             * not only used for styling, but also for identifying the link
             * within the Carousel container.
             *
             * @property NEXT_PAGE
             * @default "yui-carousel-next"
             */
            NEXT_PAGE: "yui-carousel-next",

            /**
             * The class name for the navigation container for prev/next.
             *
             * @property NAV_CONTAINER
             * @default "yui-carousel-buttons"
             */
            NAV_CONTAINER: "yui-carousel-buttons",

            /**
             * The class name of the focussed page navigation.  This class is
             * specifically used for the ugly focus handling in Opera.
             *
             * @property PAGE_FOCUS
             * @default "yui-carousel-nav-page-focus"
             */
            PAGE_FOCUS: "yui-carousel-nav-page-focus",

            /**
             * The class name of the previous navigation link. This variable
             * is not only used for styling, but also for identifying the link
             * within the Carousel container.
             *
             * @property PREV_PAGE
             * @default "yui-carousel-prev"
             */
            PREV_PAGE: "yui-carousel-prev",

            /**
             * The class name of the selected item.
             *
             * @property SELECTED_ITEM
             * @default "yui-carousel-item-selected"
             */
            SELECTED_ITEM: "yui-carousel-item-selected",

            /**
             * The class name of the selected paging navigation.
             *
             * @property SELECTED_NAV
             * @default "yui-carousel-nav-page-selected"
             */
            SELECTED_NAV: "yui-carousel-nav-page-selected",

            /**
             * The class name of a vertically oriented Carousel.
             *
             * @property VERTICAL
             * @default "yui-carousel-vertical"
             */
            VERTICAL: "yui-carousel-vertical",

            /**
             * The class name of the (vertical) Carousel's container element.
             *
             * @property VERTICAL_CONTAINER
             * @default "yui-carousel-vertical-container"
             */
            VERTICAL_CONTAINER: "yui-carousel-vertical-container",

            /**
             * The class name of a visible Carousel.
             *
             * @property VISIBLE
             * @default "yui-carousel-visible"
             */
            VISIBLE: "yui-carousel-visible"

        },

        /*
         * Configuration attributes for configuring the Carousel component
         */

        CONFIG: {

            /**
             * The offset of the first visible item in the Carousel.
             *
             * @property FIRST_VISIBLE
             * @default 0
             */
            FIRST_VISIBLE: 0,

            /**
             * The minimum width of the horizontal Carousel container to support
             * the navigation buttons.
             *
             * @property HORZ_MIN_WIDTH
             * @default 180
             */
            HORZ_MIN_WIDTH: 180,

            /**
             * The maximum number of pager buttons allowed beyond which the UI
             * of the pager would be a drop-down of pages instead of buttons.
             *
             * @property MAX_PAGER_BUTTONS
             * @default 5
             */
            MAX_PAGER_BUTTONS: 5,

            /**
             * The minimum width of the vertical Carousel container to support
             * the navigation buttons.
             *
             * @property VERT_MIN_WIDTH
             * @default 99
             */
            VERT_MIN_WIDTH: 99,

            /**
             * The number of visible items in the Carousel.
             *
             * @property NUM_VISIBLE
             * @default 3
             */
            NUM_VISIBLE: 3

        },

        /*
         * Internationalizable strings in the Carousel component
         */

        STRINGS: {

            /**
             * The content to be used as the progress indicator when the item
             * is still being loaded.
             *
             * @property ITEM_LOADING_CONTENT
             * @default "Loading"
             */
            ITEM_LOADING_CONTENT: "Loading",

            /**
             * The next navigation button name/text.
             *
             * @property NEXT_BUTTON_TEXT
             * @default "Next Page"
             */
            NEXT_BUTTON_TEXT: "Next Page",

            /**
             * The prefix text for the pager in case the UI is a drop-down.
             *
             * @property PAGER_PREFIX_TEXT
             * @default "Go to page "
             */
            PAGER_PREFIX_TEXT: "Go to page ",

            /**
             * The previous navigation button name/text.
             *
             * @property PREVIOUS_BUTTON_TEXT
             * @default "Previous Page"
             */
            PREVIOUS_BUTTON_TEXT: "Previous Page"

        },

        /*
         * Public methods of the Carousel component
         */

        /**
         * Insert or append an item to the Carousel.
         *
         * @method addItem
         * @public
         * @param item {String | Object | HTMLElement} The item to be appended
         * to the Carousel. If the parameter is a string, it is assumed to be
         * the content of the newly created item. If the parameter is an
         * object, it is assumed to supply the content and an optional class
         * and an optional id of the newly created item.
         * @param index {Number} optional The position to where in the list
         * (starts from zero).
         * @return {Boolean} Return true on success, false otherwise
         */
        addItem: function (item, index) {
            var carousel = this,
                className,
                content,
                elId,
                numItems = carousel.get("numItems");

            if (!item) {
                return false;
            }

            if (JS.isString(item) || item.nodeName) {
                content = item.nodeName ? item.innerHTML : item;
            } else if (JS.isObject(item)) {
                content = item.content;
            } else {
                return false;
            }

            className = item.className || "";
            elId      = item.id ? item.id : Dom.generateId();

            if (JS.isUndefined(index)) {
                carousel._itemsTable.items.push({
                        item      : content,
                        className : className,
                        id        : elId
                });
            } else {
                if (index < 0 || index >= numItems) {
                    return false;
                }
                carousel._itemsTable.items.splice(index, 0, {
                        item      : content,
                        className : className,
                        id        : elId
                });
            }
            carousel._itemsTable.numItems++;

            if (numItems < carousel._itemsTable.items.length) {
                carousel.set("numItems", carousel._itemsTable.items.length);
            }

            carousel.fireEvent(itemAddedEvent, { pos: index, ev: itemAddedEvent });

            return true;
        },

        /**
         * Insert or append multiple items to the Carousel.
         *
         * @method addItems
         * @public
         * @param items {Array} An array of items to be added with each item
         * representing an item, index pair [{item, index}, ...]
         * @return {Boolean} Return true on success, false otherwise
         */
        addItems: function (items) {
            var i, n, rv = true;

            if (!JS.isArray(items)) {
                return false;
            }

            for (i = 0, n = items.length; i < n; i++) {
                if (this.addItem(items[i][0], items[i][1]) === false) {
                    rv = false;
                }
            }

            return rv;
        },

        /**
         * Remove focus from the Carousel.
         *
         * @method blur
         * @public
         */
        blur: function () {
            this._carouselEl.blur();
            this.fireEvent(blurEvent);
        },

        /**
         * Clears the items from Carousel.
         *
         * @method clearItems
         * public
         */
        clearItems: function () {
            var carousel = this, n = carousel.get("numItems");

            while (n > 0) {
                if (!carousel.removeItem(0)) {
                }
                /*
                    For dynamic loading, the numItems may be much larger than
                    the actual number of items in the table.  So, set the
                    numItems to zero, and break out of the loop if the table
                    is already empty.
                 */
                if (carousel._itemsTable.numItems === 0) {
                    carousel.set("numItems", 0);
                    break;
                }
                n--;
            }

            carousel.fireEvent(allItemsRemovedEvent);
        },

        /**
         * Set focus on the Carousel.
         *
         * @method focus
         * @public
         */
        focus: function () {
            var carousel = this,
                first,
                focusEl,
                isSelectionInvisible,
                itemsTable,
                last,
                numVisible,
                selectOnScroll,
                selected,
                selItem;

            // Don't do anything if the Carousel is not rendered
            if (!carousel._hasRendered) {
                return;
            }

            if (carousel.isAnimating()) {
                // this messes up real bad!
                return;
            }

            selItem              = carousel.get("selectedItem");
            numVisible           = carousel.get("numVisible");
            selectOnScroll       = carousel.get("selectOnScroll");
            selected             = (selItem >= 0) ?
                                   carousel.getItem(selItem) : null;
            first                = carousel.get("firstVisible");
            last                 = first + numVisible - 1;
            isSelectionInvisible = (selItem < first || selItem > last);
            focusEl              = (selected && selected.id) ?
                                   Dom.get(selected.id) : null;
            itemsTable           = carousel._itemsTable;

            if (!selectOnScroll && isSelectionInvisible) {
                focusEl = (itemsTable && itemsTable.items &&
                           itemsTable.items[first]) ?
                        Dom.get(itemsTable.items[first].id) : null;
            }

            if (focusEl) {
                try {
                    focusEl.focus();
                } catch (ex) {
                    // ignore focus errors
                }
            }

            carousel.fireEvent(focusEvent);
        },

        /**
         * Hide the Carousel.
         *
         * @method hide
         * @public
         */
        hide: function () {
            var carousel = this;

            if (carousel.fireEvent(beforeHideEvent) !== false) {
                carousel.removeClass(carousel.CLASSES.VISIBLE);
                carousel.fireEvent(hideEvent);
            }
        },

        /**
         * Initialize the Carousel.
         *
         * @method init
         * @public
         * @param el {HTMLElement | String} The html element that represents
         * the Carousel container.
         * @param attrs {Object} The set of configuration attributes for
         * creating the Carousel.
         */
        init: function (el, attrs) {
            var carousel = this,
                elId     = el,  // save for a rainy day
                parse    = false;

            if (!el) {
                return;
            }

            carousel._hasRendered = false;
            carousel._navBtns     = { prev: [], next: [] };
            carousel._pages       = { el: null, num: 0, cur: 0 };
            carousel._itemsTable  = { loading: {}, numItems: 0,
                                      items: [], size: 0 };


            if (JS.isString(el)) {
                el = Dom.get(el);
            } else if (!el.nodeName) {
                return;
            }

            Carousel.superclass.init.call(carousel, el, attrs);

            if (el) {
                if (!el.id) {   // in case the HTML element is passed
                    el.setAttribute("id", Dom.generateId());
                }
                parse = carousel._parseCarousel(el);
                if (!parse) {
                    carousel._createCarousel(elId);
                }
            } else {
                el = carousel._createCarousel(elId);
            }
            elId = el.id;

            carousel.initEvents();

            if (parse) {
                carousel._parseCarouselItems();
            }

            if (!attrs || typeof attrs.isVertical == "undefined") {
                carousel.set("isVertical", false);
            }

            carousel._parseCarouselNavigation(el);
            carousel._navEl = carousel._setupCarouselNavigation();

            instances[elId] = { object: carousel };

            carousel._loadItems();
        },

        /**
         * Initialize the configuration attributes used to create the Carousel.
         *
         * @method initAttributes
         * @public
         * @param attrs {Object} The set of configuration attributes for
         * creating the Carousel.
         */
        initAttributes: function (attrs) {
            var carousel = this;

            attrs = attrs || {};
            Carousel.superclass.initAttributes.call(carousel, attrs);

            /**
             * @attribute carouselEl
             * @description The type of the Carousel element.
             * @default OL
             * @type Boolean
             */
            carousel.setAttributeConfig("carouselEl", {
                    validator : JS.isString,
                    value     : attrs.carouselEl || "OL"
            });

            /**
             * @attribute carouselItemEl
             * @description The type of the list of items within the Carousel.
             * @default LI
             * @type Boolean
             */
            carousel.setAttributeConfig("carouselItemEl", {
                    validator : JS.isString,
                    value     : attrs.carouselItemEl || "LI"
            });

            /**
             * @attribute currentPage
             * @description The current page number (read-only.)
             * @type Number
             */
            carousel.setAttributeConfig("currentPage", {
                    readOnly : true,
                    value    : 0
            });

            /**
             * @attribute firstVisible
             * @description The index to start the Carousel from (indexes begin
             * from zero)
             * @default 0
             * @type Number
             */
            carousel.setAttributeConfig("firstVisible", {
                    method    : carousel._setFirstVisible,
                    validator : carousel._validateFirstVisible,
                    value     :
                        attrs.firstVisible || carousel.CONFIG.FIRST_VISIBLE
            });

            /**
             * @attribute selectOnScroll
             * @description Set this to true to automatically set focus to
             * follow scrolling in the Carousel.
             * @default true
             * @type Boolean
             */
            carousel.setAttributeConfig("selectOnScroll", {
                    validator : JS.isBoolean,
                    value     : attrs.selectOnScroll || true
            });

            /**
             * @attribute numVisible
             * @description The number of visible items in the Carousel's
             * viewport.
             * @default 3
             * @type Number
             */
            carousel.setAttributeConfig("numVisible", {
                    method    : carousel._setNumVisible,
                    validator : carousel._validateNumVisible,
                    value     : attrs.numVisible || carousel.CONFIG.NUM_VISIBLE
            });

            /**
             * @attribute numItems
             * @description The number of items in the Carousel.
             * @type Number
             */
            carousel.setAttributeConfig("numItems", {
                    method    : carousel._setNumItems,
                    validator : carousel._validateNumItems,
                    value     : carousel._itemsTable.numItems
            });

            /**
             * @attribute scrollIncrement
             * @description The number of items to scroll by for arrow keys.
             * @default 1
             * @type Number
             */
            carousel.setAttributeConfig("scrollIncrement", {
                    validator : carousel._validateScrollIncrement,
                    value     : attrs.scrollIncrement || 1
            });

            /**
             * @attribute selectedItem
             * @description The index of the selected item.
             * @type Number
             */
            carousel.setAttributeConfig("selectedItem", {
                    method    : carousel._setSelectedItem,
                    validator : JS.isNumber,
                    value     : -1
            });

            /**
             * @attribute revealAmount
             * @description The percentage of the item to be revealed on each
             * side of the Carousel (before and after the first and last item
             * in the Carousel's viewport.)
             * @default 0
             * @type Number
             */
            carousel.setAttributeConfig("revealAmount", {
                    method    : carousel._setRevealAmount,
                    validator : carousel._validateRevealAmount,
                    value     : attrs.revealAmount || 0
            });

            /**
             * @attribute isCircular
             * @description Set this to true to wrap scrolling of the contents
             * in the Carousel.
             * @default false
             * @type Boolean
             */
            carousel.setAttributeConfig("isCircular", {
                    validator : JS.isBoolean,
                    value     : attrs.isCircular || false
            });

            /**
             * @attribute isVertical
             * @description True if the orientation of the Carousel is vertical
             * @default false
             * @type Boolean
             */
            carousel.setAttributeConfig("isVertical", {
                    method    : carousel._setOrientation,
                    validator : JS.isBoolean,
                    value     : attrs.isVertical || false
            });

            /**
             * @attribute navigation
             * @description The set of navigation controls for Carousel
             * @default <br>
             * { prev: null, // the previous navigation element<br>
             *   next: null } // the next navigation element
             * @type Object
             */
            carousel.setAttributeConfig("navigation", {
                    method    : carousel._setNavigation,
                    validator : carousel._validateNavigation,
                    value     :
                        attrs.navigation || {prev: null,next: null,page: null}
            });

            /**
             * @attribute animation
             * @description The optional animation attributes for the Carousel.
             * @default <br>
             * { speed: 0, // the animation speed (in seconds)<br>
             *   effect: null } // the animation effect (like
             *   YAHOO.util.Easing.easeOut)
             * @type Object
             */
            carousel.setAttributeConfig("animation", {
                    validator : carousel._validateAnimation,
                    value     : attrs.animation || { speed: 0, effect: null }
            });

            /**
             * @attribute autoPlay
             * @description Set this to time in milli-seconds to have the
             * Carousel automatically scroll the contents.
             * @type Number
             * @deprecated Use autoPlayInterval instead.
             */
            carousel.setAttributeConfig("autoPlay", {
                    validator : JS.isNumber,
                    value     : attrs.autoPlay || 0
            });

            /**
             * @attribute autoPlayInterval
             * @description The delay in milli-seconds for scrolling the
             * Carousel during auto-play.
             * Note: The startAutoPlay() method needs to be invoked to trigger
             * automatic scrolling of Carousel.
             * @type Number
             */
            carousel.setAttributeConfig("autoPlayInterval", {
                    validator : JS.isNumber,
                    value     : attrs.autoPlayInterval || 0
            });
        },

        /**
         * Initialize and bind the event handlers.
         *
         * @method initEvents
         * @public
         */
        initEvents: function () {
            var carousel = this,
                cssClass = carousel.CLASSES,
                focussedLi;

            carousel.on("keydown", carousel._keyboardEventHandler);

            carousel.on(afterScrollEvent, syncNavigation);

            carousel.on(itemAddedEvent, syncUi);

            carousel.on(itemRemovedEvent, syncUi);

            carousel.on(itemSelectedEvent, function () {
                if (carousel._hasFocus) {
                    carousel.focus();
                }
            });

            carousel.on(loadItemsEvent, syncUi);

            carousel.on(allItemsRemovedEvent, function (ev) {
                carousel.scrollTo(0);
                syncNavigation.call(carousel);
                syncPagerUi.call(carousel);
            });

            carousel.on(pageChangeEvent, syncPagerUi, carousel);

            carousel.on(renderEvent, function (ev) {
                carousel.set("selectedItem", carousel.get("firstVisible"));
                syncNavigation.call(carousel, ev);
                syncPagerUi.call(carousel, ev);
                carousel._setClipContainerSize();
            });

            carousel.on("selectedItemChange", function (ev) {
                setItemSelection.call(carousel, ev.newValue, ev.prevValue);
                if (ev.newValue >= 0) {
                    carousel._updateTabIndex(
                            carousel.getElementForItem(ev.newValue));
                }
                carousel.fireEvent(itemSelectedEvent, ev.newValue);
            });

            carousel.on(uiUpdateEvent, function (ev) {
                syncNavigation.call(carousel, ev);
                syncPagerUi.call(carousel, ev);
            });

            carousel.on("firstVisibleChange", function (ev) {
                if (!carousel.get("selectOnScroll")) {
                    if (ev.newValue >= 0) {
                        carousel._updateTabIndex(
                                carousel.getElementForItem(ev.newValue));
                    }
                }
            });

            // Handle item selection on mouse click
            carousel.on("click", function (ev) {
                if (carousel.isAutoPlayOn()) {
                    carousel.stopAutoPlay();
                }
                carousel._itemClickHandler(ev);
                carousel._pagerClickHandler(ev);
            });

            // Restore the focus on the navigation buttons

            Event.onFocus(carousel.get("element"), function (ev, obj) {
                var target = Event.getTarget(ev);

                if (target && target.nodeName.toUpperCase() == "A" &&
                    Dom.getAncestorByClassName(target, cssClass.NAVIGATION)) {
                    if (focussedLi) {
                        Dom.removeClass(focussedLi, cssClass.PAGE_FOCUS);
                    }
                    focussedLi = target.parentNode;
                    Dom.addClass(focussedLi, cssClass.PAGE_FOCUS);
                } else {
                    if (focussedLi) {
                        Dom.removeClass(focussedLi, cssClass.PAGE_FOCUS);
                    }
                }

                obj._hasFocus = true;
                obj._updateNavButtons(Event.getTarget(ev), true);
            }, carousel);

            Event.onBlur(carousel.get("element"), function (ev, obj) {
                obj._hasFocus = false;
                obj._updateNavButtons(Event.getTarget(ev), false);
            }, carousel);
        },

        /**
         * Return true if the Carousel is still animating, or false otherwise.
         *
         * @method isAnimating
         * @return {Boolean} Return true if animation is still in progress, or
         * false otherwise.
         * @public
         */
        isAnimating: function () {
            return this._isAnimationInProgress;
        },

        /**
         * Return true if the auto-scrolling of Carousel is "on", or false
         * otherwise.
         *
         * @method isAutoPlayOn
         * @return {Boolean} Return true if autoPlay is "on", or false
         * otherwise.
         * @public
         */
        isAutoPlayOn: function () {
            return this._isAutoPlayInProgress;
        },

        /**
         * Return the carouselItemEl at index or null if the index is not
         * found.
         *
         * @method getElementForItem
         * @param index {Number} The index of the item to be returned
         * @return {Element} Return the item at index or null if not found
         * @public
         */
        getElementForItem: function (index) {
            var carousel = this;

            if (index < 0 || index >= carousel.get("numItems")) {
                return null;
            }

            // TODO: may be cache the item
            if (carousel._itemsTable.numItems > index) {
                if (!JS.isUndefined(carousel._itemsTable.items[index])) {
                    return Dom.get(carousel._itemsTable.items[index].id);
                }
            }

            return null;
        },

        /**
         * Return the carouselItemEl for all items in the Carousel.
         *
         * @method getElementForItems
         * @return {Array} Return all the items
         * @public
         */
        getElementForItems: function () {
            var carousel = this, els = [], i;

            for (i = 0; i < carousel._itemsTable.numItems; i++) {
                els.push(carousel.getElementForItem(i));
            }

            return els;
        },

        /**
         * Return the item at index or null if the index is not found.
         *
         * @method getItem
         * @param index {Number} The index of the item to be returned
         * @return {Object} Return the item at index or null if not found
         * @public
         */
        getItem: function (index) {
            var carousel = this;

            if (index < 0 || index >= carousel.get("numItems")) {
                return null;
            }

            if (carousel._itemsTable.numItems > index) {
                if (!JS.isUndefined(carousel._itemsTable.items[index])) {
                    return carousel._itemsTable.items[index];
                }
            }

            return null;
        },

        /**
         * Return all items as an array.
         *
         * @method getItems
         * @return {Array} Return all items in the Carousel
         * @public
         */
        getItems: function (index) {
            return this._itemsTable.items;
        },

        /**
         * Return the position of the Carousel item that has the id "id", or -1
         * if the id is not found.
         *
         * @method getItemPositionById
         * @param index {Number} The index of the item to be returned
         * @public
         */
        getItemPositionById: function (id) {
            var carousel = this, i = 0, n = carousel._itemsTable.numItems;

            while (i < n) {
                if (!JS.isUndefined(carousel._itemsTable.items[i])) {
                    if (carousel._itemsTable.items[i].id == id) {
                        return i;
                    }
                }
                i++;
            }

            return -1;
        },

        /**
         * Return all visible items as an array.
         *
         * @method getVisibleItems
         * @return {Array} The array of visible items
         * @public
         */
        getVisibleItems: function () {
            var carousel = this,
                i        = carousel.get("firstVisible"),
                n        = i + carousel.get("numVisible"),
                r        = [];

            while (i < n) {
                r.push(carousel.getElementForItem(i));
                i++;
            }

            return r;
        },

        /**
         * Remove an item at index from the Carousel.
         *
         * @method removeItem
         * @public
         * @param index {Number} The position to where in the list (starts from
         * zero).
         * @return {Boolean} Return true on success, false otherwise
         */
        removeItem: function (index) {
            var carousel = this,
                item,
                num      = carousel.get("numItems");

            if (index < 0 || index >= num) {
                return false;
            }

            item = carousel._itemsTable.items.splice(index, 1);
            if (item && item.length == 1) {
                carousel._itemsTable.numItems--;
                carousel.set("numItems", num - 1);

                carousel.fireEvent(itemRemovedEvent,
                        { item: item[0], pos: index, ev: itemRemovedEvent });
                return true;
            }

            return false;
        },

        /**
         * Render the Carousel.
         *
         * @method render
         * @public
         * @param appendTo {HTMLElement | String} The element to which the
         * Carousel should be appended prior to rendering.
         * @return {Boolean} Status of the operation
         */
        render: function (appendTo) {
            var carousel = this,
                cssClass = carousel.CLASSES;

            carousel.addClass(cssClass.CAROUSEL);

            if (!carousel._clipEl) {
                carousel._clipEl = carousel._createCarouselClip();
                carousel._clipEl.appendChild(carousel._carouselEl);
            }

            if (appendTo) {
                carousel.appendChild(carousel._clipEl);
                carousel.appendTo(appendTo);
            } else {
                if (!Dom.inDocument(carousel.get("element"))) {
                    return false;
                }
                carousel.appendChild(carousel._clipEl);
            }

            if (carousel.get("isVertical")) {
                carousel.addClass(cssClass.VERTICAL);
            } else {
                carousel.addClass(cssClass.HORIZONTAL);
            }

            if (carousel.get("numItems") < 1) {
                return false;
            }

            carousel._refreshUi();

            return true;
        },

        /**
         * Scroll the Carousel by an item backward.
         *
         * @method scrollBackward
         * @public
         */
        scrollBackward: function () {
            var carousel = this;

            carousel.scrollTo(carousel._firstItem -
                              carousel.get("scrollIncrement"));
        },

        /**
         * Scroll the Carousel by an item forward.
         *
         * @method scrollForward
         * @public
         */
        scrollForward: function () {
            var carousel = this;

            carousel.scrollTo(carousel._firstItem +
                              carousel.get("scrollIncrement"));
        },

        /**
         * Scroll the Carousel by a page backward.
         *
         * @method scrollPageBackward
         * @public
         */
        scrollPageBackward: function () {
            var carousel = this,
                item     = carousel._firstItem - carousel.get("numVisible");

            if (carousel.get("selectOnScroll")) {
                carousel._selectedItem = carousel._getSelectedItem(item);
            } else {
                item = carousel._getValidIndex(item);
            }
            carousel.scrollTo(item);
        },

        /**
         * Scroll the Carousel by a page forward.
         *
         * @method scrollPageForward
         * @public
         */
        scrollPageForwa