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

For embedding the krpano viewer into a HTML page the embedpano.js script need to be used. This script does many important detection and setup things automatically, e.g. a 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 of the krpano viewer easy and simple - one script include and one line embedding code is enough.
Documentation topics:

Functions of the embedpano.js script

  • Creating and embedding the krpano viewer into the HTML page.
  • Automatically check for Flash or HTML5 support and automatically loading the appropriate krpano viewer.
  • 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.
  • The script can be also merged together with the krpano HTML5 viewer script into one single script file (e.g. a 'tour.js'). When using the krpano MAKE PANO or MAKE VTOUR droplets this will be done automatically by default.

Script Including

The embedding script need to be included once anywhere in the html page.
Include it simply that way: 
<script src="embedpano.js"></script>

When a single script file with an embedded HTML5 viewer will be used, then just include that file: 
<script src="tour.js"></script>

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="embedpano.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:

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

js:"krpano.js"
  • Name and path to the krpano HTML5 viewer '.js' file (relative to the html file).
  • By default the same path and base filename as set in the swf setting will be used, just with a '.js' extension instead of '.swf'.
  • This setting will be ignored when the HTML5 viewer is embedded into the embedding script file.

xml:"krpano.xml"
  • Name and path to the startup xml file (relative to the html file).
  • By default the same name as base filename of swf file will be used (e.g. krpano.xml for krpano.swf).

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

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

wmode:"..."
  • Set the Flashplayer wmode setting.
  • Possible settings:
    • window - The Flashplayer default, 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 slowdowns).
  • krpano will use wmode=direct by default, except for Chrome - there wmode=window will be used by default (better performance and no black during window resizing).
  • 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 on desktop and the krpano HTML5 viewer only when the Flashplayer is not available or when a mobile/tablet device will be used.
    • 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.
    • 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/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 when available.

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:
    • no setting - use the html5 setting.
    • auto - the same as html5=auto.
    • 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. 

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 is to set custom path variables, that can be used as placeholders inside url paths in the xml files.
  • Example: 
    embedpano({..., initvars:{mypath:"./panos1/"} });
    XML: 
    url="%$mypath%image.jpg"

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

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.

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

  • 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. Prefer the HTML5 viewer:

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

4. Set the wmode setting to opaque:

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

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