JavaScript API

The player has an external API so it can be controlled with JavaScript.

The skin uses this exact API. Since the skin files are not minified, you can simply peek into a skin file to figure out how some things are done internally.

All the examples below use obj as the object. However, if you use JavaScript in the skin, you must use player as the object.

Using JavaScript in the Skin Editor

There are two ways of using JavaScript in the Skin Editor:

Text Box

You can put JavaScript code into the text field of the Text Box skin element:

Start the text with javascript:. Everything that follows the : will be put into the innerHTML of the text box.

Normally, you would use this to do simple calculations. For instance, putting javascript:5+5 would display as 10.

But, you can misuse this to run any JavaScript code: put javascript:""; your JavaScript code goes here into the text element. This will then be executed when the skin is loaded. You could, for instance, register functions to certain player events:

javascript: ""; player.on("imagesready", function () {  alert("Object loaded!"); }); 

Go to URL Action

This lets you trigger JavaScript code by an action in the skin. For instance, add an action to a text element, set the source to Mouse Click, the action to Go to URL, and in the URL field add javascript: Your JavaScript code.... Like:

javascript: alert("Button clicked!"); 

Setup

obj.readConfigUrl(url: String, base: String="") Read the project configuration from a url. The base parameter defines a different base path.

obj.readConfigUrlAsync(url: String, callback: Function, base: String="") Same as readConfigUrl but asynchronous.

obj.readConfigString(xml: String) Read the project configuration from a string.

obj.readConfigXml(xml: Document) Read the project configuration from a XML Document object.

obj.getBasePath() obj.setBasePath(path: String) Get/set the base path. The base path is added to relative file names and urls. This is useful, if the HTML file has a different base then the xml configuration file. Also note that the placeholder $(r) gets replaced by the player’s base path.

obj.setCrossOrigin(s: String) Set the crossorigin attribute for all external files like the config, images, tiles and embedded videos. The default is anonymous.

Viewing direction

obj.getPan() Return the current pan angle.

obj.getPanN() Return a normalized current pan angle (between -180.0 and +180.0).

obj.setPan(angle_in_degrees: Number) Sets the current pan angle.

obj.changePan(offset_in_degrees: Number) Change the current pan angle.

obj.getTilt() Returns the current tilt angle.

obj.setTilt(angle_in_degrees: Number) Sets the current tilt angle.

obj.changeTilt(offset_in_degrees: Number) Change the current tilt angle.

obj.getFov() Return the current Field of View.

obj.setFov(angle_in_degrees: Number) Set the current Field of View.

obj.changeFov(offset_in_degrees: Number) Change the current Field of View.

obj.getZoom():Number, obj.setZoom(zoom :Number) Get/Set the zoom factor. obj.showObjectImage(x: Number, y: Number) To show the image with the given coordinates. obj.getX():Number, obj.setX(x :Number) Get/Set the pan coordinate (column) of the current image. obj.getY():Number, obj.setY(y :Number) Get/Set the tilt coordinate (row) of the current image.

obj.setPanTilt(pan: Number, tilt: Number), obj.setPanTiltFov(pan: Number, tilt: Number, fov: Number)

obj.setXY(x: Number, y:Number), obj.setXYZoom(x: Number, y:Number, zoom:Number)

Convenience functions.

obj.setDefaultView() Sets the view to the default view.

obj.moveTo(pan: Number, tilt: Number, fov: Number, speed: Number, x: Number, y: Number); Move the view to a position (using pan/tilt/fov values). obj.moveToXYZoom(x: Number, y:Number, zoom:Number, speed: Number, x: Number, y: Number); Move the view to a position (using x/y/zoom values).

obj.moveToDefaultView() Move the view to the default position.

Limits

The method names speak for themselves.

obj.canPanLeft():Boolean

obj.canPanRight():Boolean

obj.canTiltUp():Boolean

obj.canTiltDown():Boolean

obj.canZoomIn():Boolean

obj.canZoomOut():Boolean

Auto Rotation

obj.startAutorotate(speed: Number, delay: Number, rth: Number) Start (and enable) autorotation.

obj.toggleAutorotate(speed: Number, delay: Number, rth: Number) Toggle autorotation.

obj.stopAutorotate() Stop (and disable) autorotation.

obj.getIsAutorotating() If autorotation is currently running.

View states

obj.getState():Number Get the number of the current view state.

obj.getStateTitle(index? :Number):String Returns the title of a view state. The index parameter is optional, if omitted it returns the title of the current view state.

obj.changeViewState(index :Number, speed :Number) Change to a different view state.

Hotspots

obj.getPointHotspotIds():Array<String> Get all hotspot Ids as array of strings.

obj.getCurrentPointHotspots():Array<DomElement> Returns an array of all point hotspot divs.

obj.getHotspot(id: String):Object Get all the information of a hotspot as an object.

obj.getPolygonMode():Number, obj.setPolygonMode(v: Number, toggle: Number) Gets or sets the current polygon mode. If toggle is 1, it toggles between Off and the mode v.

obj.showOnePolyHotspot(id: String), obj.hideOnePolyHotspot(id: String), obj.toggleOnePolyHotspot(id: String) To show/hide a specific polygon hotspot.

obj.changePolyHotspotColor(id: String, bgColor: Number, bgAlpha: Number, borderColor: Number, borderAlpha: Number) Sets the background and border color of a specific polygon hotspot. You can use an empty string for id, to target all polygon hotspots.

For example, for a red, semi-transparent polygon with a solid green border: player.changePolyHotspotColor("Poly01", 0xff0000, 0.5, 0x00ff00, 1);

Use a hexidecimal number for the color, prefixed with 0x. The alpha value is a number between and including 0 and 1.

obj.setPolyHotspotHandcursor(id: String, enable: Boolean) Toggles the hand cursor for a specific polygon hotspot. You can use an empty string for id, to target all polygon hotspots.

obj.getHotspotPropValue(nodeId: String, hsId: String, varname: String) To retrieve the value of a custom hotspot property, defined in the project.

obj.setHotspotPropValue(nodeId: String, hsId: String, varname: String, value: Any) To set the value of a custom hotspot property, defined in the project.

Fullscreen

The method names speak for themselves.

obj.setFullscreen(flag:Boolean)

obj.enterFullscreen()

obj.exitFullscreen()

obj.toggleFullscreen()

obj.getIsFullscreen()

Miscellaneous

obj.setMargins(l: Number, t: Number, r: Number, b: Number) Lets you define margins around the player that you would normally define in the skin editor.

obj.setMargins(params:Object) Also lets you set margins around the player, like the function above, but gives you more options. The params object can contain (but does not have to contain all):

• left, top, right, bottom: each an object, containing value and unit, where unit should be either px or %.
• transition: an object containing duration and delay in milliseconds, and timingfunction. Supported values for timingfunction are: linear, ease, ease-in, ease-out, ease-in-out, step-end.

Example:

obj.setMargins({  left: { value: 30, unit: "%" },  transition: { duration: 500, timingfunction: "ease" }, }); 

obj.getViewerSize():Object Returns an object containing the ‘width’ and ‘height’ of the object player.

obj.getViewMode():Number, obj.changeViewMode(v: Number) Gets or sets the current view mode. 0 – Continuous Mode, 1 – Drag Mode, 2 – Toggle.

obj.getIsMobile() If the player is currently running on a mobile browser.

obj.getOS():Number The operating system the player is currently running on. 0 – Unknown, 1 – Windows, 2 – Mac, 3 – Linux, 4 – iOS, 5 – Android

obj.getBrowser():Number The browser the player is currently running in. 0 – Unknown, 1 – Chrome, 2 – Firefox, 3 – Safari, 4 – Edge, 5 – IE

obj.getBrowserTheme():Number The theme of the browser the player is currently running in. 0 – Light Theme, 1 – Dark Theme

Skin Variables

obj.getVariableValue(varName: String):Any, obj.setVariableValue(varName: String, varValue: Any) To access skin variables.

obj.setVariableOptions(varName: String, options: Object):Boolean In the options object, you can set:

• keep: when set to true, the variable is stored in a browser cookie, and will be updated from there when the project is opened again later
• cookiePath: the cookie path
• cookieExpireDays: a number, specifying how many days until the cookie expires

Returns true if successful.

obj.setSuperCookie(superCookieName: String, options: Object) In the options object, you can set:

• cookiePath: the cookie path
• cookieExpireDays: a number, specifying how many days until the cookie expires

Once a super cookie is defined, and you later set a variable to be stored in a cookie (with the setVariableOptions() function), this variable will not be stored in a separate cookie, but all such variables will be collected and stored in the one super cookie. This allows you to omit the 50 cookies per domain limit.

Translations

obj.getLanguage():String Returns the code of the language currently used by the player (like ’en’ or ’en-US’).

obj.setLanguage(langCode:String) Tells the player which language to use.

Events

The player provides an event system, where events are triggered at certain points, and you can register your own functions to those events.

obj.addListener(eventName:String, listener:Function)

obj.on(eventName:String, listener:Function)

Example code:

obj.on("viewstatechanged", function () {  alert("View State changed!"); }); 

obj.removeEventListener(eventName:String, listener:Function) To remove a previously registered function from a certain event.

obj.triggerEvent(eventName:String) To manually trigger a certain event.

A list of available events:

See also…

• HTML Template

• Web Output Properties

• Skin Editor