controllerCarousel


carousel(list, radius, radius_z, dz, plane_angle, duration,
         back_scale, back_opacity, middle_opacity,
         ease_type, ease_amount,
         use_spring, acc, damping_factor)

carousel.messages = [update, reset, focus]
carousel.events   = [start, end, change]

Description

Creates a 3D carousel with items supplied by a list() controller. The carousel listens for the list's update, reset and focus events. It rotates upon change in the currently-focused item in the list, so that this item is displayed in the central front position. The elliptical path is described by parameters radius, radius_z, dz and plane_angle. Items in the back can have their size and opacity decreased (via parameters back_scale, back_opacity and middle_opacity). If use_spring is set, the items will gain inertia and move in a more 'physical' way, defined by parameters acc and damping_factor.

Applies one translate transform on each item of the carousel. Additionaly, one scale and one opacity transforms can also be applied on each item if back_scale, back_opacity or middle_opacity is different than 1.

Parameters

Visit page Controller # Common Parameters for documentation on the parameters, common to all controllers: id, paused and disabled.

Parameters of carousel():

list

A string containing the ID of the list() controller whose items will be displayed in the carousel. If the list() controller belongs to another element, then the string should also contain the ID of this element - "<DOM ID of element> <controller ID>" Default value: ""

radius

Major radius in pixels of the elliptical orbit, parallel to the layour plane. If parameter plane_angle is 0, then the major radius is parallel to the X axis of the element, and if plane_angle is 90 degrees, then the major radius will be parallel to the Y axis of the element. Default value: 200

radius_z

Minor radius of the elliptical orbit in pixels, parallel to the Z axis of the element (i.e. the scene's Z axis if no rotations are applied on the element). If set to a value of -1 (the default), then the minor radius will be of equal size as the major one. If you want the carousel to be "flat", all items being on the layout plane, do not give a value of 0, but some very small number, like 0.1. Default value: -1

dz

Displacement of the whole carousel on the Z axis, where positive values move the carousel closer to the camera. Setting such a displacement is useful when the carousel is onto a non-transparent background and the background hides all elements on the back side. Setting a value of dz equal or bigger than radius_z makes sure none of items are hidden behind the plane of the background. A value of -1 (the default) sets a displacement equal to the value of radius_z. Default value: -1

plane_angle

Sets the orientation of the elliptical path's plane, rotating it around the Z axis of the carousel. If set to a value of 0 (the default), then the major radius of the ellipse is parallel to the X axis of the element (horizontal carousel), and if set to a value of 90 degrees, then the major radius will be parallel to the Y axis of the element (vertical carousel). Default value: 0

back_scale

If additional 'depth' effect is required, instead of increasing radius_z as this can be a problem in some situations, set back_scale to a value lower than 1 (the default) and items will be more and more scaled down the further to the back they are (and while they move). At the farthest position (at radius_z distance from the carousel's center) items have their scale down to the value of back_scale. Default value: 1

back_opacity

Opacity of the items at the farthest position (at radius_z distance from the carousel's center). Items in the farther half of the carousel (as looked from the camera) have their opacity interpolated between back_opacity and middle_opacity. Default value: 1

middle_opacity

Opacity of the items when they are half-way between the closest-to-the-camera position and the farthest position. Items closer to the camera than this have their opacity interpolated between the value of middle_opacity and 1. Items farther than the middle have their opacity interpolated between the values of middle_opacity and back_opacity. Default value: 1

duration

Duration in milliseconds of the rotating animation. Default value: 1000

ease_type

What kind of 'easing' to be applied on the rotation movement.
Currently supported values:

"linear" - constant speed in all movement parts,
"ease" - slower start and end of movement,
"ease_in" - slower start, fast and sudden end,
"ease_out" - fast and sudden start, slow end.

Default value: "ease"

ease_amount

Strength of 'easing' to be applied on the rotation movement.
Values in the range (0 - 1] make sense, though values greater than 1 (up to 2-3) can also be of use. Default value: 1

Accepted Messages

Visit page Controller # Common Messages for documentation on the messages, accepted by all controllers: pause, unpause, enable, disable, params and remove.

Messages accepted by carousel():

update: Reads the current set of items of the list() controller. Sets CSS properties position, left, top and transform-origin of the items preparing them for the carousel. This message is called automatically upon a notification from the list() controller that its items have changed. Call this message manually after the width or height of any of the items changes. Message params: none
reset: Initializes rotation variables, setting the carousel in its initial position, with the first item in the list focused. This message is called automatically upon a notification from the list() controller that it has reset. Message params: none
focus: Sets the focus on the supplied item, rotating the carousel until the focused item is in the central front position. Message parameter focused must contain the index of the item to focus onto. Note that this message is called automatically upon a notification from the list() controller that it has changed its focused item. Message params: {focused: <item index>}

Generated Events

Visit page Controller # Common Events for documentation on the events, generated by all controllers: frame, remove, paused, unpaused enabled and disabled.

Events fired by carousel():

start: Fired upon starting the rotation animation. Event params: none
end: Fired upon reaching the end of the rotation animation. Event params: none
change: Also fired upon reaching the end of the rotation animation, but this event carries parameters pos and item telling which item is now focused. Event params: {pos: <index of selected item>, item: <reference to HTML element>}

Interaction with DOM

Transforms: Applies one translate transform on each item of the carousel. Additionaly, one scale transform will also be applied on each item if back_scale is different than 1.
CSS: The carousel element must have its style.position with value "absolute" or "relative". Each item has the following CSS properties set: position (set to absolute), top, left, transform-origin, and opacity (if any of the params back_opacity and middle_opacity is different than 1).
Events: Does not set DOM event listeners. Listens for the update, reset and focus events of the associated list() controller.

Changes Log

Controller introduced in v.0.80