DHTML Viewers — Overview. 1

DHTML Viewers — JSP Reference. 1

DHTML Viewers — API Reference. 6

 

DHTML Viewers — Overview

Scene 7 Image Serving supports image zoom viewers based on DTHML/JavaScript technologies. A web site can incorporate the viewer in one of two forms:

A jsp-based solution, which is compatible with the Flash Basic Zoom Viewer and the Flash Advanced Zoom Viewer, including viewer commands, server interactions, and most viewer behaviors. This approach is recommended for most simple zoom applications, as well as most zoom target and swatching/image swapping applications.

A DHTML API, which provides low-level client-side control of all viewer components. This API is compatible with older Scene 7 viewer technologies. It is slated to be replaced with a new API in the future. API-level programming is recommended only if the jsp-based solution proves insufficient for a given application.[1]

DHTML Viewers — JSP Reference

The files dhtml/basicZoomTemplate.jsp (for simple zoom applications) and dhtml/genericZoomTemplate.jsp (for swatching and zoom targeting applications) provide functional JSP-based DHTML Zoom Viewers, with features corresponding to the basic and advanced Flash Zoom Viewers, respectively.

If the user interface provided by the templates does not need to be modified, they can be used as is, simply append the necessary commands to the URL to specify the image and other viewer configuration.

More commonly, the template body would be copied into an implementation jsp and modified to customize the user interface --- and for more advanced applications, the viewer configuration process or some viewer behaviors --- to suit a particular application. An experienced programmer can also incorporate the jsp code into other jsp-based web pages to embed the viewer.

See Also

Refer to the Flash Viewer Reference for important additional information repated to the configuration, control, and behavior of the basic and advanced zoom viewers, including full descriptions of all viewer configuration commands.

Include Files

The templates use a single server-side include file --- include/serverShared.jsp, which must be located on the same server from which the implementation jsp is served from.

Both viewers use a client-side (JavaScript) include --- sj_zoom.js. In addition, if the advanced zoom viewer is used for a swatching application, sj_swatch.js is required, and for an application that involves zoom targets, sj_target.js must be included as well. Naturally, all code related to swatching and/or zoom targets must be removed from the jsp if the include files are removed.

If the viewer JSP is served from a different domain than the JavaScript includes, the JavaScript variable sj_codebase must be defined before the first client-side include and provide the root path for the sj_*.js include files.

Example

Modify the JavaScript includes to remove support for swatches and to serve the includes from a different domain than that that of the jsp file:

<script language=”JavaScript”>
      sj_codebase=”http:/s7ondemand.scene7.com/is-viewers/dhtml/”;
</script>
<script type=”text/javascript” src=”http://s7ondemand.scene7.com/is-viewers/dhtml/sj_zoom.js”></script>
<script type=”text/javascript” src=”http://s7ondemand.scene7.com/is-viewers/dhtml/sj_target.js”></script>

Server-Side Viewer Configuration

The S7BasicViewer class encapsulates most of the server-side code needed to instantiate and configure the viewer. Following is a description of the public methods of this class.

S7BasicViewer Constructor

The instantiated object defines all configuration parameters for the viewer in form of member variables and assigns default values to them. These configuration variables have the same names as the viewer configuration commands. See below for a complete list of supported configuration parameters.

loadConfig

loadConfig checks the URL for the presence of a config= command. If found, the function makes a req=userdata request to the server to obtain  the viewer configuration from  Image Serving. The configuration data is updated with the returned values.

Calling this method is optional. It is only needed if Image Serving provides configuration data for the viewer. See the Flash viewer config command for additional information.

loadCommands

loadCommands parses the request, extracts all viewer configuration commands and updates the configuration parameters with that data.

configure

Obtains additional configuration data from Image Serving, verifies all settings, and converts certain configuration data to values suitable for the client-side (JavaScript) viewer implementation.

Returns ‘true’ if successful, or ‘false’ if any errors occurred.

insert

insert ( ’basic’ | ’generic’ , out )

If no error occurred when configuring the viewer, this method is called to insert all required client-side JavaScript code. The first parameter for this method must be either “basic” or “generic”; it specifies whether to insert code for the basic or advanced zoom viewer. The second parameter is also required and must always be out.

This method creates the SjZViewer JavaScript object and assigns it to a variable named s7zoom. This object can be further manipulated using the DHTML viewer API described below.

getErrorMsg

Returns a string object with a text description of the error(s) that occurred during viewer configuration. The template inserts an error alert instead of calling the insert method to create the client code for the viewer.

Example

Following is the default implementation of the configuration code, as found in the jsp templates:

S7BasicViewer viewer = new S7BasicViewer(request);
viewer.loadConfig(request);

viewer.loadCommands(request);

if (viewer.configure())

      viewer.insert(“generic”);

Server-side code may be added as needed, for example, to configure the viewer based on data obtained from a source other than the URL or config= records:

S7BasicViewer viewer = new S7BasicViewer(request);

viewer.zoomStep=1;

viewer.modifier=”op_usm=0.5,0.5”;

viewer.backgroundColor=”0xe0e0e0”;

viewer.image=myImage;

if (viewer.configure())

      viewer.insert(“generic”);

Viewer Configuration Commands/Variables

The S7BasicViewer configuration variables have the same names as the corresponding DHTML (and Flash) viewer commands.

Refer to the Flash viewer documentation for detailed descriptions of all viewer commands.

The following table lists all configuration variables/commands accepted by both the Basic and Advanced Zoom Viewers. Any deviations or restrictions from the corresponding Flash viewer command is noted in the Description section.

 

Basic Configuration Variable/Command

Description

backgroundColor

image view background color

config

viewer configuration image catalog entry

image

source image

maxZoom

zoom limit

modifier

image modifiers

navHighlightColor

navigator view highlight color

navHighlightThickness

navigator view highlight thickness

serverUrl

Image Server root path

transitionTime

smooth zoom effect duration

turnTime

image change fade time

waitIcon

custom wait animation (must be JPG, PNG, or GIF instead of SWF)

waitIconTimer

wait animation timer setup

zoomStep

zoom behavior

 

The swatch and zoom targets configuration commands/variables listed in the following tables are applicable only to the advanced DHTML zoom viewer (genericZoomTemplate.jsp):

 

Swatch Configuration Variable/Command

Description

swBorderColor

Swatch Border Color

swBorderThickness

Swatch Border Thickness

swCellSpacing

Swatch Cell Spacing

swDoReset

Reset View On Swatch Change

swHighlightColor

Selected Swatch Border Color

swHighlightThickness

Selected Swatch Border Thickness

swLayout

Swatch Cell Layout

swRetainSelection

Retain Selection on Swatch Change

swTextBold

Bold Swatch Labels

swTextColor

Swatch Label Color

swTextFontName

Swatch Label Font

swTextPosition

Swatch Label Position

swTextSize

Swatch Label Font Size

 

Zoom Targets Config Variable/Command

Description

numTargets

Zoom Target Count

ztgBorderColor

Zoom Target Border Color

ztgBorderThickness

Zoom Target Border Thickness

ztgCellSpacing

Zoom Target Cell Spacing

ztgHighlightColor

Selected Zoom Target Border Color

ztgHighlightThickness

Selected Zoom Target Border Thickness

ztgHotspotIcon

Hotspot Zoom Target Icon (must be GIF instead of SWF)

ztgLayout

Zoom Targets Layout

ztgTextBold

Bold Zoom Target Labels

ztgTextColor

Zoom Target Label Color

ztgTextFontName

Zoom Target Label Font

ztgTextPosition

Zoom Target Label Position

ztgTextSize

Zoom Target Label Font Size

 

UI Layout

Standard HTML programming techniques are used to control the layout of the viewer user interface.

HTML <div> elements are used to position the principal viewer components. izView is required, all other elements are optional and must be removed if not needed.

 

Element Id

Description

Corresponding Flash Skin Component

imageLabel

Displays the optional title for the current image.

txtImageLabel

izView

main image view

izView

izNav

Navigator view

navigator

swatchGrid

Root swatch for the primary swatch grid. Additional swatches are added to the right and below the root swatch according to swLayout and swCellSpacing.[2] If swatchGrid2 is enabled, the viewer will use this swatch grid only for the topmost parent swatch group.

swatchGrid

swatchGrid2

Root swatch for the secondary swatch grid. Additional swatches are added to the right and below the root swatch according to swLayout and swCellSpacing.[3]  When enabled, the viewer uses this swatch grid  for all child swatch groups (if any).

swatchGrid2

ztgGrid

Root zoom target thumbnail; additional zoom targets are added to the right and below this target according to ztgLayout and ztgCellSpacing.[4]

zoomTargetGrid

 

The remainder of the viewer UI, including the zoom and pan buttons, is implemented using <a> elements with their href attribute connected to the appropriate viewer member function. The template uses <img> elements to match the default appearance of the DHTML viewer to that of the Flash viewer, but naturally these can be replaced with other UI elements, as long as the href attribute continues to point to the appropriate viewer function.

DHTML Viewers — API Reference

The following section describes the JavaScript API for the client components of the DHTML viewer.

The DHTML viewer code is located in the JavaScript file dhtml/sj_zoom.js. Instantiate the viewer by creating an object of class SjZViewer. Class member functions are used to control the appearance, position, and behavior of the viewer. sj_zoom defines additional functions which are for internal use only.

SjZViewer Initialization

The SjZViewer class implements most of the functionality of the DHTML zoom viewer. All initialization functions, with the exception of the constructor, are optional.

SjZViewer      Constructor

SjZViewer ( isRoot, image [ , width, height  [ , imgWidth, imgHeight ] ] )

isRoot                    Image Serving root path; can be an absolute path in the same or a different domain as this page or a path relative to this page. Use ‘/is/image’ for typical installations.

image                     Image Serving image specifier. May include optional IS modifiers.

width, height         Zoom view size in pixels. Optional; specify null,null if not required.

imgWidth, imgHeight          Full-resolution size in pixels of image. If not specified, the client code will attempt to obtain this information from IS at run-time (slight performance penalty, no cross-domain support on certain platforms). Note that this must be the final size including any size changes caused by IS modifiers specified with image. The IS command req=props can be used to obtain the image size.

If the constructor finds a pre-defined <DIV> element with id=’izView’, it will use it as the primary view and ignore the width and height parameters. If no <DIV> element is found, the viewer will insert one at the current location in the HTML sized to width and height.

Member functions described below can only be called on a constructed object.

enableNav     Navigator View

enableNav ( [ pos, x, y, width, height ] )

pos                         ‘relative’ or ‘absolute’

x, y                          offset in pixels

width, height         size in pixels

Enables the navigator. If  a pre-defined <DIV> element with id=‘izNav’ exists, the navigator window is positioned in it and the function parameters are ignored, and the function returns a reference the navigator object.

If no suitable <DIV> element is found, a navigator window is created, sized, and positioned according to the specified parameters.

The color and thickness of the navigator highlight frame can be configured with the following member function of the navigator object:

setBorder ( thickness, color )

thickness               Navigator highlight frame thickness in pixels.

color                       Navigator highlight frame color. String formatted as a hexadecimal color (similar to HTML colors), with an optional 0x prefix.

Example

Configure the navigator using a <DIV> element and change the highlight to blue:

<div id='izNav' style='position:relative;width:50;height:50'></div>
...
<script>
   ...
   var s7nav = s7viewer.enableNav();

   s7nav.setBorder(2,”00ff00”);
   ...
</script>
...

initialRGN      Initial Image Region

initialRGNA ( rgna )

initialRGNN ( rgnn )

rgna                        A string formatted as follows: “x, y, width, height

x, y                          Top-left corner of the region. Pixel coordinates of the full-resolution image.

width, height         Size of the region. Pixel coordinates of the full-resolution image.

rgnn                        A string formatted as follows: “xn, yn, widthn, heightn

xn, yn                     Top-left corner of the region. Normalized coordinates in the range 0.0…1.0.

widthn, heightn    Size of the region. Normalized coordinates in the range 0.0…1.0.

Defines the rectangular region of the image to be shown initially and after reset(). rgna values are expressed as absolute pixel coordinates of the full-resolution image (see catalog::Targets), and rgnn values are expressed as normalized image coordinates in the range 0.0 to 1.0.

setBackground        Zoom View Background Color

setBackground ( color )

color                       View background color. String formatted as a hexadecimal color (similar to HTML colors), with an optional 0x prefix.

 Background color for parts of the image view which are not covered by the image. For example, setBackground(“eeeeee”); for light gray. Default is white.

setMaxZoom             Zoom Limit

setMaxZoom ( val )

val                           maximum zoom factor in %

Zoom limit in percent relative to the full-resolution image.            Default is 100%.

setZoomStep            Zoom Level Configuration

setZoomStep ( step )

step                        integer zoom step value (1,  2, or 3)

Specifies how many zoom actions are require to achieve half the resolution when zooming in or double the resolution when zooming out. See the zoomStep command in the Flash Viewer documentation for additional information.

setTurnTime Image Change Transition Time

setTurnTime ( interval )

interval                   transition time (seconds)

Specifies the duration of the image fade transition for setImage(). Set to 0 for a hard transition.

setTransitionTime   Zoom/Pan Transition Time

setTransitionTime ( interval )

interval                   transition time (seconds)

Specifies the maximum time a zoom or pan action should take to achieve the target view. Set to 0 to disable smooth zoom/pan.

setWaitIconURL       Wait Icon

setWaitIconURL ( path )

path                        URL for GIF file

Specifies the static or animated gif file which is displayed when the viewer is waiting for data to be loaded.

setWaitIconTimer    Wait Icon Delay

setWaitIconTimer ( showDelay, hideDelay )

showDelay            show delay time in seconds (real)

hideDelay             hide delay time in seconds (real)

showDelay specifies how long the viewer should wait before showing the wait icon after sending an image data request to the server. This avoids displaying the wait icon unnecessarily when data is received quickly. Defaults to 0.5 sec.

hideDelay specifies how long the viewer should wait before removing the wait icon after requested image data has been received. This avoids flashing of the wait icon while the user is actively panning or zooming. Defaults to 0.1 sec.

SjZViewer Operations

All member functions listed in this section can be called repeatedly at any time.

pan     Pan Image

pan ( dir, dist )

dir                           Direction in which to pan the image. Can be one of the following strings: 'leftup', 'up', 'rightup', 'left', 'right', 'leftdown', 'down', 'rightdown'

dist                          Number of pixels to move in the specified direction. If a diagonal direction is specified, the distance value is applied to both x and y directions; in this case, the actual distance moved is dist times the square root of 2).

reset   Reset to Initial Zoom/Pan

reset ( )

Changes the view to show the default image region, as specified with initialRgn.

setImage       Change Image

setImage ( image, reset [ , imgWidth, imgHeight ] )

image                     New image to be zoomed. Image Serving image specifier. May include optional IS modifiers.

reset                       ‘false’ or not specified to maintain the current zoom factor and position, ‘true’ to show the new image at the reset view (as defined by initialRGN).

ingWidth, imgHeight           Full-resolution pixel size of the new image. Assumed to be the same as the previous image if not specified. Note that this must be the final size including any size changes caused by IS modifiers specified with image. The IS command req=props can be used to obtain the image size.

setRGN          Zoom/Pan To Target

setRGNA ( rgna )

setRGNN ( rgnn )

rgna                        A string formatted as follows: “x, y, width, height

x, y                          Top-left corner of the region. Pixel coordinates of the full-resolution image.

width, height         Size of the region. Pixel coordinates of the full-resolution image.

rgnn                        A string formatted as follows: “xn, yn, widthn, heightn

xn, yn                     Top-left corner of the region. Normalized coordinates in the range 0.0…1.0.

widthn, heightn    Size of the region. Normalized coordinates in the range 0.0…1.0.

Zooms and pans the view to the specified image rectangle. rgna values are expressed as absolute pixel coordinates of the full-resolution image (see catalog::Targets), and rgnn values are expressed as normalized image coordinates in the range 0.0 to 1.0.

zoomIn           Zoom In

zoomIn ( )

Zoom in by one zoom level. Ignored if already at the highest zoom level, as set by setMaxZoom. The view will stay centered on the same image pixel.

zoomOut        Zoom Out

zoomOut ( )

Zoom out by one zoom level. Ignored if already fully zoomed out. The view will stay centered on the same image pixel when possible; shifting will occur to ensure that the entire view is filled with image data as much as possible.

SjZViewer Event Callbacks

The DHTML viewer supports a set of event callbacks which allow the application to implement event handlers for advanced customization. 

For example, to be notified when a zoom-in event occurs, the application would create the following function (assuming that the SjZViewer object is named s7zoom):

s7zoom.onEvent.onImageZoomedIn = function(scale)

{

      //application code goes here

}

onImageZoomedIn  Zoom In Event Handler

onEvent.onImageZoomedIn ( scl )

scl                           new IS scale factor (real)

Called when the view is zoomed in (in response to calling zoomIn() or setRGN()).

onImageZoomedOut           Zoom Out Event Handler

onEvent.onImageZoomedOut ( scl )

scl                           new IS scale factor (real)

Called when the view is zoomed out (in response to calling zoomOut() or setRGN()).

onImageResetted    Zoom/Pan Reset Event Handler

onEvent.onImageResetted ( scl )

scl                           new IS scale factor (real)

Called when the view is reset (in response to calling reset() or setImage()).

onImageChanged    Image Change Event Handler

onEvent.onImageChanged ( oldImage, newImage )

oldImage               previous image

newImage             new image

Called when the image changes (from setImage()).

onRegionSet Zoom/Pan To Target Event Handler

onEvent.onRegionSet ( rgna )

rgna                        zoom target region in pixels (see setRGN)

Called when the view region changes (in response to calling setRGN).

 

Copyright © 2000 - 2006 Scene 7, Inc. All rights reserved.



[1] Note that additional jsp-based viewers are under development, comparable with the corresponding Flash viewers.

[2] While the swatchGrid <DIV> element  initially only reserves space for the first swatch, the viewer eventually will expand it to accommodate all parent swatches.

[3] While the swatchGrid2 <DIV> element  initially only reserves space for the first swatch, the viewer eventually will expand it to accommodate all swatches in the largest child swatch group.

[4] While the ztgGrid <DIV> element  initially only reserves space for the first zoom target, the viewer eventually will expand it to accommodate all zoom targets.