Class s7sdk.image.ZoomTargets

The ZoomTargets are essentially hyperlinks to specific regions in the image. These hyperlinks are represented with small thumbnail images (targets) that are retrieved from TargetDesc associated with the image. The component will dispatch a ZoomTargetEvent.ZOOM_TARGET event every time a target is selected. The dispatched event contains information on the region represented by the target which is usually used by ZoomView component to zoom and pan the displayed image to the specified region.

A target is selected by clicking (or tapping) the displayed thumbnail, or by using the selectTarget() API in the viewer code.

The ZoomTargets component can display large collections of targets if needed. Scrolling controls appear when the number of targets exceeds the available space. Scrolling is also supported with a mouse or by using touch gestures.

Customizing Behavior Using Modifiers

Modifiers change ZoomTargets 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 image set whose definition comes from the server by means of the `req=imageset` command.	""
iscommand	value	The Image Serving command string that is applied to all swatches and images. If specified in the URL, all occurrences of '&' and '=' must be HTTP-encoded as `%26` and `%3D`, respectively.	""
tmbsize	width, height	Specifies the size of the individual target thumbnails in pixels. If the cell size of the target exceeds the size requirement of the component, the targets do not display. (Deprecated: now use CSS to specify thumb dimensions.)	75,75
tmblayout	cols, rows	Specifies columns, or rows, or both to limit the number of cells per row and column, respectively. Set rows, or columns, or both to 0 to let the component choose how many cells per row and column to display. If both rows and columns are larger than 0, the component ignores any swatches that exceed the total number of cells that are available. The swatches are also ignored if they cannot fit into the component's area and the resizable modifier is set to false.	0,2
textpos	bottom\|top\|left\|right\|none\|tooltip	Specifies where the label is drawn relative to the target's thumbnail image. That is, the label is centered at the specified location relative to the thumbnail. When `tooltip` is specified, no label is drawn.	tooltip
fmt	jpg\|jpeg\|png\|png-alpha\|gif\|gif-alpha	Specifies the image format used by the component for loading images from Image Server. The image format is any value supported by Image Server and the client browser. If the image_format ends with "-alpha", the component renders images as transparent. For all other image format values the component treats images as opaque.	jpeg
resizable	0\|1	If set to 0, only the thumbnails that can fit into the component's area are shown. If set to 1, the component dynamically resizes to fit the content.	0
pagemode	0\|1	When toggled, the scroll buttons automatically cause the thumbnails to jump a full page length. Extra whitespace is shown on the last page if the thumbnails do not fit. The last page has the same number of cells as any previous page. The scrollstep is ignored and mouse scrolling settles only on full pages.	0
enablescrollbuttons	0\|1	Displays or hides the scroll buttons. When the scroll buttons are hidden, the user can use their mouse or use touch gestures to scroll. Scroll buttons do not appear if there is no need to scroll regardless of the setting.	1
scrollstep	hStep, vStep	Specifies the number of thumbnails to scroll for each tap of the corresponding scroll button.	3,3
enabledragging	0\|1[,overdragvalue]	Enables or disables the ability for a user to scroll the swatches using a mouse or using touch gestures. The `overdragvalue` is in the 0 - 1 range and it is a percent value for the movement in the wrong direction of the actual speed. If set to 1, it moves with the mouse. If set to 0 it does not let you move in the wrong direction at all.	1,0.5
buttonsnapmode	snapin\|snapout\|overlay	One of three button modes that are specified by setting the desired string. Use `snapin` to cause the buttons to align next to the thumbnails. Use `snapout` to cause the buttons to align next to the component border. Use `overlay` to cause the buttons to render on top of the thumbnails.	snapout
partialswatches	0\|1	Specifies whether the component allows scrolling to stop when any of the thumbnails are partially visible (scrolling not aligned). The recommended value is false or 0.	0
orientation	0\|1	Defines the layout of swatch cells. A row-major layout is used when the orientation is set to 0; a column-major layout is used when the orientation is set to 1.	0

Defining the Appearance using CSS

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

The styling of the sub-elements using class selectors like .s7thumb 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 .s7szoomtargets .s7thumb. For more information on component styling see the HTML5 Viewer SDK User Guide and the examples in this document.

CSS Class	Attribute Selector	Description
`.s7zoomtargets`	(None)	Represents the main body of the `ZoomTargets` component.
`.s7thumbcell`	(None)	Defines thumbnail spacing using `margin` CSS property.
`.s7thumb`	`state=[default\|selected\|over]`	Defines the appearance of the swatch thumbnails. `default` value of `state` attribute corresponds to "up" state, `selected` means that the thumbnail is currently selected and `over` state turns on when user rolls over unselected thumbnail.
`.s7label`	(None)	Defines the appearance of the swatch labels.
`.s7tooltip`	(None)	A global class selector that defines appearance for the tooltips. To disable tooltips set the `display` style to `none`.
`.s7scrollleftbutton`	(None)	Defines the appearance of the left scroll button.
`.s7scrollrightbutton`	(None)	Defines the appearance of the right scroll button.
`.s7scrollupbutton`	(None)	Defines the appearance of the up scroll button.
`.s7scrolldownbutton`	(None)	Defines the appearance of the down scroll button.

Localizable Symbols

Swatches also have a number of 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
`ScrollLeftButton.TOOLTIP`	Define a localized tooltip of `ScrollLeftButton`
`ScrollRightButton.TOOLTIP`	Define a localized tooltip of `ScrollRightButton`
`ScrollUpButton.TOOLTIP`	Define a localized tooltip of `ScrollUpButton`
`ScrollDownButton.TOOLTIP`	Define a localized tooltip of `ScrollDownButton`

Class Summary
Constructor Attributes	Constructor Name and Description
	s7sdk.image.ZoomTargets(container, settings, compId)

Method Summary
Method Attributes	Method Name and Description
	addEventListener(type, handler, useCapture) Adds an event listener to the instance of the `ZoomTargets` component.
	getFrame() Returns the index of the currently selected frame of the image or media set.
	resize(width, height) Resizes the `ZoomTargets` component to the specified width and height.
	selectTarget(targetDesc, triggerScroll) Selects the specified target.
	setAsset(assetName) Changes the currently active set.
	setCSS(classname, property, value) Sets a particular CSS class and property on a component
	setItem(item) Sets the current item represented by the component.
	setModifier(modObj) Sets 1-N # of modifiers for the component.

Class Detail

s7sdk.image.ZoomTargets(container, settings, compId)

Example Code
This example demonstrates how to use the ZoomTargets component in a simple viewer. In this example a Container object,
a ZoomView object, and a ZoomTargets object are created. The ZoomTargets object displays thumbnails for each zoom target
found within the image asset. When a ZoomTargets thumbnail is selected it modifies the display area and zoom level of
the ZoomView object.

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 ZoomView and ZoomTargets 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 several 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>ZoomTargets 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.Container');
            s7sdk.Util.lib.include('s7sdk.image.ZoomTargets');
            s7sdk.Util.lib.include('s7sdk.image.ZoomView');
        </script>

        <style type="text/css" media="screen">
            .s7zoomview {
                left: 105px;
                top: 0px;
                width: 300px;
                height: 400px;
            }
            .s7zoomtargets {
                width: 100px;
                height: 400px;
                z-index: 1;
            }
            .s7zoomtargets .s7thumb{
                width: 70px;
                height: 60px;
            }
        </style>

    </head>
    <body>

        <div id="s7container"></div>
        <script type="text/javascript" language="JavaScript">
            var params, container, zoomTargets, zoomView;

            // Initialize the SDK
            s7sdk.Util.init();

            // Create ParameterManager instance to handles modifiers		
            params = new s7sdk.ParameterManager();
                
            // 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", "Scene7SharedAssets/Backpack_B");
                params.push("tmblayout", "1,0"); // layout thumbnails with 1 column and many rows

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

                // Create the ZoomView component object
                zoomView = new s7sdk.image.ZoomView(container, params, "zoomview");

                // Create the ZoomTargets component object
                zoomTargets = new s7sdk.image.ZoomTargets(container, params, "targets");

                // Add an event listener for zoom target selection events
                zoomTargets.addEventListener(s7sdk.event.ZoomTargetEvent.ZOOM_TARGET, onTargetSelected, false);
            }

            // Define an event handler function to update the ZoomView when a zoom target is selected
            function onTargetSelected(event){
                zoomView.zoomRgn(event.s7event.zoomRgn);
            }

            // The ParameterManager dispatches SDK_READY when all the modifiers
            // are processed and it is safe to initialize the viewer.
            params.addEventListener(s7sdk.Event.SDK_READY, initViewer, false);

            // It is now safe to process the modifiers. The callbacks are defined
            // which trigger the SDK_READY event.
            params.init();

        </script>
    </body>
</html>

Default styles for ZoomTargets:

.s7zoomtargets {
	background-color:rgba(100, 100, 100, 0.2);
	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);
	width:400px;
	height:150px;
 }
.s7zoomtargets .s7thumbcell {
	margin:5px;
 }
.s7zoomtargets .s7thumb {
	border:1px solid transparent;
	width:75px;
	height:75px;
 }
.s7zoomtargets .s7thumb[state='selected'] {
	border:1px solid #FFFFFF;
 }
.s7zoomtargets .s7scrollleftbutton {
	display:block;
	position:absolute;
	top:0px;
	left:0px;
	width:20px;
	height:20px;
 }
.s7zoomtargets .s7scrollleftbutton[state='up'] {
	background-image:url(images/sdk/scroll_left_up.png);
 }
.s7zoomtargets .s7scrollleftbutton[state='over'] {
	background-image:url(images/sdk/scroll_left_over.png);
 }
.s7zoomtargets .s7scrollleftbutton[state='down'] {
	background-image:url(images/sdk/scroll_left_down.png);
 }
.s7zoomtargets .s7scrollleftbutton[state='disabled'] {
	background-image:url(images/sdk/scroll_left_disabled.png);
 }
.s7zoomtargets .s7scrollrightbutton {
	display:block;
	position:absolute;
	top:0px;
	left:0px;
	width:20px;
	height:20px;
 }
.s7zoomtargets .s7scrollrightbutton[state='up'] {
	background-image:url(images/sdk/scroll_right_up.png);
 }
.s7zoomtargets .s7scrollrightbutton[state='over'] {
	background-image:url(images/sdk/scroll_right_over.png);
 }
.s7zoomtargets .s7scrollrightbutton[state='down'] {
	background-image:url(images/sdk/scroll_right_down.png);
 }
.s7zoomtargets .s7scrollrightbutton[state='disabled'] {
	background-image:url(images/sdk/scroll_right_disabled.png);
 }
.s7zoomtargets .s7scrollupbutton {
	display:block;
	position:absolute;
	top:0px;
	left:0px;
	width:20px;
	height:20px;
 }
.s7zoomtargets .s7scrollupbutton[state='up'] {
	background-image:url(images/sdk/scroll_up_up.png);
 }
.s7zoomtargets .s7scrollupbutton[state='over'] {
	background-image:url(images/sdk/scroll_up_over.png);
 }
.s7zoomtargets .s7scrollupbutton[state='down'] {
	background-image:url(images/sdk/scroll_up_down.png);
 }
.s7zoomtargets .s7scrollupbutton[state='disabled'] {
	background-image:url(images/sdk/scroll_up_disabled.png);
 }
.s7zoomtargets .s7scrolldownbutton {
	display:block;
	position:absolute;
	top:0px;
	left:0px;
	width:20px;
	height:20px;
 }
.s7zoomtargets .s7scrolldownbutton[state='up'] {
	background-image:url(images/sdk/scroll_down_up.png);
 }
.s7zoomtargets .s7scrolldownbutton[state='over'] {
	background-image:url(images/sdk/scroll_down_over.png);
 }
.s7zoomtargets .s7scrolldownbutton[state='down'] {
	background-image:url(images/sdk/scroll_down_down.png);
 }
.s7zoomtargets .s7scrolldownbutton[state='disabled'] {
	background-image:url(images/sdk/scroll_down_disabled.png);
 }
.s7zoomtargets .s7label {
	box-sizing:border-box;
	padding:3px;
	font:14px Helvetica, Arial;
	text-shadow:0px 4px 4px #555555;
 }
.s7tooltip {
	position:absolute;
	padding:5px;
	line-height:100%;
	text-align:center;
	background-color:rgb(224, 224, 224);
	color:rgb(26,26,26);
	font-family:Helvetica, sans-serif;
	font-size:11px;
	z-index:10000;
	border:1px solid rgb(191,191,191);
 }

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

Method Detail

addEventListener(type, handler, useCapture)

Adds an event listener to the instance of the ZoomTargets 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.ZoomTargetEvent.

The events supported by the component are:

ZoomTargetEvent.ZOOM_TARGET - Dispatched when a target is selected. s7sdk.event.ZoomTargetEvent

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

See:: s7sdk.event.ZoomTargetEvent

{Number} getFrame()

Returns the index of the currently selected frame of the image or media set.

resize(width, height)

Resizes the ZoomTargets component to the specified width and height.

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

selectTarget(targetDesc, triggerScroll)

Selects the specified target.

Parameters:
{s7sdk.TargetDesc} targetDesc: A target descriptor representing the target to select.
{Boolean} triggerScroll: Scroll to the newly selected target's thumbnial.

setAsset(assetName)

Changes the currently active set. The component invalidates and rebuilds using the existing serverurl and the new asset after retrieving the set definition from Image Serving, then displays the targets from the first element in the set. Preferred way of changing the displayed targets though is by simply calling setItem() API.

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

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. .s7zoomtargets
{String} property: The CSS property that is being set. i.e. background-color
{String} value: The CSS property value being set. i.e. #FF0000

setItem(item)

Sets the current item represented by the component. The item must be a decedent of type ItemDesc. An exception is thrown if the item does not reference a parent set, or is not descendant of type ItemDesc. The component is rebuilt after this call and the new targets, associated with the instance of the ItemDesc are displayed.

Parameters:
item: {s7sdk.ItemDesc} The set item whose zoom targets will be displayed by the component.

See:: s7sdk.ItemDesc; s7sdk.TargetDesc

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

Class s7sdk.image.ZoomTargets