Skip to main content

Methods

Initialization Example:
// create FSI Viewer element and set parameters
const instance = document.createElement("fsi-viewer")
instance.setAttribute("id", viewerId)
instance.setAttribute("src", "images/samples/shoe-brown.jpg")
instance.setAttribute("skin", "white")
instance.setAttribute("debug", true)
instance.setAttribute("plugins", "resize,fullScreen")
instance.style.width = '600px'
instance.style.height = '400px'
document.body.appendChild(instance)

// start viewer instance
instance.start()

// add method changeImage
const success = instance.changeImage({
    fpxsrc: "images/samples/sneaker/sneaker-white.jpg",
    effects: "contrast(10)"
  },
  '1,1,0.05,0.4,0.9,0.7,0'
)

// add listener onChangeImage
instance.addListener('onChangeImage', (parameters, view) => {
  console.log('Image is now:', parameters, view)
})

addListener​

const success = addListener(listenerName, fn, iScope)
Calls a specific listener. Listeners which are added via addListener(), remain valid when changeConfig() is called.
listenerName
string
Name of listener
fn
string
Name of function executed when listener is called
iScope
string
The scope of variables in which the callback function is called. This determines what the variable `this` means within the specified callback function. If iScope is not passed, iScope will be the instance of the viewer to which the listener has been added.
RETURN
boolean
Returns `true` if successful.
const success = instance.addListener('onZoomChanged',
  (scale, scaleMax, percent, preliminary) => {
  // code
})
Example

Consult Callbacks for an overview of all available listeners.

changeConfig​

changeConfig(cfgFileName, [parameters])
Reset the viewer object and change the configuration to the given configuration file.
cfgFileName
string
path to the configuration file (see cfg parameter)
parameters
object
Optional: object with start parameters. (the same parameters as in configuration files can be used)
RETURN
void
This function does not return a value.
instance.changeConfig('viewer_presets/no_user_interface.xml')
Example

changeImage​

const success = changeImage(parameters, [view])
Resets the viewer object and changes the image displayed to the given image file.
parameters
object
object containing parameters. If present, parameters will overwrite parameters defined upon initialization
view
string
Optional: specific image section defined as view string
RETURN
boolean
Returns `true` if succeeded.
const success = instance.changeImage({
    fpxsrc: "images/samples/sample.png",
    effects: "sepia()"
  },
  '1,1,0.05,0.4,0.9,0.7,0')
Example

clickMenuButton​

clickMenuButton(buttonID)
Sets the corresponding menu button to active.
buttonID
string
The button ID that needs to be activated.
RETURN
void
This function does not return a value.

See Overview of button IDs for FSI Viewer for a list of all available IDs.

instance.clickMenuButton('ToggleFullScreen')
Example

debugEnabled​

const success = debugEnabled()
Returns if the debug mode is enabled
RETURN
boolean
`true` = debug mode enabled, `false` = disabled
const success = instance.debugEnabled()
Example

debugError​

debugError()
Returns the corresponding viewer error messages in the console.
RETURN
mixed
error message
instance.debugError()
Example

debugLog​

debugLog()
Returns the corresponding viewer debug log messages in the console.
RETURN
mixed
log message
instance.debugLog()
Example

debugWarn​

debugWarn()
Returns the corresponding viewer debug warn messages in the console.
RETURN
mixed
warning messages
instance.debugWarn()
Example

destroy​

destroy()
Destroys the given FSI Viewer object. You should destroy the instance before you remove the object spins div tag from the DOM tree.
RETURN
void
This function does not return a value.

instance.destroy()
Example

dumpListeners​

dumpListeners()
Lists all listeners in the console and how often they were called.
RETURN
void
This function does not return a value.
instance.dumpListeners()
Example

getBuild​

const version = getBuild()
Returns a string containing the FSI Viewer software build number.
RETURN
string
software build number
const version = instance.getBuild()
Example

getConfigValue​

const value = getConfigValue(name)
Returns the value of any configuration parameter addressed with `name`.
name
string
Any FSI Viewer parameter, e.g. `src` or `skin`
RETURN
mixed
Requested parameter value
const value = instance.getConfigValue('src')
Example

getHotspotViewString​

const coordinates = getHotspotViewString(hotspotID)
Returns the view coordinates for the given hotspot ID.
hotspotID
string
Consecutive number of Hotspot (1,2,3,..)
RETURN
string
Hotspot coordinates
const coordinates = instance.getHotspotViewString('1')
Example

See getViewString for an explanation on how the view coordinates are composed.

getImageIsTransparent​

const success = getImageIsTransparent()
Initialises
RETURN
string
`true` = image is transparent
const success = instance.getImageIsTransparent()
Example

getInFullScreenMode​

const success = getInFullScreenMode()
Initialises
RETURN
string
`true` = viewer is currently in FullScreen Mode
const success = instance.getInFullScreenMode()
Example

getInitDone​

const success = getInitDone()
Returns if the initialization process is done.
RETURN
boolean
`true` = initialization process completed
const success = instance.getInitDone()
Example

getInstanceID​

const getID = getInstanceID()
Returns the number of the viewer object.
RETURN
integer
Viewer ID
const getID = instance.getInstanceID()
Example

getInstanceName​

const name = getInstanceName()
Returns the type of the viewer (e.g. FSI Viewer or FSI Pages) and the id attribute of the viewer object.
RETURN
string
Viewer ID attribute
const name = instance.getInstanceName()
Example

getMenuButtonPresent​

const success = getMenuButtonPresent(buttonID)
Shows if requested button ID is active.
buttonID
string
Button ID
RETURN
boolean
`true` = requested button is currently active

See Overview of button IDs for FSI Viewer for a list of all available IDs.

This can be used to remove inactive buttons from the menu if you are using a custom skin.

Note

Method only delivers correct results after the callback onInitMenu is called.

const success = instance.getMenuButtonPresent('HotSpots')
Example

getMenuHeight​

const height = getMenuHeight(purpose)
Returns a string containing the height of the menu bar in pixel.
purpose
string
If skin has a floating NavWindow (oSkinInfo.bFloatingNavWindow == true) and purpose == "navWindow", the return value is "0"
RETURN
integer
Height of the menu bar, exception: see above
const height = instance.getMenuHeight()
Example

getMouseMode​

const mode = getMouseMode()
Returns the current active mouse mode.
RETURN
integer
Active mouse mode

See Mouse Mode plugin for more info on mouse modes.

const mode = instance.getMouseMode()
// zoom mode
switch (mode) {
  case 0: // zoom
    // code
    break;
  case 1: // pan
    // code
    break;
  case 2: // rotate
    // code
    break;
}
Example

getParameters​

const param = getParameters()
Returns an object containing all parameters set via javascript or custom tag attributes.
RETURN
object
Object containing all parameters currently set
const param = instance.getParameters()

// return example:
/*
{
  id: 'myViewer',
  dir: 'images/samples/spin/',
  cfg: 'samples/spin.xml',
  autodisablepointeractions: 'true',
  inplacezoom: '1'
}
*/
Example

getPluginParameter​

const param = getPluginParameter(pluginName, parameterName, [defaultValue], [makeBoolean])
Returns the parameter defined for the given plugin.
pluginName
string
Name of the FSI Viewer plugin
parameterName
string
Name of the plugin parameter
defaultValue
Optional: value that is returned if desired PluginParameter is undefined
makeBoolean
boolean
Optional: specifies that a set value is converted into a boolean value. (0, "0" and "false" are converted to boolean false). Otherwise, the value is returned as it was set as a parameter (e.g. as a string).
RETURN
mixed
Parameter value of plugin parameter
const param = instance.getPluginParameter('autoSpin', 'interval')
Example

See Plugin Parameters for an overview of all available plugins for FSI Viewer.

getSkinClassName​

const skin = getSkinClassName()
Returns the name of the current used skin class, e.g. fsi-skin-black
RETURN
string
Name of the currently used skin class
const skin = instance.getSkinClassName()
Example

getSpinFrames​

const frame = getSpinFrames()
Returns the amount of spin frames.
RETURN
integer
Spin frame amount
const frame = instance.getSpinFrames()
Example

getSrcDim​

const dim = getSrcDim()
Returns the dimensions of the source image.
RETURN
object
Object with width and height of source image
const dim = viewer.getSrcDim()

/* return example:
{
  width: 5184,
  height: 3456
}
*/
Example

getVersion​

const version = getVersion()
Returns a string containing the FSI Viewer software version number.
RETURN
string
Software version number
const version = instance.getVersion()
Example

getViewString​

const view = getViewString()
Returns a string containing the current view.
RETURN
string
Current view

The format is: SceneSet, Scene, left, top, right, bottom.

SceneSet is 1 for rotations around one axis.

Scene describes the rotation. If you use 36 images for a spin, scene 18 means a rotation of 180 degree.

left, top, right, bottom: image coordinates in the range [0.0 to 1.0].

const view = instance.getViewString()
Example

getVisibleImageRect​

const rect = getVisibleImageRect()
Returns the image rectangle currently visible in FSI Viewer.
RETURN
object
Currently visible rectangle
const rect = instance.getVisibleImageRect()

/* return example:
{
  left: 0,
  top: 0.263021,
  right: 1,
  bottom: 0.736979
}
Example

getVisibleImageRectParameter​

const rect = getVisibleImageRectParameter()
Returns the image rectangle currently visible in FSI Viewer in simple parameter form.
RETURN
string
Currently visible rectangle
const rect = instance.getVisibleImageRectParameter()

// return example:
// 0,0.3,1,0.3
Example

getVisibleImageURL​

const url = getVisibleImageURL(width, height, [effects], [makeImageFitInto])
Returns the Image URL exactly as it is currently visible in FSI Viewer.
width
integer
Width of image displayed in image URL. `default` = same width as currently displayed
height
integer
Height o image displayed in image URL.`default` = same height as currently displayed
effects
string
Optional: effect that is used in image URL. Addressed in the same way as in FSI Viewer, e.g. `desaturate(average)`.
makeImageFitInto
boolean
Optional: `true`= image will be fitted into width and height
RETURN
string
Auto-generated responsive image URL.
const url = instance.getVisibleImageURL(200, 500, 'sepia()', true)

// or

const url = instance.getVisibleImageURL('default', 'default')

// return example:
// 'https://yourserver.com/fsi/server?width=200&effects=sepia()&type=image&source=images/samples/image.png'
Example

getZoom​

const zoom = getZoom()
Returns the current magnification level in percent.
RETURN
float
Zoom value in percent, `0` = normal scale without zoom, `100` = maximum magnification
const zoom = instance.getZoom()
Example

getZoomFloat​

const zoom = getZoomFloat()
Returns the current magnification level as a float value. 1.0 = no zoom, 2.5 = 2.5x magnification, etc.
RETURN
float
current magnification level
const zoom = instance.getZoomFloat()
Example

gotoHotspot​

const success = gotoHotspot(hotspotID, animate, zoom)
Displays the image section as specified by the Hotspot.
hotspotID
string
HotSpot ID
animate
boolean
`false` = view should be displayed immediately, `true` = animated movement from current view to specified view
zoom
boolean
100% zoom to defined hotspot section
RETURN
boolean
Returns `true` if successful.
const success = instance.gotoHotspot(2, true, true)
Example

gotoViewString​

const success = gotoViewString(view, animated)
Display the image section and rotation as specified by `view`.
view
string
Image section shown as viewString
animated
boolean
`false` = view should be displayed immediately, `true` = animated movement from current view to specified view
RETURN
boolean
Returns `true` if successful.

Please refer to getViewString to see the correct format required.

const success = instance.gotoViewString('1,15,0,0.229167,1,0.770833,0', true)
Example

hideMenuToolTip​

hideMenuToolTip()
Shows or hides custom tooltips which are displayed on hover.
RETURN
void
This function does not return a value.
instance.hideMenuToolTip()
Example

init​

const success = init(id, options, debug)
Initialises the chosen viewer element.
id
string
FSI Viewer Element ID
options
object
Object with start parameters. The same parameters as in configuration files can be used
debug
boolean
debug mode at initialization
RETURN
boolean
Returns `true` if the initialization succeeded.

This method is only needed if an FSI Viewer has not been started automatically (default).

const success = instance.init('fsi-123', {
  language: 'german',
  imageWidth: 250,
  quickZoomInPlaceZoom: true
}, true)
Example

makeBoolean​

const success = makeBoolean(value, [defaultValue])
Any value (int, float, string, boolean, undefined...) is converted to boolean value true/false.
value
string
Element
defaultValue
boolean
Optional: return value, if value === undefined.
RETURN
boolean
Returns `true` if successful.

Example: 0, "0", "false" and "FALSE" are converted to boolean false. Every number except 0, "1", "true" and "TRUE" are converted to boolean true.

const success = instance.makeBoolean('false')
Example

pressMenuButton​

pressMenuButton(buttonID)
Sets the menu button to pressed.
buttonID
string
Button ID
RETURN
void
This function does not return a value.

See Overview of button IDs for FSI Viewer for a list of all available IDs.

instance.pressMenuButton('ToggleFullScreen')
Example

printAPI​

printAPI()
Shows all API methods, listeners and button IDs in the console in alphabetical order.
RETURN
void
This function does not return a value.
instance.printAPI()
Example

registerExternalMenuButton​

registerExternalMenuButton(button, buttonID, [tip])
Registers an external menu button.
button
element
External button ID
buttonID
string
FSI Viewer Button ID
tip
string
Optional: custom tool tip for button
RETURN
void
This function does not return a value.

See Overview of button IDs for FSI Viewer for a list of all available IDs.

instance.registerExternalMenuButton('zoomIt', 'ZoomIn', 'It zooms!')
Example

registerExternalMenuButtonsFromContainer​

registerExternalMenuButtonsFromContainer(container)
Registers an external menu button from a specific container.
container
element
Container ID
RETURN
void
This function does not return a value.
instance.registerExternalMenuButtonsFromContainer('buttonContainer')
Example

releaseMenuButton​

releaseMenuButton(buttonID)
Releases the pressed menu button.
buttonID
string
Button ID
RETURN
void
This function does not return a value.

See Overview of button IDs for FSI Viewer for a list of all available IDs.

instance.releaseMenuButton('ToggleFullScreen')
Example

removeListener​

const success = removeListener(listenerName, fn)
Removes a specific listener.
listenerName
string
Name of listener.
fn
string
Name of function executed when listener is called
RETURN
boolean
Returns `true` if successful.
const success = instance.removeListener('onZoomChanged', yourFunction)
Example

resetView​

resetView()
Reset the viewer to the initial magnification and rotation.
RETURN
void
This function does not return a value.
instance.resetView()
Example

setFullScreenElement​

const success = setFullScreenElement(FSContainer)
Defines the FullScreen element.
FSContainer
element
Element ID
RETURN
boolean
Returns `true` if successful.
const success = instance.setFullScreenElement('buttonContainer')
Example

setMouseMode​

setMouseMode(mode)
Sets the active mouse mode.
mode
integer
Number of mouse mode
RETURN
void
This function does not return a value.

See Mouse Mode plugin for more info on mouse modes.

instance.setMouseMode('3')
Example

setZoom​

setZoom(percent, preliminary, animate)
Set magnification to the amount indicated
percent
float
Zoom amount [0...100], 0 = normal scale, 100 = maximum magnification
preliminary
boolean
`true` = magnification level is only temporary, so no additional image data will be loaded
animate
boolean
`true` = animate from current to given magnification level
RETURN
void
This function does not return a value.
instance.setZoom('50', true, true)
Example

showAboutWindow​

showAboutWindow()
Shows the About window.
RETURN
void
This function does not return a value.
instance.showAboutWindow()
Example

showMenuButton​

showMenuButton(buttonID, show)
Hides or displays the corresponding menu button.
buttonID
string
Button ID
show
boolean
`true` = button is displayed
RETURN
void
This function does not return a value.

See Overview of button IDs for FSI Viewer for a list of all available IDs.

instance.showMenuButton('ToggleFullScreen', false)
Example

showMenuToolTip​

showMenuToolTip(tip, src, x, y)
Shows custom tooltips that are handled like the general menu tool tips.
tip
string
HTML code of tooltip or ID in language.xml files
src
element
DOM element used to align tooltip, usually event.target
x
float
x offset for tooltip position
y
float
y offset for tooltip position
RETURN
void
This function does not return a value.
instance.showMenuToolTip('foo', btn, 0, 0)
Example

spinToDegree​

spinToDegree(degree)
Note that you can only spin to a position that has a corresponding HD image, not to a position that shows a video only
degree
integer
Desired position in degree (0 .. 360)
RETURN
void
This function does not return a value.
instance.spinToDegree(180)
Example

spinToTarget​

spinToTarget(targetFrame, [targetSceneSet], [frames])
Spins to the position indicated by the target parameters. Note that you can only spin to a position that has a corresponding HD image, not to a position that shows a video only.
targetFrame
integer
Number of target frame
targetSceneSet
integer
Optional: defines if scene set should be changed with an animation
frames
integer
Optional: Defines how many frames the animation will have. Setting it to 1 will spin directly to the target. The higher amount this parameter is set to, the smoother the animation will be and the longer it will take to switch from targetFrame to targetSceneSet.
RETURN
void
This function does not return a value.
instance.spinToTarget(2, 1, 12)
Example

start​

start()
Starts the viewer. Mandatory for initialization.
RETURN
void
This function does not return a value.
instance.start()
Example

startAutoSpin​

const success = startAutoSpin()
Activates AutoSpin. Only possible if the plugin AutoSpin is set.
RETURN
boolean
`true` = AutoSpin successfully started
const success = instance.startAutoSpin()
Example

stopAutoSpin​

const success = stopAutoSpin()
Stops AutoSpin. Only possible if the plugin AutoSpin is set.
RETURN
boolean
`true` = AutoSpin successfully stopped
const success = instance.stopAutoSpin()
Example

testAPIListenersStart​

testAPIListenersStart()
Starts the API test and shows all called listeners and the parameters which they return.
RETURN
void
This function does not return a value.
instance.testAPIListenersStart()
Example

testAPIListenersStop​

testAPIListenersStop()
Stops the API test.
RETURN
void
This function does not return a value.
instance.testAPIListenersStop()
Example

traceConfigValue​

const show = traceConfigValue(strName)
Traces a config value and enables you to see where (by parameter/attribute, in config files, the _default.xml, etc) a specific value is set.
name
string
Any FSI Viewer parameter e.g. `src` or `skin`
RETURN
mixed
Returns where parameter is set
const show = instance.traceConfigValue('src')

// return example:
// Tracing parameter "src"
// By Parameter/Attribute:
// images/samples/bag.png
// RESULT:
// src (alias: fpxsrc) = "images/samples/bag.png"
Example

unregisterExternalMenuButton​

const success = unregisterExternalMenuButton(button)
Unregisters an external menu button.
button
element
Button ID
RETURN
boolean
`true` = successfully unregistered
const success = instance.unregisterExternalMenuButton('zoomIt')
Example

unregisterExternalMenuButtonsFromContainer​

unregisterExternalMenuButtonsFromContainer(container)
Unregisters an external menu button from a specific container.
container
element
Container ID
RETURN
void
This function does not return a value.
instance.unregisterExternalMenuButtonsFromContainer('buttonContainer')
Example

updateSize​

updateSize()
Updates the size of a fsi-viewer element.
RETURN
void
This function does not return a value.
instance.updateSize()
Example