Carousel
Abstract

A virtualized container of items that can be scrolled either horizontally or vertically. As scrolling occurs, a configured number of visible items (slots) are dynamically positioned and reconfigured to give the appearance that all items in the specified range are present.

To create a carousel, a configureSlot function must be provided that will return the configuration object for a given slot index. Slot index 0 is special, and whenever the range is not empty, 0 must be included in the range. The meaning of a slot index, however, is defined by the developer and only interpreted by the developer-provided configureSlot function.

Slot indexes are converted into virtual scroll positions and given to an InfinityScroller. This special scroller allows for negative scroll positioning as well as unbounded scroll range.

This widget is not intended to be used standalone, but as part of higher-level widgets such as MultiDatePicker.

No results

Configs

Configs are options you supply in a configuration object when creating an instance of this class

configureSlot : String/Function
A callback function that must be provided by the developer to produce configuration objects for the slots in the carousel.

Derived classes may set this config to the name of the instance method to call. The this pointer will be the carousel instance.
Parameters
- index : Number
  
  The slot index as defined by the range of the carousel.
- carousel : Carousel
  
  The carousel instance.
- slot : Widget
  
  The slot being reconfigured or null when creating a new slot.
Returns

WidgetConfig
:

The slot's configuration object.
Has a corresponding runtime configureSlot property.
currentIndex : Number

The first visible slot index. This first visible slot can be read or written using this property. Setting currentIndex will determine if the transition can be animated by the distance being traveled.

See goto.

Has a corresponding runtime currentIndex property.
disableReserveSlots : Boolean/'inert'false

The value to set for the disabled config on reserve slots. These slots are not visible to the user but can be tabbed into from visible slots.

When set to 'inert', the inert DOM attribute is also set. This prevents tabbing from a visible slot to a reserved slot.
emptyHtml : String

The HTML to render when the carousel's range is empty. To avoid XSS attacks, it is safer to use emptyText instead.

Has a corresponding runtime emptyHtml property.
emptyText : StringNo items to display

The text to render when the carousel's range is empty. This text is automatically encoded and is safe from XSS issues. To render markup when the carousel is empty, see emptyHtml.

Has a corresponding runtime emptyText property.
range : Number[]

The range of slot indexes to be presented in the carousel. Slot indexes greater than or equal to range[0] and less than range[1] will be rendered.

If this value is null or [0, 0], the carousel will render no items (i.e., it will be empty). See emptyText.

By default, the carousel's range is unlimited, i.e., range = [-Infinity, Infinity].

Has a corresponding runtime range property.
reserveSlots : Number1

The number of slots to render beyond what is visible in the carousel. These reserve items are critical to giving the appearance of continuity as the carousel is being scrolled. A minimum of 1 is required and is generally sufficient for slots that are reasonably large. If slots are small (maybe less than 100px), it may be helpful to provide additional reserve slots.

Has a corresponding runtime reserveSlots property.
scrollOnTab : Booleanfalse

Set to true to use trapFocus to scroll the carousel when tabbing to slots that are not currently visible.

NOTE: This only works when configureSlot produces Panel instances.

Has a corresponding runtime scrollOnTab property.
shrinkWrap : Boolean/'auto'auto

Due to the position: absolute nature of carousel items, a carousel does not have a natural size. When the carousel is being sized by its container, this is not a problem, but can be an issue if the carousel is being used in a layout where its natural size would be important.

Specify true for the carousel to provide a natural size based on the size of its slots. This is done by setting min-width and/or min-height on the internal elements that contain the absolutely positioned slots. This may have a modest performance impact due to the required measuring of the slots to provide these minimums.

By default (shrinkWrap = 'auto'), the carousel enables shrinkWrap support when the carousel's main element is position: absolute. This can be disabled by setting shrinkWrap = false.

Has a corresponding runtime shrinkWrap property.
slots : Number

The number of slots to present in the carousel. When set to a number, each slot is given a percentage size (e.g., "50%" for slots = 2) so they fill the carousel. This is typically required when the carousel is using shrinkWrap (note: shrink wrapping is enabled by default for position: absolute carousels).

When null, as many slots as needed to fill the carousel are created. This can produce partially visible slots.

Setting this value to 'auto' will similarly fill the available space, but once the required number of slots is determined, they are assigned a percentage size so that they completely fill the carousel.

Has a corresponding runtime slots property.
snap : Booleantrue

Set to false to disable scroll snapping and allow free scrolling through the carousel.

Has a corresponding runtime snap property.
vertical : Booleanfalse

Set to true to enable vertical mode. By default, carousels scroll horizontally.

Has a corresponding runtime vertical property.

Properties

Properties are getters/setters or publicly accessible variables on this class

isCarousel : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of Carousel class, or subclass thereof.

configureSlot : String/Function

A callback function that must be provided by the developer to produce configuration objects for the slots in the carousel.

Derived classes may set this config to the name of the instance method to call. The this pointer will be the carousel instance.

Has a corresponding configureSlot config.
currentIndex : Number

The first visible slot index. This first visible slot can be read or written using this property. Setting currentIndex will determine if the transition can be animated by the distance being traveled.

See goto.

Has a corresponding currentIndex config.
emptyHtml : String

The HTML to render when the carousel's range is empty. To avoid XSS attacks, it is safer to use emptyText instead.

Has a corresponding emptyHtml config.
emptyText : StringNo items to display

The text to render when the carousel's range is empty. This text is automatically encoded and is safe from XSS issues. To render markup when the carousel is empty, see emptyHtml.

Has a corresponding emptyText config.
range : Number[]

The range of slot indexes to be presented in the carousel. Slot indexes greater than or equal to range[0] and less than range[1] will be rendered.

If this value is null or [0, 0], the carousel will render no items (i.e., it will be empty). See emptyText.

By default, the carousel's range is unlimited, i.e., range = [-Infinity, Infinity].

Has a corresponding range config.
reserveSlots : Number1

The number of slots to render beyond what is visible in the carousel. These reserve items are critical to giving the appearance of continuity as the carousel is being scrolled. A minimum of 1 is required and is generally sufficient for slots that are reasonably large. If slots are small (maybe less than 100px), it may be helpful to provide additional reserve slots.

Has a corresponding reserveSlots config.
scrollOnTab : Booleanfalse

Set to true to use trapFocus to scroll the carousel when tabbing to slots that are not currently visible.

NOTE: This only works when configureSlot produces Panel instances.

Has a corresponding scrollOnTab config.
scrolling : Boolean

READONLY

This will yield true when the carousel is currently scrolling.
shrinkWrap : Boolean/'auto'auto

Due to the position: absolute nature of carousel items, a carousel does not have a natural size. When the carousel is being sized by its container, this is not a problem, but can be an issue if the carousel is being used in a layout where its natural size would be important.

Specify true for the carousel to provide a natural size based on the size of its slots. This is done by setting min-width and/or min-height on the internal elements that contain the absolutely positioned slots. This may have a modest performance impact due to the required measuring of the slots to provide these minimums.

By default (shrinkWrap = 'auto'), the carousel enables shrinkWrap support when the carousel's main element is position: absolute. This can be disabled by setting shrinkWrap = false.

Has a corresponding shrinkWrap config.
slots : Number

The number of slots to present in the carousel. When set to a number, each slot is given a percentage size (e.g., "50%" for slots = 2) so they fill the carousel. This is typically required when the carousel is using shrinkWrap (note: shrink wrapping is enabled by default for position: absolute carousels).

When null, as many slots as needed to fill the carousel are created. This can produce partially visible slots.

Setting this value to 'auto' will similarly fill the available space, but once the required number of slots is determined, they are assigned a percentage size so that they completely fill the carousel.

Has a corresponding slots config.
snap : Booleantrue

Set to false to disable scroll snapping and allow free scrolling through the carousel.

Has a corresponding snap config.
vertical : Booleanfalse

Set to true to enable vertical mode. By default, carousels scroll horizontally.

Has a corresponding vertical config.
isCarousel : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of Carousel class, or subclass thereof.

Functions

Functions are methods available for calling on the class

backward( animate )

Step the carousel back one slot index.
ensurePlan( options )
: Object

internal

Decodes any options specified to a derived class that may be passed to ensureVisible. This method ensures the options object has the properties needed by ensureVisible.
ensureVisible( options )

Ensures that the given slot index is visible, scrolling if necessary to make it so.
forward( animate )

Step the carousel forward one slot index. See go.
go( increment, animate )

Steps the slot index of the carousel forward or backward by the given increment.
goto( index, animate )

Sets the slot index of the carousel to the given index.
indexFromPos( pos )
: Number

Returns the carousel slot index given a logical scroll position (see InfinityScroller).
posFromIndex( index )
: Number

Returns the logical scroll position (see InfinityScroller) given a carousel slot index.
sync( )

internal

Synchronizes the scroll range and child items based on the current configuration and scroll position. This is called in response to scroll events and when the carousel is reconfigured.

Carousel
Abstract

Configs

Parameters

Returns

Properties

Functions

Source path

Inheritance tree5

Mixins7

Contents

Carousel Abstract

Configs

Parameters

Returns

Properties

Functions

Source path

Inheritance tree5

Mixins7

Contents

Carousel
Abstract