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.
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, ...).
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:
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.
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.
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>
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.
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.
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.
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.
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.
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.
By default WebGL will be preferred - except for these cases:
iOS (iPhone/iPad) - there WebGL currently isn't available and therefore not tested -
and to avoid problems if it might become available one day in future iOS versions, CSS3D is preferred
on these devices by default.
Android Stock/WebView-based browsers - on some Android devices the webview-based browsers are supporting
WebGL but with very different rendering performance results - some devices are very good while others are very bad -
so as compromise it's better not to use WebGL there by default yet.
Android Firefox < 22 - in Android Firefox versions before version 22 the WebGL rendering was
slow and laggy, so in these Firefox versions CSS3D will be preferred.
But with Firefox 22 (or newer) WebGL will preferred by default.
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.
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).
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.
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() 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.
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.
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).
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.
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).
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:
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.
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.