Class s7sdk.image.ImageMapEffect

The ImageMapEffect component is an effects component designed to add functionality to the ZoomView, SpinView and PageView components. The ImageMapEffect uses map data retrieved from Scene7 Image Serving to highlight certain areas of the image and associate them with certain actions.

The component obtains image map data from Image Serving using the req=map command. The image maps can also be extracted from set definitions as parsed by the MediaSet component and assigned using the setMediaSet() API.

Image maps are defined in Image Serving catalogs in the form of a series of HTML <area> elements. Each area element has the following structure:

<area coords="coordinates" shape="shape"[rollover_key="id"] [href="href"] [target= "target"] [alt="toolTipText"] />

Attribute	Description
`shape`	Specifies the shape of the area. Only `poly` is currently supported. Required.
`coords`	The polygon vertices. Required.
`alt`	Optional text to display as a rollover tooltip.
`href`	Hyperlink for this area. The hyperlink is a URL, a JavaScript fragment, or an internal link. The internal links allow changing frames within the image set and are specified as `href="target:`frame`"`. Optional.
`target`	Browser target frame in which to display the web page referenced by `href`. Optional. Defaults to `_self` (same browser frame) if not specified.
`rollover_key`	Item identifier. Primarily used for the `RolloverKeyEvent` which is typically handled by the `InfoPanelPopup` component that uses the `rollover_key` value to retrieve the dynamic content from the info server and display it in the pop-up area.

When using JavaScript inside href attribute customer should understand that this JavaScript code will be executed on the client thus such code should be secure.

An active image map activates all other maps that are linked to the currently active map. You can link two or more independent image map areas that belong to the same frame by specifying the same value for the rollover_key attribute, or if the rollover_key attribute is empty, the maps are linked if they contain the same href value. You can override this behavior and force all maps to be visible, regardless if the user mouse over the map area or not.

Depending on the value of mode modifier ImageMapEffect component can either display image map icons in the center of image map area or render actual image map region.

Customizing Behavior Using Modifiers

Modifiers change ImageMapEffect 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.	/is/image/
rollover	0\|1	Specifies when to run the `RolloverKeyEvent.ROLLOVER_ACTIVATED` event. If set to 1, the event is run when the mouse enters the image map area--in case image map has non-empty `rollover_key` attribute. If set to 0, `RolloverKeyEvent.ROLLOVER_ACTIVATED` is run when the image map is clicked==if the image map has non-empty `rollover_key` and empty `href` attributes--in this case `RolloverKeyEvent.ROLLOVER_DEACTIVATED` is not run at all. `rollover` is automatically set to "0" on touch devices.	1
maptips	0\|1	Specifies whether or not tool tips are enabled for individual map area elements. Ignored on touch devices, including touch-enabled desktop systems.	0
mode	icon\|region\|auto\|none	Specifies the appearance of the image map. When set to `icon` map icons are statically shown on desktop and touch devices. `region` renders image map regions. On desktop systems, they are shown on rollover and on touch devices they are always visible. When set to `auto` on desktop systems, image map regions are shown on rollover and on touch devices map icons are always visible. `none` disables image maps.	icon

Defining Appearance using CSS

You can define the appearance of the ImageMapEffect component by using CSS rules. All HTML5 Viewer SDK components use class selectors for styling. You can style the body of the ImageMapEffect component by using the .s7imagemapeffect class selector. The styles associated with this class selector are applied to all instances of the ImageMapEffect component. Style particular instances by prefixing the class rule with the instance #ID. For example, styling rules for #myComp.s7imagemapeffect are applied only to the particular ImageMapEffect instance. For more information on component styling see the HTML5 Viewer SDK User Guide and the examples in this document.

CSS Class	Attribute Selector	Description
`.s7imagemapeffect`	(None)	Represents the main element of the `ImageMapEffect` component.
`.s7icon`	`state=[default\|active]`	Defines the appearance of the map icons.
`.s7region`	`(None)`	Defines the appearance of image map regions. Only `border` and `background` (or `background-color`) CSS properties are supported. `border` controls region outline, it should be specified as `"width solid color"`, where width should be in pixels and color is in either `#RRGGBB`, `RGB(R,G,B)` or `RGBA(R,G,B,A)` formats. `background` (or `background-color`) controls region fill, it should use the same color formats as supported for `border` color.
`.s7mapoverlay`	`state=[default\|active]`	Deprecated, use `.s7icon` instead.
`.s7tooltip`	(None)	A global class selector that defines appearance for the tooltips. To disable tooltips set the `display` style to `none`.

Localized Symbols

ImageMapEffect 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.These symbols are used to set "aria-label" attribute on an image map.

Symbol	Description
`ImageMapEffect.USAGE_HINT`	Used to describe keyboard control
`ImageMapEffect.TYPE_LINK`	An image map data assumes that when activated by ENTER key it will be opened by ImageMapEffect component in the current or new browser window (e.g. a navigation to different resource occurs)
`ImageMapEffect.TYPE_QUICK_VIEW`	RolloverKeyEvent.QUICKVIEW_ACTIVATED is dispatched when this map is activated by ENTER key
`ImageMapEffect.TYPE_VIDEO`	RolloverKeyEvent.VIDEO_ACTIVATED is dispatched when this map is activated by ENTER key
`ImageMapEffect.TYPE_TARGET`	RolloverKeyEvent.TARGET_INDEX is dispatched when this map is activated by ENTER key
`ImageMapEffect.TYPE_ROLL_OVER`	RolloverKeyEvent.ROLLOVER_ACTIVATED is dispatched when this map is activated by ENTER key
`ImageMapEffect.TYPE_ACTION`	JS function call is executed

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

Method Summary
Method Attributes	Method Name and Description
	addEventListener(type, handler, useCapture) Adds an event listener to the particular `ImageMapEffect` component.
	enableJavaScriptHrefs(enableScript) Sets component's behavior corresponds to ImageMapEffect.enableJavaScriptHrefs.
	getOverlaysVisible() Returns whether or not overlay visibility is enabled.
	setCSS(classname, property, value) Sets a particular CSS class and property on a component
	setModifier(modObj) Sets 1-N # of modifiers for the component.
	setOverlaysVisible(value) Whenever set to true, the map area overlays is visible as long as they are available.

Class Detail

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

Example Code
This example demonstrates how to use the ImageMapEffect component in a simple viewer. In this example a Container object,
a ZoomView object, an ImageMapEffect object, and an InfoPanelPopup object are created. When a user rolls over an area of the
ZoomView that is designated in the image map returned from the infoserver, the InfoPanel is activated. Note that the
"infoserverurl" modifier pushed into the ParameterManager object in the initViewer() function and the data that the server
returns are required for this example to work.

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 Swatches component.
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>InfoPanelPopup Components</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.ImageMapEffect');
            s7sdk.Util.lib.include('s7sdk.image.ZoomView');
            s7sdk.Util.lib.include('s7sdk.info.InfoPanelPopup');
        </script>

        <style type="text/css" media="screen">
            html,body {
                width: 100%;
                height: 100%;
            }
            body {
                padding: 0px;
                margin: 0px;
                font-size: 12px;
                background: #FFFFFF;
                overflow: hidden;
            }	
            .s7zoomview {
                top: 0px;
                left: 0px;
                height: 400px;
                width: 280px;
            }
            .s7infopanelpopup {
                position : absolute;
                top : 0px;
                left : 0px;
				width: 100%;
				height: 100%;
                background-color : rgba(0,0,0,0.7);
                z-index: 12000;
            }
            .s7infopanelpopup .s7overlay {
                left : 50%;
                top : 50%;
                margin-left : -150px;
                margin-top : -100px;
                width : 300px;
                height : 200px;
                padding : 20px;
                box-shadow : 12px 12px 12px 0px rgba(0,0,0,0.5);
                background-color : rgba(255,255,255,1);
            }
            .s7infopanelpopup .s7closebutton {
                position: absolute;
                width: 30px;
                height: 30px;
                top: -15px;
                right: -15px;
                padding: 8px;
            }
        </style>

    </head>
    <body>
        <script language="JavaScript" type="text/javascript">
            var params, container, zoomView, infoPanelPopup, imageMapEffect;

            // 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/eCatalog_Sample");

                // s7info infoserver specific parameters
                //params.push("infoserverurl", "http://s7info1.scene7.com/s7info/s7/$3$/$4$/$1$");
                var str = '<info><var name="1"><![CDATA[Value 1]]></var><var name="2"><![CDATA[Value 2]]></var><var name="3"><![CDATA[dynamicmedia-sample]]></var><var name="4"><![CDATA[adobe.com]]></var>' + 
                            '<![CDATA[<a href="http://$4$" target="_blank"> $1$ </a><br><img src="http://s7d1.scene7.com/is/image/Scene7SharedAssets/$3$" height="75%"><br>$2$]]></info>'
                params.push('template',str);

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

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

                 // Create the ImageMapEffect component object. For the first parameter, instead of passing
                 // the s7sdk.Container instance, we instead pass the DOM ID of the target ZoomView or SpinView component.
                imageMapEffect = new s7sdk.image.ImageMapEffect("zoomView", params, "imageMapEffect");

                // Create the InfoPanelPopup component object
                infoPanelPopup = new s7sdk.info.InfoPanelPopup(container, params, "infoPanelPopup");

                // Add event listeners for image map rollover events
                imageMapEffect.addEventListener(s7sdk.RolloverKeyEvent.ROLLOVER_ACTIVATED, rolloverKeyHandler, false);
                imageMapEffect.addEventListener(s7sdk.RolloverKeyEvent.ROLLOVER_DEACTIVATED, rolloverKeyHandler, false);
            }

            // Define an event handler function to activate the InfoPanelPopup for image map rollovers
            function rolloverKeyHandler(event) {
                if (event.s7event.rolloverKey != null) {
                    infoPanelPopup.activateRollover(event.s7event.rolloverKey);
                }
            }

            // 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 ImageMapEffect:


.s7imagemapeffect .s7icon {
	width:50px;
	height:50px;
	background-repeat:no-repeat;
	background-position:center;
	background-image:url(images/sdk/map_overlay_icon.png);
	z-index:999;
	cursor:pointer;
	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);
 }
.s7imagemapeffect .s7icon[state='default'] {
	opacity:0.6;
 }
.s7imagemapeffect .s7icon[state='active'] {
	opacity:1;
 }
.s7imagemapeffect .s7region {
	background:rgba(0,0,0, 0);
	border:1px solid #000000;
 }
.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|Component} container: either direct reference to SDK component to attach to, or an ID of such SDK component.
{s7sdk.ParameterManager} settings: A parameter manager object representing the desired configuration.
{String} compId: Does not apply to ImageMapEffect.

See:: s7sdk.MapDesc

Method Detail

addEventListener(type, handler, useCapture)

Adds an event listener to the particular ImageMapEffect component. The handler function receives a DOM event object of type Event. The object contains a property, s7event, that references the associated RolloverKeyEvent object.

The events supported by the component are:

s7sdk.event.RolloverKeyEvent.ROLLOVER_ACTIVATED - Dispatched when a map area is activated. s7sdk.event.RolloverKeyEvent

s7sdk.event.RolloverKeyEvent.ROLLOVER_DEACTIVATED - Dispatched when a map area is deactivated. s7sdk.event.RolloverKeyEvent

s7sdk.event.RolloverKeyEvent.TARGET_INDEX - Dispatched when a map area is clicked and its href represents internal hyperlink (i.e. is prefixed with target:). The target index will be available in frame property of the s7event field. s7sdk.event.RolloverKeyEvent

s7sdk.event.RolloverKeyEvent.QUICKVIEW_ACTIVATED - Dispatched when a map area is clicked and its href containes quick view data (i.e. is prefixed with quickview:). The quick view data associated with this image map will be available in quickViewData property of the s7event field as a JSON object. s7sdk.event.RolloverKeyEvent

s7sdk.event.RolloverKeyEvent.HREF_ACTIVATED - Dispatched always when an image map is clicked or tapped.The argument of the event (href property) contains raw href attribute value, without any parsing. s7sdk.event.RolloverKeyEvent

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

See:: s7sdk.event.RolloverKeyEvent

enableJavaScriptHrefs(enableScript)

Sets component's behavior corresponds to ImageMapEffect.enableJavaScriptHrefs.

Parameters:
{Boolean} enableScript: enable\disable evaluateJavaScriptLink.

getOverlaysVisible()

Returns whether or not overlay visibility is enabled.

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. .s7imagemapeffect .s7icon
{String} property: The CSS property that is being set. i.e. background-position
{String} value: The CSS property value being set. i.e. center

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

setOverlaysVisible(value)

Whenever set to true, the map area overlays is visible as long as they are available. This property is useful if the target component wants to temporarily hide the map overlays during a transition of some sort.

Parameters:
value

Namespaces

Classes in s7sdk.image

Class s7sdk.image.ImageMapEffect