/**
* Copyright (c) 2006-2007, Bill W. Scott
* All rights reserved.
*
* This work is licensed under the Creative Commons Attribution 2.5 License. To view a copy
* of this license, visit http://creativecommons.org/licenses/by/2.5/ or send a letter to
* Creative Commons, 543 Howard Street, 5th Floor, San Francisco, California, 94105, USA.
*
* This work was created by Bill Scott (billwscott.com, looksgoodworkswell.com).
*
* The only attribution I require is to keep this notice of copyright & license
* in this original source file.
*
* Version 1.0 - 10.21.2008
*
*/
YAHOO.namespace("extension");
/**
* @class
* The carousel class manages a content list (a set of LI elements within an UL list) that can be displayed horizontally or vertically. The content can be scrolled back and forth with or without animation. The content can reference static HTML content or the list items can be created dynamically on-the-fly (with or without Ajax). The navigation and event handling can be externalized from the class.
* @param {object|string} carouselElementID The element ID (id name or id object) of the DIV that will become a carousel
* @param {object} carouselCfg The configuration object literal containing the configuration that should be set for this module. See configuration documentation for more details.
* @constructor
*/
YAHOO.extension.Carousel = function(carouselElementID, carouselCfg) {
this.init(carouselElementID, carouselCfg);
};
YAHOO.extension.Carousel.prototype = {
/**
* Constant denoting that the carousel size is unbounded (no limits set on scrolling)
* @type number
*/
UNBOUNDED_SIZE: 1000000,
/**
* Initializes the carousel object and all of its local members.
* @param {object|string} carouselElementID The element ID (id name or id object)
* of the DIV that will become a carousel
* @param {object} carouselCfg The configuration object literal containing the
* configuration that should be set for this module. See configuration documentation for more details.
*/
init: function(carouselElementID, carouselCfg) {
var oThis = this;
/**
* For deprecation.
* getItem is the replacement for getCarouselItem
*/
this.getCarouselItem = this.getItem;
// CSS style classes
var carouselListClass = "carousel-list";
var carouselClipRegionClass = "carousel-clip-region";
var carouselNextClass = "carousel-next";
var carouselPrevClass = "carousel-prev";
this._carouselElemID = carouselElementID;
this.carouselElem = YAHOO.util.Dom.get(carouselElementID);
this._prevEnabled = true;
this._nextEnabled = true;
// Create the config object
this.cfg = new YAHOO.util.Config(this);
/**
* scrollBeforeAmount property.
* Normally, set to 0, this is how much you are allowed to
* scroll below the first item. Setting it to 2 allows you
* to scroll to the -1 position.
* However, the load handlers will not be asked to load anything
* below 1.
*
* A good example is the spotlight example which treats the middle item
* as the "selected" item. It sets scrollBeforeAmount to 2 and
* scrollAfterAmount to 2.
*
* The actual items loaded would be from 1 to 15 (size=15),
* but scrolling range would be -1 to 17.
*/
this.cfg.addProperty("scrollBeforeAmount", {
value:0,
handler: function(type, args, carouselElem) {
},
validator: oThis.cfg.checkNumber
} );
/**
* scrollAfterAmount property.
* Normally, set to 0, this is how much you are allowed to
* scroll past the size. Setting it to 2 allows you
* to scroll to the size+scrollAfterAmount position.
* However, the load handlers will not be asked to load anything
* beyond size.
*
* A good example is the spotlight example which treats the middle item
* as the "selected" item. It sets scrollBeforeAmount to 2 and
* scrollAfterAmount to 2.
*
* The actual items loaded would be from 1 to 15 (size=15),
* but scrolling range would be -1 to 17.
*/
this.cfg.addProperty("scrollAfterAmount", {
value:0,
handler: function(type, args, carouselElem) {
},
validator: oThis.cfg.checkNumber
} );
/**
* loadOnStart property.
* If true, will call loadInitHandler on startup.
* If false, will not. Useful for delaying the initialization
* of the carousel for a later time after creation.
*/
this.cfg.addProperty("loadOnStart", {
value:true,
handler: function(type, args, carouselElem) {
// no action, only affects startup
},
validator: oThis.cfg.checkBoolean
} );
/**
* orientation property.
* Either "horizontal" or "vertical". Changes carousel from a
* left/right style carousel to a up/down style carousel.
*/
this.cfg.addProperty("orientation", {
value:"horizontal",
handler: function(type, args, carouselElem) {
oThis.reload();
},
validator: function(orientation) {
if(typeof orientation == "string") {
return ("horizontal,vertical".indexOf(orientation.toLowerCase()) != -1);
} else {
return false;
}
}
} );
/**
* size property.
* The upper bound for scrolling in the 'next' set of content.
* Set to a large value by default (this means unlimited scrolling.)
*/
this.cfg.addProperty("size", {
value:this.UNBOUNDED_SIZE,
handler: function(type, args, carouselElem) {
oThis.reload();
},
validator: oThis.cfg.checkNumber
} );
/**
* numVisible property.
* The number of items that will be visible.
*/
this.cfg.addProperty("numVisible", {
value:3,
handler: function(type, args, carouselElem) {
oThis.reload();
},
validator: oThis.cfg.checkNumber
} );
/**
* firstVisible property.
* Sets which item should be the first visible item in the carousel. Use to set which item will
* display as the first element when the carousel is first displayed. After the carousel is created,
* you can manipulate which item is the first visible by using the moveTo() or scrollTo() convenience
* methods. Can be < 1 or greater than size if the scrollBeforeAmount or scrollAmountAfter has been set
* to non-zero values.
*/
this.cfg.addProperty("firstVisible", {
value:1,
handler: function(type, args, carouselElem) {
oThis.moveTo(args[0]);
},
validator: oThis.cfg.checkNumber
} );
/**
* scrollInc property.
* The number of items to scroll by. Think of this as the page increment.
*/
this.cfg.addProperty("scrollInc", {
value:3,
handler: function(type, args, carouselElem) {
},
validator: oThis.cfg.checkNumber
} );
/**
* animationSpeed property.
* The time (in seconds) it takes to complete the scroll animation.
* If set to 0, animated transitions are turned off and the new page of content is
* moved immdediately into place.
*/
this.cfg.addProperty("animationSpeed", {
value:0.25,
handler: function(type, args, carouselElem) {
oThis.animationSpeed = args[0];
},
validator: oThis.cfg.checkNumber
} );
/**
* animationMethod property.
* The YAHOO.util.Easing
* method.
*/
this.cfg.addProperty("animationMethod", {
value: YAHOO.util.Easing.easeOut,
handler: function(type, args, carouselElem) {
}
} );
/**
* animationCompleteHandler property.
* JavaScript function that is called when the Carousel finishes animation
* after a next or previous nagivation.
* Only invoked if animationSpeed > 0.
* Two parameters are passed: type (set to 'onAnimationComplete') and
* args array (args[0] = direction [either: 'next' or 'previous']).
*/
this.cfg.addProperty("animationCompleteHandler", {
value:null,
handler: function(type, args, carouselElem) {
if(oThis._animationCompleteEvt) {
oThis._animationCompleteEvt.unsubscribe(oThis._currAnimationCompleteHandler, oThis);
}
oThis._currAnimationCompleteHandler = args[0];
if(oThis._currAnimationCompleteHandler) {
if(!oThis._animationCompleteEvt) {
oThis._animationCompleteEvt = new YAHOO.util.CustomEvent("onAnimationComplete", oThis);
}
oThis._animationCompleteEvt.subscribe(oThis._currAnimationCompleteHandler, oThis);
}
}
} );
/**
* autoPlay property.
* Specifies how many milliseconds to periodically auto scroll the content.
* If set to 0 (default) then autoPlay is turned off.
* If the user interacts by clicking left or right navigation, autoPlay is turned off.
* You can restart autoPlay by calling the startAutoPlay().
* If you externally control navigation (with your own event handlers)
* then you may want to turn off the autoPlay by callingstopAutoPlay()
*/
this.cfg.addProperty("autoPlay", {
value:0,
handler: function(type, args, carouselElem) {
var autoPlay = args[0];
if(autoPlay > 0)
oThis.startAutoPlay();
else
oThis.stopAutoPlay();
}
} );
/**
* wrap property.
* Specifies whether to wrap when at the end of scrolled content. When the end is reached,
* the carousel will scroll backwards to the item 1 (the animationSpeed parameter is used to
* determine how quickly it should animate back to the start.)
* Ignored if the size attribute is not explicitly set
* (i.e., value equals YAHOO.extension.Carousel.UNBOUNDED_SIZE)
*/
this.cfg.addProperty("wrap", {
value:false,
handler: function(type, args, carouselElem) {
},
validator: oThis.cfg.checkBoolean
} );
/**
* navMargin property.
* The margin space for the navigation controls. This is only useful for horizontal carousels
* in which you have embedded navigation controls.
* The navMargin allocates space between the left and right margins
* (each navMargin wide) giving space for the navigation controls.
*/
this.cfg.addProperty("navMargin", {
value:0,
handler: function(type, args, carouselElem) {
oThis.calculateSize();
},
validator: oThis.cfg.checkNumber
} );
/**
* revealAmount property.
* The amount to reveal of what comes before and what comes after the firstVisible and
* the lastVisible items. Setting this will provide a slight preview that something
* exists before and after, providing an additional hint for the user.
* The revealAmount will reveal the specified number of pixels for any item
* before the firstVisible and an item after the lastVisible. Additionall, the
* loadNextHandler and loadPrevHandler methods will be passed a start or end that guarantees
* the revealed item will be loaded (if set to non-zero).
*/
this.cfg.addProperty("revealAmount", {
value:0,
handler: function(type, args, carouselElem) {
oThis.reload();
},
validator: oThis.cfg.checkNumber
} );
// For backward compatibility. Deprecated.
this.cfg.addProperty("prevElementID", {
value: null,
handler: function(type, args, carouselElem) {
if(oThis._carouselPrev) {
YAHOO.util.Event.removeListener(oThis._carouselPrev, "click", oThis._scrollPrev);
}
oThis._prevElementID = args[0];
if(oThis._prevElementID == null) {
oThis._carouselPrev = YAHOO.util.Dom.getElementsByClassName(carouselPrevClass,
"div", oThis.carouselElem)[0];
} else {
oThis._carouselPrev = YAHOO.util.Dom.get(oThis._prevElementID);
}
YAHOO.util.Event.addListener(oThis._carouselPrev, "click", oThis._scrollPrev, oThis);
}
});
/**
* prevElement property.
* An element or elements that will provide the previous navigation control.
* prevElement may be a single element or an array of elements. The values may be strings denoting
* the ID of the element or the object itself.
* If supplied, then events are wired to this control to fire scroll events to move the carousel to
* the previous content.
* You may want to provide your own interaction for controlling the carousel. If
* so leave this unset and provide your own event handling mechanism.
*/
this.cfg.addProperty("prevElement", {
value:null,
handler: function(