close panorama

Embedding into HTML Version 1.19

For embedding the krpano viewer into a HTML page the krpano.js script (the filename can differ) and the embedpano() function need to be used. The embedpano function detects the browser support and decides which krpano viewer to use / to embed (HTML5 or Flash). When using Flash the krpano embedding script also applies several Flashplayer fixes and workarounds (e.g. it enables the Mouse-wheel usage inside Flash). 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 need to be included once anywhere (before the first usage) in the html page:
<script src="krpano.js"></script>

Some details:
  • The krpano.js file could be named different - e.g. when using the MAKE VTOUR droplets it's typically named 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).
  • 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 or projects.

Viewer Embedding

Create anywhere on the html page a <div> element where the viewer should be embedded, give it 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. The embedpano.js script provides a embedpano() function for the viewer embedding:

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 only one 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 there is no startup xml file, 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.
  • This can be used to set the krpano startup variables and also to set any other krpano variables or settings.
  • 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 usage.
  • 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).

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:false, stencil:false}
  • 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.
    • depth - Create a depth buffer, false by default. Would need to be enabled for the correct ThreeJS plugin usage.
    • stencil - Create a stencil buffer, false by default.
  • All these settings are disabled by default for performance and memory reasons (especially on mobile devices).

mobilescale:0.5
  • By default all krpano content on mobile devices will be scaled by 0.5.
  • To disable that scaling, set the mobilescale setting to 1.0.
  • This can be useful for implementing responsive webdesigns.
  • 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");