News Examples Documentation Download Buy Forum Contact
NOTE: This page is from an older version, see the latest version here.

Embedding into HTML Version 1.20.6

For embedding the krpano viewer into a HTML page the core 'krpano.js' script file (the filename can differ) need to be included and the embedpano() function be called. The embedpano function detects the browser support and decides which krpano viewer to use (the krpano HTML5 or krpano Flash viewer). When using the krpano Flash viewer, the embedding script also applies several Flashplayer and Browser fixes and workarounds (e.g. to enable the Mouse-wheel usage inside Flash on systems where this isn't supported). This makes the embedding of the krpano viewer easy and simple - just one script include and one line embedding code.

Script Including

The krpano script file need to be included once anywhere (but before the embedpano() usage) in the html page:
<script src="krpano.js"></script>

Some details and notes:
  • The 'krpano.js' file can be named different - e.g. when using the MAKE PANO or MAKE VTOUR droplets it's typically named 'pano.js' or 'tour.js'.
  • The file itself contains two parts - the krpano embedding script and the krpano HTML5 viewer. The krpano Flash viewer is a separate external file (e.g. the 'krpano.swf' file).
  • The file is always the same, it doesn't contain any pano or tour specific information, that means it could be shared across several panos/tours or projects.
    E.g. to make later updates easier just use only one global folder for the krpano viewer and plugins files and link from all other projects to them. Then all projects can be updated by only updating the global krpano files.

Viewer Embedding

Create anywhere on the html page a <div> element where the viewer should be embedded, give that div element an unique 'id' name and define its size via css styles:
<div id="pano" style="width:100%;height:100%;"></div>

After defining the <div> element, create a <script> element with the embedding script code.
For the embedding itself there is the global embedpano() function:

embedpano({...embedding parameters...});
  • The embedpano() function needs an object with the embedding parameters.

  • Full example:
    <script src="krpano.js"></script>
    
    <div id="pano" style="width:600px; height:400px;"></div>
    
    <script>
      embedpano({swf:"krpano.swf", xml:"pano.xml", target:"pano"});
    </script>

Embedding Parameters

The embedpano() function needs a Javascript object as argument. This object is used to pass all parameters (in random order) by using parametername:value pairs. Almost all parameters (except the target parameter) are optional - when they were not defined, their default values will be used.
The parameters object provides the following settings:

xml:"krpano.xml"
  • Name and path to the startup xml file (relative to the html file).
  • When not set, the filename of .swf file will be used (e.g. 'krpano.xml' for 'krpano.swf').
  • When no xml file should be loaded on startup, the value null can be used.

target:"...pano-div-id..."
  • The #id of the html element where the viewer should be embedded.
  • There will be an 'alert()' error when no target will be set.

swf:"krpano.swf"
  • Name and path to the viewer '.swf' file (relative to the html file).
  • The default is "krpano.swf".
  • This file will be only used for the Flashplayer, when using only HTML5 this file will be not required.

id:"krpanoSWFObject"
  • The id of the internal viewer object.
  • This will be the object for interfacing the viewer via the Javascript-Interface.
  • The default id is "krpanoSWFObject".
  • It is important that each viewer will have an unique id!
  • When there already exists an object with the given id, then the embedding script will automatically add numbers at the end of the id until it is unique.

bgcolor:"#000000"
  • The background color of the viewer (in html color format).
  • The default is "#000000" (=Black).

html5:"auto"
  • Set the krpano HTML5 Viewer usage.
  • Possible settings:
    • auto - The default setting - automatically use the krpano HTML5 viewer.
      With that setting, the krpano HTML5 viewer will be used when possible by default (since version 1.19, in older versions Flash was used as default)! When HTML5 will be not possible, then the Flash viewer will be used as fallback.
    • prefer - Prefer the usage of the krpano HTML5 viewer when possible, otherwise use Flash (same as auto since version 1.19).
    • fallback - Prefer the usage of the krpano Flash viewer when possible. Use the krpano HTML5 viewer only as fallback when Flash is not available.
    • only - Only use the krpano HTML5 viewer - never use the krpano Flash viewer.
      With that setting, the krpano HTML5 viewer will be used when possible. When the system/browser is not HTML5-compatible, then an error message will be shown.
    • always - Always use the krpano HTML5 viewer, regardless if the system and browser are supporting the therefore necessary capabilities!
      Note - This setting should be only used for internal testing, never for publishing!
    • never - Never use the krpano HTML5 viewer, force using the krpano Flash viewer.
  • Additional extensions settings (for controlling the rendering method):
    • +webgl - Use the krpano HTML5 viewer only when WebGL is available.
      Note - some features are only available when WebGL is available - e.g. panoramic-video-support, WebVR-support, stereo-rendering, spherical and cylindrical images, view distortions (fisheye, littleplanet), ...
    • +css3d - Prefer the usage of CSS3D rendering instead of WebGL rendering (by default WebGL will be preferred when available). The css3d setting should be only used for internal testing, never for publishing!
    Usage examples:
    • prefer+webgl - Use the krpano HTML5 viewer only when WebGL is available, otherwise use Flash.
    • only+webgl - Use the krpano HTML5 viewer only when WebGL is available, otherwise show an error message.

flash:""
  • Set the krpano Flash Viewer usage.
  • This is a basically the same as the html5 setting, just the inverse. It can be used for nicer urls, e.g. by using flash=prefer instead of html5=fallback.
  • When the flash setting will be set, it will be mapped to a html5 setting and overwrite it.
  • Possible settings:
    • auto or no setting - use the html5 setting.
    • prefer - Prefer the usage of the krpano Flash viewer when possible.
      Use the krpano HTML5 Viewer only when there is no Flashplayer and the system/browser is HTML5-compatible.
      This setting will be mapped to html5=fallback.
    • fallback - Prefer the usage of the krpano HTML5 viewer when possible. Use the krpano Flash viewer only as fallback when HTML5 is not available.
      This setting will be mapped to html5=prefer.
    • only - Only use the krpano Flash viewer - never use the krpano HTML5 viewer.
      With that setting, the krpano Flash viewer will be used when possible. When there is no Flashplayer, then an error message will be shown.
      This setting will be mapped to html5=never.
    • never - Never use the krpano Flash viewer, only use the krpano Flash viewer.
      This setting will be mapped to html5=only.

wmode:"..."
  • Set the Flashplayer wmode setting.
  • Possible settings:
    • window - The Flashplayer default, a compromise between system support and performance. Note - on some systems and browsers html elements can't overlap the Flashplayer in this mode! See this wmode link for details.
    • opaque - Allow other html elements to overlap the Flashplayer (depending on the system and browser this can cause slower and jerky rendering).
    • opaque-flash - Same as opaque but only for the Flashplayer (will be ignored by the HTML5 viewer - see the HTML5 notes below).
    • transparent - Make the Flashplayer background transparent to allow seeing html elements behind the Flashplayer and additionally also allow other html elements to overlap the Flashplayer (depending on the system and browser this can cause slower and jerky rendering).
    • transparent-flash - Same as transparent but only for the Flashplayer (will be ignored by the HTML5 viewer - see the HTML5 notes below).
    • direct - Best performance, hardware accelerated presentation, no html overlapping on many systems and browsers (this is typically the fastest mode but on incompatible or older systems and browsers this can cause slowdowns).
  • krpano will use wmode=direct by default, except for Chrome - there wmode=window will be used by default (better performance and no black window during resizing).
  • HTML5 notes: The wmode setting is typically a Flashplayer setting, but wmode=opaque and wmode=transparent will be evaluated also by the krpano HTML5 viewer and make the viewer background transparent there too. Overlapping html elements itself are always possible when using the HTML5 viewer.

localfallback:"http://localhost:8090"
  • When running HTML5 content locally with file:// urls several browsers (especially Chrome and Safari) are restricting the dynamic loading of data files! In the krpano HTML5 viewer this affects the xml and plugin loading.
  • For more information about this case please see here - Local Usage.
  • To avoid just getting a xml loading error in this case, the embedding script checks in this case if loading would be possible and if not, it offers some alternative solutions.
  • Possible settings:
    • An url of the krpano Testing Server (by default http://localhost:8090)
      • When the localfallback setting will be set to an url of the krpano Testing Server (the default case) and the server is currently already running, then the current page will be automatically redirected to the testing server to allow a full featured local usage.
      • When the server is not running, the error fallback case will be used.
    • flash - Use the krpano Flash viewer instead. The Flashplayer is not affected by the local browser restrictions.
    • error - Show an error and information message about local usage.
      The error message could be customized by using the onerror callback.
    • none - Ignore that they are local restrictions and start the HTML5 viewer anyway...

vars:{...}
  • Pass a Javascript Object with krpano variable:value pairs.
  • The variables will be set AFTER the xml file has been be loaded and parsed.
    So these variables can be used to add new settings or to overwrite settings that were already defined in the xml.
  • Example:
    var settings = {};
    settings["onstart"] = "trace('on start...')";
    settings["view.hlookat"] = 30;
    embedpano({xml:"pano.xml", target:"pano", vars:settings});

initvars:{...}
  • Pass a Javascript Object with krpano variable:value pairs.
  • This is basically the same as the vars setting, but these variables will be set BEFORE the xml file wil be loaded and parsed.
  • The main usage of this setting will be to set custom path variables that can be used as placeholders inside url paths in the xml files and / or to set variables that can be used inside xml-if-checks for <include> elements.
  • Example:
    embedpano({..., initvars:{mypath:"./panos1/"} });
    XML:
    url="%$mypath%image.jpg"
  • To be able to pass initvars variables via http queries directly at the url of the html file this syntax need to be used:
    tour.html?initvars.variable=value

basepath:...
  • Sets a custom base-path for resolving paths that are relative to the krpano swf file.
  • Can be used in Flash and HTML5 for adjusting relative paths in the xml.

consolelog:false
  • A Boolean setting that defines if krpano log/trace-messages should be sent also to the browser Javascript console.

mwheel:true
  • A Boolean setting to control the mouse-wheel support.
  • When set to true (the default), then the mouse-wheel events will be captured and can be used in the viewer (e.g. for zooming).
  • When set to false, then any mouse-wheel usage will be ignored and the browser will do its default mouse-wheel handling (typically scrolling the webpage).
  • The mouse-wheel support can be changed also at runtime by using the control.disablewheel setting.

capturetouch:true
  • A Boolean setting to control the captureing of touch events.
  • When set to true (the default), then the touch events will be captured and can be used in the viewer (e.g. for panning and zooming).
  • When set to false, then touch events itself will be still used by the viewer, but their default event processing will be not stopped. That means in this case the browser might pan or zoom the webpage.

focus:true
  • A Boolean setting to give the viewer the input / keyboard focus on startup.
  • When not set, the setting will be set automatically depending on the viewer size - when the viewer will cover the whole webpage, focus will be set to true, otherwise to false.
  • This works only in HTML5 (all browsers) and in the Chrome Flashplayer. In other browsers the Flash element requires an initial click by the user for getting the focus.

webglsettings:{preserveDrawingBuffer:false, depth:true, stencil:true, ...}
  • Pass an object with special settings for the WebGL context creation.
  • The WebGL context will be created at startup and can't be changed at runtime, therefore these settings need to be specified already during embedding.
  • Available settings:
    • preserveDrawingBuffer - Keep the drawing buffer content. Would need to be enabled for when trying to make screenshots of the WebGL canvas via toDataURL or readPixels in some browsers. Set to false by default for better performance.
    • depth - Create a depth buffer. Required for depthmap support and 3D-object rendering. Set to true by default, but could be disabled when not needed.
    • stencil - Create a stencil buffer. Required for a correct line rendering of polygonal-hotspots when using an alpha-transparent line-border color. Set to true by default, but could be disabled when not needed.
    • failIfMajorPerformanceCaveat - Don't use WebGL when the rendering performance would be dramatically lower than the OpenGL rendering performance of a native application. Set to false by default.
    • antialias - Set if anti-aliasing should be used - true or false.
      When not set, krpano decided itself for optimal performance because some device/browser/gpu combinations are performing very bad (e.g. half framerate) with enabled anti-aliasing. This setting should be used only for internal testing or very special cases.

webxr:"auto"
  • Control the WebXR API support.
  • For using the WebXR API it is neccesady to do several initial setup-steps already on startup, therefore the usage of the WebXR API need to be defined already when embedding the viewer.
  • Available settings:
    • auto (the default)
      • Use the WebXR API only on desktop browsers and dedicated VR systems/browsers. On Android mobile systems the alternative krpano MobileVR support has a currently a better and wider device support.
      • When the WebVR API and the WebXR API are both available the same time, then prefer the WebVR API. Today the WebVR API is still the better choice. It allows using oversampling for higher image quality and device specific performance optimizations. Both is currently not possible with the WebXR API, eventually future API versions and browsers might get better here.
    • preferwebvr
      • Prefer the WebVR API when WebVR and WebXR are both available.
    • prefer or true
      • Prefer the WebXR API when WebVR and WebXR are both available.
    • no or false
      • Don't use the WebXR API at all, always use the WebVR API or the krpano MobileVR support for VR display.

mobilescale:1.0
  • A setting for optionally using a different global scale for mobile devices.
  • See also the xml stagescale setting.

fakedevice:""
  • Fake the krpano device detection settings.
  • Available settings: "mobile", "tablet", "desktop".
  • Note - This setting should be only used for internal testing, never for publishing!

onready:...Javascript-Function...
  • The onready setting can be used to set a call-back-function to get notified when the embedding is done and the krpano viewer is ready for usage.
  • The given function will be called with the krpano Javascript-Interface object.
  • Example:
    embedpano({target:"krpanoDIV", onready:krpanoReady});
    
    function krpanoReady(krpano)
    {
        krpano.call("trace(krpano is ready...)");
    }
  • Flashplayer Notes: This function requires the External Interface of the Flashplayer! This means the call-back will work offline/locally only when the security settings of the Flashplayer were adjusted. See here for more detatils - Local / Offline Usage.

onerror:...Javascript-Function...
  • The onerror setting can be used to set a custom embedding-error-handling function.
  • The given function will be called with an error-message string as parameter.

passQueryParameters:false
  • A Boolean setting. When set to true, all query parameters from the html url will be passed to the viewer as variables.
  • When enabled, it will be also possible to pass the html5, flash, wmode, mobilescale, fakedevice and initvars settings directly at the html url.
  • Usage example:
    tour.html?html5=only&startscene=scene2&initvars.design=flat

Viewer Removing

For removing the pano viewer from the html page the removepano() function need to be used! The removepano() function will remove all internally attached mouse-fixes (Flash) and all DOM elements and events (HTML5).


removepano(id);
  • The removepano() function need to be called with the unique id of the viewer object.
  • Example:
    embedpano({target:"panoDIV", id:"pano1"});
    
    ...
    
    removepano("pano1");