HTML5 Viewer SDK API Documentation 

Namespaces


Class Index

Classes in s7sdk.set

Class s7sdk.set.SpinView

The SpinView is an image viewing component that displays a spin set served by Adobe Scene7 Image Serving. You can create the illusion of a rotating object by displaying images taken from different angles that make up a spin set. You can spin around the view by either calling moveFrame() API from JavaScript or by dragging the image when current frame is fully zoomed out, otherwise drag will pan the zoomed in image.

You can also zoom into the currently displayed frame by either double-clicking/tapping on it or by calling zoomIn() API from JavaScript. You can adjust which user action is associated with a zooming action through the use of doubleclick and singleclick modifiers. On the devices that support pinch gestures, pinching in and out zooms in and out the current frame. If the image is zoomed in, a dragging gesture pans the image. If the image is fully zoomed out, a dragging gesture results in frame change, resulting in a spinning of the view.

The auto-spin feature can be turned on using autospin modifier. It is possible to control auto spin speed, number of rotations and direction. In order to achieve the best auto spin experience it is recommended to preload all frames by setting maxloadradius to -1; note however that this will result in increased load time and higher bandwidth usage.

The SpinView component supports two dimensional Spin Sets including sets with incomplete rows. The SpinView component handles incomplete sets by centering each row of frames.

The spin set to be displayed by the component can be set by either using the setMediaSet() API or using the asset modifier directly. However if you are specifying inline sets as a list of asset IDs/names then you must use the MediaSet component and setMediaSet() API. Each inline set should include a comma separated list of assets (in the form company/asset). If it is a 2d Spin Set, each row should be enclosed in curly braces and also separated by commas. For instance, a 3 item spin set could be specified like:

demo/p01,demo/p02,demo/p03

A 2D SpinSet with 2 rows and 2 columns would be specified similarly:

{demo/p01,demo/p02},{demo/p03,demo/p04}


If you are using the SpinView directly, the set passed to the asset modifier must be fully defined in the Scene7 Publishing System and identifiable by the catalog/set id.

Customizing Behavior Using Modifiers

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

The following modifiers are supported:

ModifierSyntaxDescriptionDefault
serverurlisRootPathThe 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/
assetspinSetThe Image Serving catalog or asset ID of a named spin set whose definition comes from the server by means of the req=set command.
iscommandvalueImage Serving command string that is applied to all images in the set. If specified in the URL, all occurrences of '&' and '=' must be HTTP-encoded as %26 and %3D, respectively.
zoomstepstep[,limit]Configures how many zoom-in and zoom-out actions are required to increase or decrease the resolution by a factor of two. The resolution change for each zoom action is 2^1/step. Set to 0 to zoom to full resolution with a single zoom action. Set limit to specify the maximum zoom resolution, relative to the full resolution image. The default of 1.0 does not allow zooming beyond full resolution.1.0, 1.0
transition[time][,easing]Time specifies the time in seconds that the animation takes for a single zoom step action. Use easing to create an illusion of acceleration or deceleration which makes the transition appear more natural. You can set easing to one of the following: 0 (auto), 1 (linear), 2 (quadratic), 3 (cubic), 4 (quartic), 5 (quintic). Auto mode always uses linear transition when elastic zoom is disabled (default). Otherwise, it fits one of the other easing functions based on the transition time. That is, the shorter the transition time, the higher the easing function is used to quicken the acceleration or deceleration effect.0.5,0
singleclicknone|zoom|reset|zoomResetConfigures the mapping of single-click or tap-to-zoom actions. Set to none to disable single-click or tap zoom. If it is set to zoom, clicking the image zooms in one zoom step; CTRL+clicking zooms out one zoom step. Set reset to cause a single click of the image to reset the zoom to the initial zoom level. For zoomReset, reset is applied if the current zoom factor is at or beyond the specified limit. Otherwise, zoom is applied.none
doubleclicknone|zoom|reset|zoomResetConfigures the mapping of double-click or tap-to-zoom actions. Set to none disables double-click or tap zoom. If it is set to zoom then clicking the image zooms in one zoom step; CTRL+clicking zooms out one zoom step. Set reset causes a single click of the image to reset the zoom to the initial zoom level. For zoomReset, reset is applied if the current zoom factor is at or beyond the specified limit. Otherwise, zoom is applied.zoomReset
maxloadradiusvalue[,highRes]Represents the maximum number of frames to preload in each direction when the SpinView is idle. A value of -1 preloads all frames in the set. The preloaded frames are always in the original resolution at which the SpinView was initially loaded.6,0
autospin0|1[,duration][,direction][,spin_number]Enables or disables the automatic spin animation. duration is the number of seconds per one full spin. direction is the spin direction which is 0 for spinning east and 1 for spinning west. spin_number is the number of full rotations done before autospin stops. The number is a floating point number. Set to -1 for an infinitive auto spin.0,1,1,1
iconeffect0|1[,count][,fade][,autoHide]Enables the IconEffect to display above the first image in the spin set when the image is in a reset state. Such functionality suggests to the user to drag the image to spin it. Set count to specify the maximum number of times the icon overlay appears and reappears. A value of -1 indicates that the overlay reappears indefinitely. Set fade to specify the duration in seconds of show and hide animation. Set autoHide to specify the number of seconds that the IconEffect stays fully visible before it auto-hides. That is, the time after fade in animation is completed and before fade out animation starts). A value of 0 disables the auto-hide behavior.1,1,0.3,3
enableHDalways|never|limit,numberEnable, limit, or disable optimization for devices where devicePixelRatio is greater than 1 such as devices with high-density display like iPhone4 and similar devices. If active, the component limits the size of the IS image request as if the device only had a pixel ratio of 1, thereby reducing the bandwidth. If you use the limit setting, the component enables high pixel density only up to the specified limit.limit,1500
lockdirection0|1Specifies whether to alow a change in spin direction in case of 2d spin set. When set to 1 the component will identify the primary drag or swipe direction (horizontal vs vertical) in the beginning of the gesture and after that will keep that direction until the gesture ends. In this case if the user starts horizontal spin and then decides to continue their drag gesture in a vertical direction the component will not perform vertical spin, and will still consider only horizontal part of mouse movement or swipe. A value of 0 allows user to change spin direction at any point of time during the gesture progress. The setting has not affect if the spin set is 1D.0
sensitivityxSensitivity[,ySensitivity]Controls sensitivity of the horizontal and vertical spin performed with mouse drag or swipe. xSensitivity sets how many full horizontal product rotations will be made if user drags their mouse horizontally from one side of the view to another; for example, 3 would mean that user would see 3 complete spins for one full drag gesture. Similarily, ySensitivity controls sensitivity of the vertical spin; the value of 1 means that one full vertical drag or swipe changes the view angle from the top-most spin plane to the bottom-most (or vice verse). Setting negative value for ySensitivity reverses the direction of vertical spin.5,2
fmtjpg|jpeg|png|png-alpha|gif|gif-alphaSpecifies the image format that the component uses to load 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 transparentjpeg

Defining the Appearance using CSS

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

The styling of the sub-elements using class selectors like .s7iconeffect for example, must be specified in the form of the descendant class selectors, that is, they must follow the main class selector separated by a space, such as .s7spinview .s7iconeffect. For more information on component styling see the HTML5 Viewer SDK User Guide and the default styles section.

CSS ClassAttribute SelectorDescription
.s7spinview(None)Represents the main body of the SpinView component.
.s7iconeffectstate=[spin_1D|spin_2D]Defines the appearance of the IconEffect. If the component works with two-dimensional spin, it applies state=spin_2Dselector; otherwise state=spin_1D is used.

Localized Symbols

SpinView 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.

SymbolDescription
SpinView.ROLE_DESCRIPTIONDefine a localized "aria-roledescription" of SpinView
SpinView.USAGE_HINTDefine a localized text for "aria-describedby" of SpinView

Class Summary
Constructor Attributes Constructor Name and Description
 
s7sdk.set.SpinView(container, settings, compId)
Method Summary
Method Attributes Method Name and Description
 
addEventListener(type, handler, useCapture)
Adds an event listener to the instance of the SpinView component.
 
Dispose is used to remove itself and all sub-elements from the DOM
 
Returns a SpinCapabilityState object that can be used to determine the current state of the SpinView component.
 
Gets the currently displayed frame.
 
Retrieves the total number of frames.
 
Returns the current inner height of the component.
 
Returns the current inner width of the component.
 
The current zoom scale percentage, where 0 corresponds to the reset state and 100 to the top image resolution or the set limit.
 
Converts a point from the top resolution image coordinates to view coordinates.
 
moveFrame(direction)
Move the current frame to an adjacent frame.
 
resize(w, h)
Sets SpinView to the specified width and height.
 
setAsset(asset)
Changes the currently displayed set.
 
setCSS(classname, property, value)
Sets a particular CSS class and property on a component
 
Changes the currently displayed frame.
 
setMediaSet(mediaSet)
Sets the spin set as parsed by the MediaSet component.
 
setModifier(modObj)
Sets 1-N # of modifiers for the component.
 
Zoom in one level.
 
zoomNPan(dx, dy)
Move the displayed portion of the zoomed in image by a specified amount.
 
zoomNRgn(rgn)
Display the specified image region in the view area and adjust the zoom level accordingly.
 
Zoom in by one step.
 
Reset the view to its initial zoom state.
 
zoomRgn(rgn)
Display the specified image region in the view area and adjust the zoom level accordingly.
Class Detail
s7sdk.set.SpinView(container, settings, compId)
Example Code

This example demonstrates how to use the SpinView component in a simple viewer. In this example a Container object, a SpinView object, and two pan button objects are created. Every time a user clicks on a pan button, the moveFrame() method is called on the SpinView object to simulate spinning the image in the given direction. Notice that the pan buttons have been repurposed for use as rotate buttons in this example, and the buttons' default tooltip text has been changed to reflect their functionality. The code below does the following:

  1. The Scene7 HTML5 SDK is linked to the page and the required s7sdk components are included in the document head.
  2. CSS Styles are defined in the document head to control the appearance of the SpinView and button components.
  3. The s7sdk.Util.init() method is called to initialize the SDK.
  4. A ParameterManager object is created to handle component modifiers for the viewer.
  5. An initViewer() function is defined. This function initializes a couple of modifiers (hard coded for example purposes), and sets new strings to be displayed as tooltips by the button components when a user interacts with them. It 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.).
  6. Handler functions are defined to respond to the component event listeners added in the initViewer() function.
  7. 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.
  8. 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="user-scalable=no,height=device-height,width=device-width,initial-scale=1.0,maximum-scale=1.0"/> <title>SpinView Example</title> <!-- To run this example locally you need to replace this with an absolute SDK path. For more information check the HTML5 Viewers SDK User Guide or the examples included in the package. --> <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.Button'); s7sdk.Util.lib.include('s7sdk.common.Container'); s7sdk.Util.lib.include('s7sdk.set.SpinView'); </script> <style type="text/css" media="screen"> .s7spinview { height: 300px; width: 300px; } .s7panleftbutton { position: absolute; top: 137px; left: 0px; } .s7panrightbutton { position: absolute; top: 137px; left: 287px; } </style> </head> <body style="margin: 0 0;overflow:hidden;"> <script language="JavaScript" type="text/javascript"> var params, container, spinView, panRightButton, panLeftButton; // Initialize the SDK s7sdk.Util.init(); // Create ParameterManager instance to handles modifiers params = new s7sdk.ParameterManager(); // Assign new localized values for SYMBOLS defined by the // PanLeftButton and PanRightButton components. params.setLocalizedTexts({ "en":{ "PanRightButton.TOOLTIP":"Spin East", "PanLeftButton.TOOLTIP":"Spin West" }, defaultLocale: "en" }); // Define the function that initializes the viewer function initViewer(){ // Set hardcoded modifiers (not required when values are specified on the url) params.push("serverurl", "http://s7d1.scene7.com/is/image"); params.push("asset", "sample/spinner"); // Create the Container component object container = new s7sdk.Container(null, params, "s7container"); // Note: Any component supporting the setMediaSet API can be driven // by the MediaSet component. // Create the SpinView component object spinView = new s7sdk.set.SpinView(container, params, "spinView"); // Create the PanRightButton component object panRightButton = new s7sdk.common.PanRightButton(container, params, "panRightButton"); // Create the PanLeftButton component object panLeftButton = new s7sdk.common.PanLeftButton(container, params, "panLeftButton"); // Add event listeners for pan button click events panLeftButton.addEventListener("click", onPanLeft, true); panRightButton.addEventListener("click", onPanRight, true); } // Define an event handler function to rotate the SpinView left (West) function onPanLeft(event){ spinView.moveFrame(s7sdk.Enum.SPIN_DIRECTION.WEST); } // Define an event handler function to rotate the SpinView right (East) function onPanRight(event){ spinView.moveFrame(s7sdk.Enum.SPIN_DIRECTION.EAST); } // The ParameterManager will dispatch SDK_READY when all modifiers have been processed // and it is safe to initialize the viewer params.addEventListener(s7sdk.Event.SDK_READY, initViewer, false); // Now it is safe to process the modifiers, the callbacks have been defined // this will trigger the SDK_READY event params.init(); </script> </body> </html>
Default styles for SpinView:

.s7spinview {
	background-color:#ffffff;
	position:absolute;
	width:400px;
	height:400px;
	user-select:none;
	-moz-user-select:-moz-none;
	-webkit-user-select:none;
	-webkit-tap-highlight-color:rgba(0,0,0,0);
	opacity:1;
	text-align:left;
 }
.s7spinview img {
	max-width:none;
	max-height:none;
 }
.s7spinview .s7iconeffect {
	width:120px;
	height:120px;
	-webkit-transform:translateZ(0px);
	background-repeat:no-repeat;
	background-position:center;
 }
.s7spinview .s7iconeffect[state='spin_1D'] {
	background-image:url(images/sdk/spinicon.png);
 }
.s7spinview .s7iconeffect[state='spin_2D'] {
	background-image:url(images/sdk/spinicon_2D.png);
 }
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 components DOM element
Method Detail
addEventListener(type, handler, useCapture)
Adds an event listener to the instance of the SpinView 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.CapabilityStateEvent.

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_SPIN_CAPABILITY_STATE - Dispatched when the spin, pan, or zoom capabilities have changed. See s7sdk.SpinCapabilityState
  • s7sdk.event.AssetEvent.ASSET_CHANGED - Dispatched when the spin asset has changed. s7sdk.event.AssetEvent
  • 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 spin 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 spins. 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.CapabilityStateEvent.NOTF_ZOOM_CAPABILITY_STATE.
    {Function} handler
    Function to be called when the event gets dispatched.
    {Boolean} useCapture
    Register capture phase.
    See:
    s7sdk.SpinCapabilityState

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

    {s7sdk.SpinCapabilityState} getCapabilityState()
    Returns a SpinCapabilityState object that can be used to determine the current state of the SpinView component. For example, if the component can zoom in, then the ZOOM_IN capability flag will be set. This means that the current frame is not fully zoomed in.
    Returns:
    {s7sdk.SpinCapabilityState} The current capabilities of the SpinView instance.
    See:
    s7sdk.SpinCapabilityState

    getCurrentFrameIndex()
    Gets the currently displayed frame.
    Returns:
    int Current 0-based index of the displayed frame.

    {int} getFramesLength()
    Retrieves the total number of frames.
    Returns:
    {int} Total number of frames in the spin set.

    {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.

    {Number} getZoomLevel()
    The current zoom scale percentage, where 0 corresponds to the reset state and 100 to the top image resolution or the set limit.
    Returns:
    {Number} Percentage zoom level.

    imagePixelsToViewPoint(inPt)
    Converts a point from the top resolution image coordinates to view coordinates.
    Parameters:
    {Point2D} inPt
    Point in top resolution image coordinates.
    See:
    s7sdk.Point2D

    moveFrame(direction)
    Move the current frame to an adjacent frame. For instance, passing s7sdk.Enum.SPIN_DIRECTION.NORTH_EAST for the direction parameter will move the frame up one row and to the right one row. Incomplete rows in the spin set are centered, so when traversing up and down the frame selected will be centered. The north and south (up and down) movement is locked at the top and bottom positions. The east and west (or left and right) motion wraps around from side to side.
    Parameters:
    {s7sdk.Enum.SPIN_DIRECTION} direction
    Direction to move to.
    See:
    s7sdk.Enum.SPIN_DIRECTION

    resize(w, h)
    Sets SpinView 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(asset)
    Changes the currently displayed set. The component invalidates and rebuilds using the existing serverurl and the new asset after retrieving the spin 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.
    Parameters:
    {String} asset
    - The catalog ID of the spin set.
    See:
    s7sdk.TrackingManager

    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. .s7spinview
    {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(val)
    Changes the currently displayed frame.
    Parameters:
    val
    The 0-based index of the frame to switch to.

    setMediaSet(mediaSet)
    Sets the spin set as parsed by the MediaSet component. This re-sets the component to use the new spin set content. Anything that is previously set through the asset modifier is ignored.

    This method is more efficient way of setting the set for the component to display compared to the setAsset() API which is assuming a stand-alone mode of operation and is sending a separate image serving request to retrieve the set definition. In addition, this is the only way to use inline spin sets with this component.

    Parameters:
    mediaSet
    {s7sdk.MediaSetDesc} Set from which to extract the frames.
    See:
    s7sdk.MediaSetDesc
    s7sdk.MediaSet

    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

    zoomIn()
    Zoom in one level.

    zoomNPan(dx, dy)
    Move the displayed portion of the zoomed in image by a specified amount. The image is displaced both horizontally and vertically as specified by dx and dy parameters which are in normalized image coordinates where 0,0 represents the upper-left corner and 1,1 represents the lower-right corner of the image.
    Parameters:
    {Object} dx
    If dx is greater than 0 the image is moved to the right; if dx is less than 0 the image is moved to the left.
    {Object} dy
    If dy is greater than 0 the image is moved down; if dy less than 0 the image is moved up.

    zoomNRgn(rgn)
    Display the specified image region in the view area and adjust the zoom level accordingly. This operation will fit the specified region into the SpinView viewing area the best way possible without distorting the image. That is, the specified region will be modified if necessary in order to preserve the image aspect ratio.
    Parameters:
    {Rectangle} rgn
    The image region in normalized image coordinates where 0,0 represents the top left corner and 1,1 represents the bottom right corner of the image.

    zoomOut()
    Zoom in by one step.

    zoomReset()
    Reset the view to its initial zoom state.

    zoomRgn(rgn)
    Display the specified image region in the view area and adjust the zoom level accordingly. This operation will fit the specified region into the SpinView viewing area the best way possible without distorting the image. That is, the specified region will be modified if necessary in order to preserve the image aspect ratio.
    Parameters:
    {Rectangle} rgn
    Image region to zoom into in image top resolution coordinates.

    Documentation generated by JsDoc Toolkit 2.4.0 on Thu Oct 15 2020 11:59:13 GMT-0000 (UTC)