Class s7sdk.set.CarouselView

The CarouselView is an image viewing component that displays images served by Adobe Scene7 Image Serving that are combined into an image set. The CarouselView may automatically load nearby frames in the background to make the frame transition responsive and smooth, this behavior is controlled with maxloadradius modifier.

The component does not support zoom. It always renders an image in reset state.

Customizing Behavior Using Modifiers

Modifiers change CarouselView default behavior. They are passed to the component by the ParameterManager instance specified in the constructor.

The following modifiers are supported:

Modifier	Syntax	Description	Default
serverurl	isRootPath	The Image Serving root path. If no domain is specified, the domain from which the page is served is applied instead. Standard URI path resolution applies.	/is/image/
asset	imageSet	The Image Serving catalog or asset ID of a named eCatalog set whose definition comes from the server by means of the `req=set` command.	""
direction	auto\|left\|right	Specifies the way pages are displayed in the view. `left` sets a left-to-right display order and `right` reverses the order so that pages are displayed right-to-left. When `auto` is set, the component applies `right` mode when `locale` is set to "ja". Otherwise, `left` is used.	auto
iscommand	value	The Image Serving command string that is applied to all swatches. If specified in the URL all occurrences of '&' and '=' must be HTTP-encoded as `%26` and `%3D`, respectively.	""
frametransition	[none\|fade\|slide][,duration][,spacing]	Specifies the type and duration of the effect applied on frame change. Set `none` for no transition; frame change occurs instantly. Set `fade` to cross-fade the transition between old and new frames, with transition duration in seconds controlled by duration. Set `slide` to activate the transition where the old frame slides out of the view and the new frame slides in. Slide animation duration is also controlled by duration. The spacing between adjacent frames is controlled with spacing. The spacing has the range between `0` and `1` and is relative to the component's width.	none
maxloadradius	-1\|0\|preloadnbr	Specifies the component preload behavior. When set to `-1`, the component preloads all image set frames when in an idle state. `0` disables preload. Use preloadnbr to define how many invisible frames around the currently displayed frame are preloaded in an idle state.	0
enableHD	always\|never\|limit,<number>	Enable, limit, or disable optimization for devices where `devicePixelRatio` is greater than 1. If using the `limit` setting, the largest value that works for all devices is the value of the larger of width or height for the Reply Image Size Limit setting in Scene7 Publishing System (see Setup > Application Setup > Publish Setup > Image Server, then look under the Request Attributes heading.)	limit,1500
fmt	jpg\|jpeg\|png\|png-alpha\|gif\|gif-alpha	Specifies the image format for the component to use for loading images from Image Server. If the specified format ends with "-alpha", the component renders images as transparent. For all other image formats, the component treats images as opaque. Note that the component has a white background by default. Therefore, to make it completely transparent set the `background-color` CSS property to `transparent`	jpeg
autoPlay	[0\|1][,duration][,direction]	Specifies on/off, duration to display each banner in the carousel and direction of auto-loop. Set `0` for auto-loop off. Set `1` to auto-loop on with transition duration in seconds controlled by duration. The direction of auto-loop is controlled with direction. The direction has the range between `1` right-to-left and `0` left-to-right.	0,2,1

Defining Appearance using CSS

You can define the appearance of the CarouselView component using CSS rules. All HTML5 Viewer SDK components use class selectors for styling. You can style the body of the CarouselView component by using the .s7carouselview class selector. The styles that are associated with this class selector are applied to all instances of the CarouselView component. You can style particular instances by prefixing the class rule with the instance #id. For example, styling rules for #myComp.s7carouselview are applied only to the particular CarouselView instance.

For more information on component styling see the HTML5 Viewer SDK User Guide and the default styles section.

CSS Class	Attribute Selector	Description
`.s7carouselview`	(None)	Represents the main body of the `CarouselView` component.

Localized Symbols

CarouselView also has text symbols that you can localize either in a preset or in the viewer page though the mechanisms provided by the ParameterManager. For more information on localization consult the ParameterManager API documentation and HTML5 Viewers SDK User Guide.

Symbol	Description
`CarouselView.ROLE_DESCRIPTION`	Define a localized "aria-roledescription" of `CarouselView`
`CarouselView.USAGE_HINT`	Define a localized text for "aria-describedby" of `CarouselView`

Class Summary
Constructor Attributes	Constructor Name and Description
	s7sdk.set.CarouselView(container, settings, compId)

Method Summary
Method Attributes	Method Name and Description
	addEventListener(type, handler, useCapture) Adds an event listener to the instance of the `CarouselView` component.
	autoPlayPause() Pauses auto-play animation.
	autoPlayResume() Resumes the auto-play animation if it is configured using `autoPlay` modifier but was paused with `autoPlayPause()` call.
	dispose() Dispose is used to remove itself and all sub-elements from the DOM
	getAutoPlay() Return autoplay permission.
	getCapabilityState() Returns the current capabilities of the `CarouselView` instance.
	getCurrentFrameIndex() Returns current frame index.
	getHeight() Returns the current inner height of the component.
	getWidth() Returns the current inner width of the component.
	imagePixelsToViewPoint(inPt) Converts a point from the top resolution image coordinates to view coordinates.
	nextPage() Go to next page.
	prevPage() Go to previous page.
	resize(w, h) Sets `CarouselView` to the specified width and height.
	setAsset(assetName) Changes the currently displayed set.
	setAutoPlay(val) Set autoplay permission.
	setCSS(classname, property, value) Sets a particular CSS class and property on a component
	setCurrentFrameIndex(idx) Set current frame to specific index.
	setMediaSet(mediaSet) Sets the image or eCatalog set or `OrientationSetDesc` instance which contains two instances of `MediaSetDesc` for landscape and portrait orientations separately.
	setModifier(modObj) Sets 1-N # of modifiers for the component.

Class Detail

s7sdk.set.CarouselView(container, settings, compId)

Example Code
This example demonstrates how to use the CarouselView component in a simple viewer. In this example a Container object, MediaSet,
ImageMapEffect, buttons and a CarouselView object are created. 
The code below does the following:

The Scene7 HTML5 SDK is linked to the page and the required s7sdk components are included in the document head.
CSS Styles are defined in the document head to control the appearance of the SDK components.
The s7sdk.Util.init() method is called to initialize the SDK.
A ParameterManager object is created to handle component modifiers for the viewer.
An initViewer() function is defined. This function initializes a couple of modifiers (hard coded for example purposes),
then creates the component objects required for this simple example. The initViewer() function also adds event listeners
that designate functions to handle relevant component events (which might be dispatched by the components as a result of
user interactions, changes in a component's state, etc.).
Handler functions are defined to respond to the component event listeners added in the initViewer() function.
An event listener is added to the ParameterManager object that designates the initViewer() function as the handler
to call when the Scene7 SDK is loaded and ready.
Finally, the init() method is called on the ParameterManager object to start the viewer.

<!DOCTYPE html>
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<meta name="viewport" content="width=device-width" />
	<title>CarouselView Example</title>

        <style type="text/css" media="screen">
            html,body {
                width: 100%;
                height: 100%;
            }
            body {
                margin: 0px;
                padding: 0px;
            }	
			.s7carouselview {
				top: 10px;
				left: 10px;
				height: 360px;
				width: 360px;
			}
            .s7panleftbutton {
                position: absolute;
                top: 470px;
                left: 0px;
            }
            .s7panrightbutton {
                position: absolute;
                top: 470px;
                left: 335px;
            }
            .s7setindicator {
                top: 470px;
                left: 10px;
                height: 60px;
                width: 360px;
				position:absolute;
            }
	</style>

<script language="javascript" type="text/javascript" src="../js/s7sdk/utils/Utils.js"></script>
<script language="javascript" type="text/javascript">
    s7sdk.Util.lib.include('s7sdk.common.Container');
    s7sdk.Util.lib.include('s7sdk.common.Button');
	s7sdk.Util.lib.include('s7sdk.event.Event');
	s7sdk.Util.lib.include('s7sdk.set.MediaSet');
	s7sdk.Util.lib.include('s7sdk.set.CarouselView');
	s7sdk.Util.lib.include('s7sdk.image.ImageMapEffect');
    s7sdk.Util.lib.include('s7sdk.set.SetIndicator');
</script>

</head>
<body>

	<script language="JavaScript" type="text/javascript">
		s7sdk.Util.init();
		var params = new s7sdk.ParameterManager(null,null,{"asset" : "MediaSet.asset"});
		// Assign new localized values for SYMBOLS defined by the
		// PanLeftButton and PanRightButton components.
		params.setLocalizedTexts({
			"en":{
				"PanRightButton.TOOLTIP":"Next",
				"PanLeftButton.TOOLTIP":"Previos"
				 },
			defaultLocale: "en"
			});
		params.push("serverurl", "http://s7d1.scene7.com/is/image");
		params.push("asset", "sample/brochure");
		//params.push("autoplay", "true,2,1");

		//-------------------------------------------------------------------------------- init
		var container, carouselView, mediaSet, nextBtn, prevBtn, imageMapEffect, indicator;

		function initViewer() {

            // Create the Container component object
            container = new s7sdk.common.Container(null, params, "s7container");

            // Create the CarouselView component object
			carouselView = new s7sdk.set.CarouselView(container, params, "exCarouselView");
            carouselView.addEventListener(s7sdk.event.AssetEvent.ITEM_SELECTED_EVENT, onCarouselViewSelected, false);

			// Create the ImageMapEffect component object
			imageMapEffect = new s7sdk.image.ImageMapEffect("exCarouselView", params, "exImageMapEffect");

			// Create the SetIndicator component object
            indicator = new s7sdk.set.SetIndicator(container, params, "exIndicator");

			// Create the Button components object
			nextBtn = new s7sdk.common.PanRightButton(container, params, "nextButton");
			prevBtn = new s7sdk.common.PanLeftButton(container, params, "prevButton");

			// Add event listeners for buttons click events
			nextBtn.addEventListener("click", onNext, true);
			prevBtn.addEventListener("click", onPrev, true);

			// Create the MediaSet component object
			mediaSet = new s7sdk.MediaSet(null, params, null);
			mediaSet.addEventListener(s7sdk.AssetEvent.NOTF_SET_PARSED, onSetParsed, false);
		};

		function onSetParsed(e) {
			var msasset = e.s7event.asset;
			carouselView.setMediaSet(msasset);
            indicator.setNumberOfPages(msasset.items.length);
		};
	    
		// Define an event handler function to update the SetIndicator when the page changes
		function onCarouselViewSelected(event){
			var idx = event.s7event.frame;
			indicator.setSelectedPage(idx);
		};

		function onNext(event){
			carouselView.nextPage();
		}

		function onPrev(event){
			carouselView.prevPage();
		}

		params.addEventListener(s7sdk.Event.SDK_READY, initViewer, false);
		params.init();
	</script>
</body>
</html>

Default styles for PageView:

.s7carouselview {
	background-color:#ffffff;
	position:absolute;
	width:400px;
	height:400px;
	z-index:0;
	user-select:none;
	-ms-user-select:none;
	-moz-user-select:-moz-none;
	-webkit-user-select:none;
	-webkit-tap-highlight-color:rgba(0,0,0,0);
 }
.s7carouselview img {
	max-width:none;
	max-height:none;
 }

Parameters:
{String|Container} container: The reference to Container instance or the ID of the parent DOM element to which the component is added as a child
{s7sdk.ParameterManager} settings: A parameter manager instance that represents the desired configuration.
{String} compId: An optional parameter that specifies the ID of the component DOM element.

See:: s7sdk.ParameterManager; s7sdk.set.MediaSet; s7sdk.image.ImageMapEffect

Method Detail

addEventListener(type, handler, useCapture)

Adds an event listener to the instance of the CarouselView component. The handler function receives a DOM event object of type Event. The object contains a property s7event, which references the associated custom event object, for example s7sdk.event.AssetEvent.

The events supported by the component are:

s7sdk.event.ResizeEvent.COMPONENT_RESIZE - Dispatched when the component has been resized. s7sdk.event.ResizeEvent

s7sdk.event.CapabilityStateEvent.NOTF_CAROUSELVIEW_CAPABILITY_STATE - Dispatched when the page index, pan or zoom capabilities have changed. s7sdk.event.CapabilityStateEvent

s7sdk.event.AssetEvent.ASSET_CHANGED - Dispatched when asset has changed. s7sdk.event.AssetEvent

s7sdk.event.AssetEvent.ITEM_SELECTED_EVENT - Dispatched when the current page has changed. s7sdk.event.AssetEvent

s7sdk.event.FrameEvent.NOTF_FRAME_TRANSITION_START - Dispatched when fade or slide page transition begins. s7sdk.event.FrameEvent

s7sdk.event.FrameEvent.NOTF_FRAME_TRANSITION_END - Dispatched when fade or slide page transition is finished. s7sdk.event.FrameEvent

s7sdk.event.StatusEvent.NOTF_ASSET_METADATA_READY - Dispatched when component receives asset metadata. If the component is initialized with setMediaSet() it dispatches instantly inside that API call. Otherwise if the component loads req=set on its own, this event is sent when component has received and parsed req=set. s7sdk.event.StatusEvent

s7sdk.event.StatusEvent.NOTF_VIEW_READY - Dispatched when component fills the view entirely with image data (either low-resolution tile or high-resolution overview image loads and displays - whatever comes first). It is sent only after asset swap and not during zoom, pan or page change operations. s7sdk.event.StatusEvent

s7sdk.event.StatusEvent.NOTF_HIGHRES_VIEW_READY - Dispatched when component fills the view with high resolution image. The event is sent only once per asset swap, when the view is filled with high resolution image data for the first time after asset was set or changed. This event is not sent later, when user zooms, pans or changes pages. s7sdk.event.StatusEvent

s7sdk.event.StatusEvent.NOTF_PRELOAD_START - Dispatched when the component begins to preload new content according to maxloadradius modifier. The event is sent multiple times during component's life cycle as user actions may trigger new preloading step. s7sdk.event.StatusEvent

s7sdk.event.StatusEvent.NOTF_PRELOAD_COMPLETE - Dispatched when all the content according to maxloadradius modifier is downloaded. The event is sent multiple times during component's life cycle as user actions may trigger new preloading step. s7sdk.event.StatusEvent

Parameters:
{String} type: Event name, for example s7sdk.event.AssetEvent.ASSET_CHANGED.
{Function} handler: Function to be called when the event gets dispatched.
{Boolean} useCapture: Register capture phase.

autoPlayPause()

Pauses auto-play animation.

autoPlayResume()

Resumes the auto-play animation if it is configured using autoPlay modifier but was paused with autoPlayPause() call. This method has no effect if auto-play was not enabled in the component settings.

dispose()

Dispose is used to remove itself and all sub-elements from the DOM

{Boolean} getAutoPlay()

Return autoplay permission.

Returns:: autoplay permission.

{s7sdk.CarouselViewCapabilityState} getCapabilityState()

Returns the current capabilities of the CarouselView instance.

Returns:: {s7sdk.CarouselViewCapabilityState} The current capabilities of the CarouselView instance.

See:: s7sdk.CarouselViewCapabilityState

{Number} getCurrentFrameIndex()

Returns current frame index.

Returns:: Index of the current frame.

{Number} getHeight()

Returns the current inner height of the component.

Returns:: {Number} the inner height of the component, in pixels.

{Number} getWidth()

Returns the current inner width of the component.

Returns:: {Number} the inner width of the component, in pixels.

{Point2D} imagePixelsToViewPoint(inPt)

Converts a point from the top resolution image coordinates to view coordinates.

Parameters:
{Point2D} inPt: Point in top resolution image coordinates.

Returns:: {Point2D} point in view coordinates

See:: s7sdk.Point2D

nextPage()

Go to next page.

prevPage()

Go to previous page.

resize(w, h)

Sets CarouselView to the specified width and height.

Parameters:
{Number} w: The width of the component, in pixels.
{Number} h: The height of the component, in pixels.

setAsset(assetName)

Changes the currently displayed set. The component invalidates and rebuilds using the existing serverurl and the new asset after retrieving the set definition from Image Serving. Unless the asset has not been set already, this call generates a SWAP tracking event that is managed by the TrackingManager component. Preferred way of changing assets though is by calling the setMediaSet() API

Parameters:
{String} assetName: - The catalog ID of the set.

See:: s7sdk.TrackingManager; s7sdk.set.MediaSet

setAutoPlay(val)

Set autoplay permission.

Parameters:
{Boolean} val: Specifies on/off of auto-loop

setCSS(classname, property, value)

Sets a particular CSS class and property on a component

Parameters:
{String} classname: The CSS classname to use for this style. i.e. .s7carouselview
{String} property: The CSS property that is being set. i.e. background-color
{String} value: The CSS property value being set. i.e. #FF0000

setCurrentFrameIndex(idx)

Set current frame to specific index.

Parameters:
{Number} idx: new frame index

setMediaSet(mediaSet)

Sets the image or eCatalog set or OrientationSetDesc instance which contains two instances of MediaSetDesc for landscape and portrait orientations separately. This will re-set the component to use the new set content; anything previously set through asset modifier will be ignored. The set is not parsed recursively; to use embedded sets you need to call this method passing in the embedded set instead.

Parameters:
{MediaSetDesc | OrientationSetDesc} mediaSet: Set to extract the frames from.

See:: s7sdk.set.MediaSet; s7sdk.MediaSetDesc; s7sdk.OrientationSetDesc

setModifier(modObj)

Sets 1-N # of modifiers for the component.

Parameters:
{Object} modObj: A simple JSON object with name:value pairs of valid modifiers for a particular component

Namespaces

Classes in s7sdk.set

Class s7sdk.set.CarouselView