Prototype-UI
Release Candidate 0
Utilities
Carousel
Shadow
Window
WindowManager
Index

UI. Carousel

Main class to handle a carousel of elements in a page.  A carousel :

  • could be vertical or horizontal
  • works with liquid layout
  • is designed by CSS

Assumptions

  • Elements should be from the same size

Example

...
<div id="horizontal_carousel">
  <div class="previous_button"></div>
  <div class="container">
    <ul>
      <li> What ever you like</li>
    </ul>
  </div>
  <div class="next_button"></div>
</div>
<script>
new UI.Carousel("horizontal_carousel");
</script>
...
Summary
UI. Carousel
Main class to handle a carousel of elements in a page.
Options
direction
Can be horizontal or vertical, horizontal by default
previousButton
Selector of previous button inside carousel element, “.previous_button” by default, set it to false to ignore previous button
nextButton
Selector of next button inside carousel element, “.next_button” by default, set it to false to ignore next button
container
Selector of carousel container inside carousel element, “.container” by default,
scrollInc
Define the maximum number of elements that gonna scroll each time, auto by default
disabledButtonSuffix
Define the suffix classanme used when a button get disabled, to ‘_disabled’ by default Previous button classname will be previous_button_disabled
overButtonSuffix
Define the suffix classanme used when a button has a rollover status, ‘_over’ by default Previous button classname will be previous_button_over
Attributes
element
DOM element containing the carousel
id
DOM id of the carousel’s element
container
DOM element containing the carousel’s elements
elements
Array containing the carousel’s elements as DOM elements
previousButton
DOM id of the previous button
nextButton
DOM id of the next button
posAttribute
Define if the positions are from left or top
dimAttribute
Define if the dimensions are horizontal or vertical
elementSize
Size of each element, it’s an integer
nbVisible
Number of visible elements, it’s a float
animating
Define whether the carousel is in animation or not
Events
List of events fired by a carousel
previousButton: enabled
Fired when the previous button has just been enabled
previousButton: disabled
Fired when the previous button has just been disabled
nextButton: enabled
Fired when the next button has just been enabled
nextButton: disabled
Fired when the next button has just been disabled
scroll: started
Fired when a scroll has just started
scroll: ended
Fired when a scroll has been done, memo.shift = number of elements scrolled, it’s a float
sizeUpdated
Fired when the carousel size has just been updated.
Constructor
initialize
Constructor function, should not be called directly
Destructor
destroy
Cleans up DOM and memory
Event handling
fire
Fires a carousel custom event automatically namespaced in “carousel:” (see Prototype custom events).
observe
Observe a carousel event with a handler function automatically bound to the carousel
stopObserving
Unregisters a carousel event, it must take the same parameters as this.observe (see Prototype stopObserving).
Actions
checkScroll
Check scroll position to avoid unused space at right or bottom
scroll
Scrolls carousel from maximum deltaPixel
scrollTo
Scrolls carousel, so that element with specified index is the left-most.
updateButtons
Update buttons status to enabled or disabled Them status is defined by classNames and fired as carousel’s custom events
Size and Position
computeElementSize
Return elements size in pixel, height or width depends on carousel orientation.
currentIndex
Returns current visible index of a carousel.
currentLastPosition
Returns the current position from the end of the last element.
currentPosition
Returns the current position in pixel.
currentSize
Returns the current size of the carousel in pixel
updateSize
Should be called if carousel size has been changed (usually called with a liquid layout)

Options

direction

Can be horizontal or vertical, horizontal by default

previousButton

Selector of previous button inside carousel element, “.previous_button” by default, set it to false to ignore previous button

nextButton

Selector of next button inside carousel element, “.next_button” by default, set it to false to ignore next button

container

Selector of carousel container inside carousel element, “.container” by default,

scrollInc

Define the maximum number of elements that gonna scroll each time, auto by default

disabledButtonSuffix

Define the suffix classanme used when a button get disabled, to ‘_disabled’ by default Previous button classname will be previous_button_disabled

overButtonSuffix

Define the suffix classanme used when a button has a rollover status, ‘_over’ by default Previous button classname will be previous_button_over

Attributes

element

DOM element containing the carousel

id

DOM id of the carousel’s element

container

DOM element containing the carousel’s elements

elements

Array containing the carousel’s elements as DOM elements

previousButton

DOM id of the previous button

nextButton

DOM id of the next button

posAttribute

Define if the positions are from left or top

dimAttribute

Define if the dimensions are horizontal or vertical

elementSize

Size of each element, it’s an integer

nbVisible

Number of visible elements, it’s a float

animating

Define whether the carousel is in animation or not

Events

List of events fired by a carousel

Notice: Carousel custom events are automatically namespaced in “carousel:” (see Prototype custom events).

Examples

This example will observe all carousels

document.observe('carousel:scroll:ended', function(event) {
  alert("Carousel with id " + event.memo.carousel.id + " has just been scrolled");
});

This example will observe only this carousel

new UI.Carousel('horizontal_carousel').observe('scroll:ended', function(event) {
  alert("Carousel with id " + event.memo.carousel.id + " has just been scrolled");
});

previousButton: enabled

Fired when the previous button has just been enabled

previousButton: disabled

Fired when the previous button has just been disabled

nextButton: enabled

Fired when the next button has just been enabled

nextButton: disabled

Fired when the next button has just been disabled

scroll: started

Fired when a scroll has just started

scroll: ended

Fired when a scroll has been done, memo.shift = number of elements scrolled, it’s a float

sizeUpdated

Fired when the carousel size has just been updated.  Tips: memo.carousel.currentSize() = the new carousel size

Constructor

initialize

initialize: function(element,
options)

Constructor function, should not be called directly

Parameters

elementDOM element
options(Hash) list of optional parameters

Returns

this

Destructor

destroy

destroy: function($super)

Cleans up DOM and memory

Event handling

fire

fire: function(eventName,
memo)

Fires a carousel custom event automatically namespaced in “carousel:” (see Prototype custom events).  The memo object contains a “carousel” property referring to the carousel.

Example

document.observe('carousel:scroll:ended', function(event) {
  alert("Carousel with id " + event.memo.carousel.id + " has just been scrolled");
});

Parameters

eventNamean event name
memoa memo object

Returns

fired event

observe

observe: function(eventName,
handler)

Observe a carousel event with a handler function automatically bound to the carousel

Parameters

eventNamean event name
handlera handler function

Returns

this

stopObserving

stopObserving: function(eventName,
handler)

Unregisters a carousel event, it must take the same parameters as this.observe (see Prototype stopObserving).

Parameters

eventNamean event name
handlera handler function

Returns

this

Actions

checkScroll

checkScroll: function(position,
updatePosition)

Check scroll position to avoid unused space at right or bottom

Parameters

positionposition to check
updatePositionshould the container position be updated ? true/false

Returns

position

scroll

scroll: function(deltaPixel)

Scrolls carousel from maximum deltaPixel

Parameters

deltaPixela float

Returns

this

scrollTo

scrollTo: function(index)

Scrolls carousel, so that element with specified index is the left-most.  This method is convenient when using carousel in a tabbed navigation.  Clicking on first tab should scroll first container into view, clicking on a fifth - fifth one, etc.  Indexing starts with 0.

Parameters

Index of an element which will be a left-most visible in the carousel

Returns

this

updateButtons

updateButtons: function()

Update buttons status to enabled or disabled Them status is defined by classNames and fired as carousel’s custom events

Returns

this

Size and Position

computeElementSize

computeElementSize: function()

Return elements size in pixel, height or width depends on carousel orientation.

Returns

an integer value

currentIndex

currentIndex: function()

Returns current visible index of a carousel.  For example, a horizontal carousel with image #3 on left will return 3 and with half of image #3 will return 3.5 Don’t forget that the first image have an index 0

Returns

a float value

currentLastPosition

currentLastPosition: function()

Returns the current position from the end of the last element.  This value is in pixel.

Returns

an integer value, if no images a present it will return 0

currentPosition

currentPosition: function()

Returns the current position in pixel.  Tips: To get the position in elements use currentIndex()

Returns

an integer value

currentSize

currentSize: function()

Returns the current size of the carousel in pixel

Returns

Carousel’s size in pixel

updateSize

updateSize: function()

Should be called if carousel size has been changed (usually called with a liquid layout)

Returns

this
Generated by Natural Docs
initialize: function(element,
options)
Constructor function, should not be called directly
destroy: function($super)
Cleans up DOM and memory
fire: function(eventName,
memo)
Fires a carousel custom event automatically namespaced in “carousel:” (see Prototype custom events).
observe: function(eventName,
handler)
Observe a carousel event with a handler function automatically bound to the carousel
stopObserving: function(eventName,
handler)
Unregisters a carousel event, it must take the same parameters as this.observe (see Prototype stopObserving).
checkScroll: function(position,
updatePosition)
Check scroll position to avoid unused space at right or bottom
scroll: function(deltaPixel)
Scrolls carousel from maximum deltaPixel
scrollTo: function(index)
Scrolls carousel, so that element with specified index is the left-most.
updateButtons: function()
Update buttons status to enabled or disabled Them status is defined by classNames and fired as carousel’s custom events
computeElementSize: function()
Return elements size in pixel, height or width depends on carousel orientation.
currentIndex: function()
Returns current visible index of a carousel.
currentLastPosition: function()
Returns the current position from the end of the last element.
currentPosition: function()
Returns the current position in pixel.
currentSize: function()
Returns the current size of the carousel in pixel
updateSize: function()
Should be called if carousel size has been changed (usually called with a liquid layout)