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.0.8.15

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.

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>

Or when a single all-contained .js file was created, just include that file: 
<script src="tour.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. But this causes a kind of page-reload which can be problematic in some cases - to avoid that, either use a single all-contained .js file or include all script files manually at once in that order: 
<script src="swfkrpano.js"></script>
<script src="krpanoiphone.license.js"></script>
<script src="krpanoiphone.js"></script>
Note - the include order of these files is important in this case!

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. Both functions have the same functionality, only their syntax and usage is slightly different. There are:

1. The createPanoViewer() function:

<script>
  var viewer = createPanoViewer({swf:"krpano.swf", target:"pano"});
  viewer.addVariable("xml", "pano.xml");
  viewer.embed();
</script>
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 the returned object.

2. And the embedpano() function:

<script>
  embedpano({swf:"krpano.swf", xml:"pano.xml", target:"pano"});
</script>
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.

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.

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

wmode:"..."
  • Set the Flashplayer wmode (window mode) setting.
  • Possible settings:
    • window - the default, a compromise between system support and performance.
    • 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 (typically the fastest mode but on incompatible or older systems/browsers this can cause heavy slowdowns).
  • HTML5 Notes: wmode=transparent will be evaluated also by the krpano HTML5 viewer and makes there the background also transparent. Overlapping itself is always possible in the HTML5 viewer.

html5:"auto"
  • Set the krpano HTML5 Viewer usage.
  • Possible settings:
    • auto - the default, automatically use the krpano HTML5 Viewer. This happens when the Flashplayer is not available and the system/browser is HTML5 compatible.
    • prefer or whenpossible - prefer the usage of the HTML5 viewer when possible.
    • always - always use the HTML5 viewer, regardless if really supported.
    • never - never use the HTML5 viewer, force using the Flash viewer.

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. 

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. 

html5licenseload:true
  • Try to load the krpano HTML5 license (the krpanoiphone.license.js) automatically when not already available / included.
  • This setting can be used to avoid a page-reload, when loading the license.

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);
  • Set the krpano HTML5 Viewer usage.
  • Possible settings:
    • auto - the default, automatically use the krpano HTML5 Viewer. This happens when the Flashplayer is not available and the system/browser is HTML5 compatible.
    • prefer or whenpossible - prefer the usage of the HTML5 viewer when possible.
    • always - always use the HTML5 viewer, regardless if really supported.
    • never - never use the HTML5 viewer, force using the Flash viewer.

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 9.0.28 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 = id of the html element (optionally, 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.

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 only known by Android and will cause a warning on iOS 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 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>