close panorama

Embedding into HTML Version 1.16
Select Version:

For embedding the krpano viewer into the HTML page the default swfkrpano.js Javascript should be used. This script does many important detection and setup things automatically, e.g. like the device/system feature detection (Flash or HTML5) and it also fixes automatically a lot of browser and system related issues and limitations (Mouse wheel usage). This makes the embedding itself easy and simple.
Documentation topics:

Functions of the swfkrpano.js script

  • Creating and embedding the krpano viewer into the HTML page.
  • Automatically checking for Flashplayer or HTML5 support and automatically loading the appropriate krpano viewer.
  • Making it possible to generate just one single Javascript file, which has all other krpano Javascript files embedded. When using the krpano MAKE PANO or MAKE VTOUR droplets with embedlicenses=true (the default), then this will be done automatically.
  • Several cross-browser, cross-system Mouse wheel fixes (page-scrolling, wheel-zooming, Mac support, touchpad/continues-wheel support, wheel speed normalization).
  • Fixing of several Flashplayer limitations when using wmode=transparent / opaque.
  • Automatically enabling the usage of the Flashplayer Fullscreen Mode.
  • It provides additional helper functions (device detection, parameter passing, ...).

Script Including

The embedding script should be included once anywhere in the html page. It can be included either in the html <head> or <body> element. Include it simply that way: 
<script src="swfkrpano.js"></script>
The swfkrpano.js script will automatically try to load the additional the krpano HTML5 viewer scripts (krpanoiphone.js and krpanoiphone.license.js) when necessary.

When a single, all-contained script file will be used, then just include that file - e.g.: 
<script src="tour.js"></script>

Additionally to the automatic-loading of the krpano HTML5 viewer scripts, it would be also possible to include them all manually: 
<script src="swfkrpano.js"></script>
<script src="krpanoiphone.license.js"></script>
<script src="krpanoiphone.js"></script>

Update Notes: Since version 1.16 the manual-include-order doesn't matter anymore and the automatic-loading doesn't cause a page-reload anymore!

Viewer Embedding

Create anywhere on the htmlpage a html <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 swfkrpano.js script provides two embedding functions for doing this - the createPanoViewer() function and the embedpano() function. Both functions have the same functionality, only their syntax and usage is slightly different.

createPanoViewer({...embedding parameters...});
  • The createPanoViewer() function accepts an object with parameters and returns an other object for additionally adding or changing parameters. The final embedding will be done when calling the embed() function of that returned object.
  • Example: 
    <script>
  var viewer = createPanoViewer({swf:"krpano.swf"});
  viewer.addVariable("xml", "pano.xml");
  viewer.embed("pano");
</script>

embedpano({...embedding parameters...});
  • The embedpano() function is basically the same as the createPanoViewer() function (same object with parameters) but with the difference that it directly embeds the viewer and doesn't return anything. It can be just seen as 'shorter' version of the embedding code and should be used in the most cases.
  • Example: 
    <script>
  embedpano({swf:"krpano.swf", xml:"pano.xml", target:"pano"});
</script>

Embedding Parameters

The createPanoViewer() and embedpano() functions are having only one argument - a single Javascript Object. This object is used to pass all parameters (in random order) by using parametername:value pairs. Almost all parameters (except target) are optionally - when they were not defined, their default values will be used.
The parameters object provides the following settings:

swf:"krpano.swf"
  • Name and path to the viewer swf file (relative to the html file).
  • The default is "krpano.swf".

xml:"krpano.xml"
  • Name and path to the pano xml file (relative to the html file).
  • By default the same name as name of swf file is used (e.g. krpano.xml for krpano.swf).

target:"...pano-div-id..."
  • The id of the html element where the viewer should be embedded. Can be overwritten in the embed() function.
  • There will be an 'alert()' error when there is no target set.

id:"krpanoSWFObject"
  • The id of the 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.

width:"100%", height:"100%"
  • Size (width and height) of the viewer object.
  • The sizes can be either absolute pixel values or a relative percent values.
  • The default is "100%" which means use the size of the parent html element.
  • Note - the recommended method for setting the size of the viewer would be setting the size of the parent html element! This way the viewer can resize itself automatically when the parent size changes. 

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

wmode:"..."
  • Set the Flashplayer wmode setting.
  • Possible settings:
    • window - The default setting, a compromise between system support and performance. Note: On many 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 (slower rendering performance).
    • transparent - Makes the Flashplayer background transparent to allow seeing html elements behind the Flashplayer and additionally also allow other html elements to overlap the Flashplayer (even more slower rendering performance).
    • 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/browsers this can cause heavy slowdowns).
  • HTML5 Notes: The wmode is typically a Flash-only setting, but wmode=transparent will be also evaluated by the krpano HTML5 viewer and makes there the background transparent too. Overlapping itself is always possible in the HTML5 viewer. 

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 Flash viewer will be used by default, and the krpano HTML5 viewer only when the Flashplayer is not available and the system/browser is HTML5-compatible.
    • prefer - Prefer the usage of the krpano HTML5 viewer when possible.
      With that setting, the krpano HTML5 viewer will be used by default, and the krpano Flash viewer only when the system/browser is not HTML5-compatible.
    • 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/browser will support it. Warning - this setting should be only used for internal testing!
    • never - Never use the krpano HTML5 viewer, force using the krpano Flash viewer.
  • Settings extensions for the HTML5 viewer: (for testing)
    • The html5 setting can be extended with 'webgl' or 'css3d' to define which rendering-technology should be prefered when both are available.
    • Usage examples: html5="auto+css3d", html5="prefer+webgl", ...
    • By default WebGL will be preferred - except for two cases:
      1. iOS - there WebGL is currently not available and therefore not tested - and to avoid problems if it might become available one day, CSS3D is preferred on these devices by default.
      2. Android Firefox - rendering-performance-tests on several Android devices had shown that CSS-3D is much better (faster, smoother) than WebGL on these devices - therefore CSS-3D is prefered in Android Firefox by default. 

vars:{...}
  • Pass a Javascript Object with krpano variable:value pairs.
  • Either set the krpano startup variables here.
  • Or set any other krpano variable. The variables will be set when xml file was loaded and parsed, so these variables can be used to overwrite variables/settings from the xml. 

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 html page).

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 then it will be also possible to pass the html5 setting directly at the html url. This makes it possible to switch between the Flash and the HTML5 version just by using different links.

The createPanoViewer Object Functions

The createPanoViewer() function accepts the same an object with parameters as the embedpano() function but also returns an new Javascript Object for additionally adding or changing parameters. This object provides additional functions for device support checking. The final embedding will be done when calling the embed() function of that object.
The createPanoViewer object provides the following functions:

viewer.addVariable(variable, value);
  • Either set the krpano startup variables here.
  • Or set any other krpano variable. The variables will be set when xml file was loaded and parsed, so these variables can be used to overwrite variables/settings from the xml. 

viewer.addParam(parameter, value);
  • Set Flashplayer parameters (e.g. wmode).

viewer.passQueryParameters();
  • Passes automatically all query parameters from the html to the viewer.

viewer.useHTML5(setting);

var ret = viewer.isHTML5possible();
Check if the usage of the krpano HTML5 Viewer is possible. 

var ret = viewer.isFlashpossible();
Check if the usage of the krpano Flash Viewer is possible (check if the Flashplayer Plugin is installed/enabled and if the Flashplayer version is 10.1 or higher). 

var ret = viewer.isDevice(devices);
  • Check if the current viewing device is one of the given devices.
  • devices:
    • "iPhone"
    • "iPod"
    • "iPad"
    • "Android"
    Several devices can be checked at once by connecting the devices by a '|' character: 
    if( viewer.isDevice("iPhone|iPod|Android") ) ...;

viewer.embed(target);
  • Finally embedded the krpano viewer to the given html target.
  • target (optionally)
    • Id of the html element.
    • When set, it will overwrite the target setting from the parameters object.

Startup / Embedding Variables

There are some special variables, which can be used when embedding the viewer. These variables will not directly passed to the viewer - they have a special meaning for the embedding itself:

  • xml
    With the xml variable it's possible to specify the path / name of the startup xml file.
    When no xml variable will set then the 'default loading' will be used, which tries to load a xml file which has the same 'basename' as the swf file (e.g. krpano.swf ⇒ krpano.xml or pano.swf ⇒ pano.xml or tour.swf ⇒ tour.xml and so on ...).

  • license
    By default and when no license is embedded, then the krpano Flash viewer tries to load a license file which has the same 'basename' as the swf file (e.g. krpano.swf ⇒ krpano.license or pano.swf ⇒ pano.license or tour.swf ⇒ tour.license and so on ...). But with the license variable it's possible to set a custom path / name of or to the license file.

  • simulatedevice
    This variable allow to test the iPhone / iPad / Android layouts and images on Desktop. Possible settings:
    • iphone - simulate the iPhone/iPod
    • ipad - simulate the iPad
    • useragent - simulate the device depending on the User-Agent
    • androidmobile - simulate an Android Mobile device (Flash only)
    • android or androidtablet - simulate an Android Tablet device (Flash only)
    The krpano iPhone/iPad Simulator (included in the viewer download package) is using that setting together with an iPhone / iPad background and an original sized viewing window.

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");

Notes about the usage on mobile devices (iPhone, iPad, Android)

There are some settings for the html file available that should be respected, when trying to get optimal results on all devices:

  • Always use the HMTL5 doctype for your html file: 
    <!DOCTYPE html>
  • For a correct 1:1 pixel-mapped display, any kind of automatic page / viewport scaling should be disabled. This can be done by using this <meta> viewport setting the html <head> element: 
    <meta name="viewport" content="target-densitydpi=device-dpi, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    Note: The 'target-densitydpi=device-dpi' setting is known only by Android and can cause a warning on other browsers (iOS, Chrome, ...) in the Javascript console - this warning can be ignored in this case.
  • Don't use <iframe> elements to include the viewer - always include the viewer directly on the page. When using iframes the page / viewport scaling inside the iframe can not be controlled and elements can appear in the wrong size. The scaling which can happen in this case, can also affect the display quality.

Examples

1. Most simple usage:

<script> embedpano({target:"pano"}); </script>
Here all default values will be used: "krpano.swf" as name for the flash viewer file, "krpano.xml" as default xml file, "krpanoSWFObject" as viewer id and 100% as size. Only the target where the pano should be embedded must be set.

2. Simple usage but with more settings:

<script>
  embedpano({swf:"pano.swf", xml:"pano.xml", target:"pano"});
</script>
Here also the paths to swf and xml files will be set.

3. Most simple usage of the createPanoViewer function:

<script>
  var viewer = createPanoViewer();
  viewer.embed("pano");
</script>

4. Typical usage of the createPanoViewer function:

<script>
  var viewer = createPanoViewer({swf:"tour.swf", target:"pano"});
  viewer.addVariable("xml", "tour.xml");
  viewer.embed();
</script>

5. Prefer the HTML5 viewer:

<script>
  embedpano({swf:"pano.swf", xml:"pano.xml", target:"pano", html5:"prefer"});
</script>

6. Set the wmode setting to opaque:

<script>
  embedpano({swf:"pano.swf", xml:"pano.xml", target:"pano", wmode:"opaque"});
</script>

7. Selective HTML5 usage - prefer HTML5 only on Android and on IE10 Touch devices:

<script>
  function selecthtml5usage()
  {
     // check for Android:
     if( navigator.userAgent.indexOf("Android") >= 0 )
       return "prefer"
     
     // check for IE10 with multi-touch display:
     if( (navigator.msMaxTouchPoints|0) > 1 )
       return "prefer"
     
     // for all other cases use html5=auto:
     return "auto";
  }
  
  embedpano({xml:"pano.xml", target:"pano", html5:selecthtml5usage()});
</script>