News Examples Documentation Download Buy Forum Contact

Embedding into HTML Version 1.22

To embed the krpano viewer into an HTML page, the script file krpano.js (the actual filename can differ) must be included and the embedpano() function be called.

Script Including

The krpano script file need to be included once anywhere on the html page:
<script src="krpano.js"></script>

Some details and notes:
  • The 'krpano.js' file can be named different - e.g. when using the MAKE PANO or MAKE VTOUR droplets it is typically named 'pano.js' or 'tour.js'.
  • The file itself contains the krpano viewer and when registered also the license information.
  • Typically the file is always the same for all panos and tours (unless custom protection settings were applied). That means the same file can be used and shared for multiple panos and tours.
    When hosting multiple panos and tours this is even a recommend way - use one global location for the krpano viewer and plugins files and refer from all other projects to them. With that updating the version will be much eaiser.

Viewer Embedding

Create anywhere on the html page a <div> element where the viewer should be embedded, give that div element 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 embed the krpano viewer using the global embedpano() function:

embedpano({...embedding parameters...})
  • The embedpano() function needs an Object with the Embedding Parameters as argument.
  • Full example:
    <script src="krpano.js"></script>
    
    <div id="pano" style="width:600px; height:400px;"></div>
    
    <script>
      embedpano({xml:"pano.xml", target:"pano"});
    </script>

Embedding Parameters

The embedpano() function needs an Object as argument. This Object is used to pass various settings. All parameters except target are optional - when they were not defined, their default values will be used.
The Embedding Parameters Object provides the following settings:
embedpano({
    target : "...",
    xml : null,
    id : "krpanoSWFObject",
    bgcolor : "#000000",
    vars : null,
    initvars : null,
    basepath : null,
    cors : false,
    sameorigin : true,
    consolelog : false,
    mwheel : true,
    capturetouch : true,
    focus : true,
    webgl : true,
    webglsettings : {webgl2:true, depth:true, stencil:true},
    webxr : "auto",
    mobilescale : 1.0,
    safearea : "auto",
    touchdevicemousesupport : true,
    iosfullscreen : false,
    passQueryParameters : false,
    onready : function(krpano){ ... }
});
Note - the Embedding Parameters Object is available in the viewer as embeddingparameters variable.


The Embedding Parameters in detail:

target:...
  • Set the target html-element where the pano viewer should get embedded.
  • Can be either the id of a html-element or directly the html-element itself.
  • There will be a Javascript alert() error when no target will be set or no html-element with the given id can be found.

xml:null
  • Name and path to the startup xml file (relative to the html file).
  • When no xml file should be loaded on startup, set the value to null.
  • Backward compatibility: When not set and a path to a swf file is set, then the given filename of the swf file will be used as name of the startup xml file (e.g. 'krpano.xml' for 'krpano.swf').

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).
  • Optionally the value transparent can be used to see the content (the website, bglayer layers) behind the pano (behind partial panos or 3D-models).
    • Note - when using a transparent background, only normal crossfade pano-blending is possible (other blending modes will automatically fallback to this).

vars:{...}
  • Pass an Object with krpano variable:value pairs.
  • 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 an 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 path for resolving relative to the krpano viewer url paths.
  • Note - changing this will affect the %VIEWER% url placeholder.

cors:false
  • Enable the sending of CORS (Cross Origin Resource Sharing) HTTP headers when loading files from external servers.
  • This can be necessary when the external server only allow selective access.
  • Same as when setting the security.cors setting to use-credentials.

sameorigin:true
  • A security feature as cross-site-scripting protection - when enabled (the default), the krpano viewer will load 'text' files (xml, scripts, plugins, ...) only from the same server (same 'origin').
  • Loading files from other origins (external servers, other domains) will be blocked and cause an 'External Access Denied' error. This avoids the possibility to inject unwanted files, especially when the passQueryParameters setting is set to true.
  • Image and media files are not affected by this settings.

consolelog:false
  • If enabled, the krpano log/trace messages will also be displayed in the Browser's Javascript console.

mwheel:true
  • Control the mouse-wheel support.
  • 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).
  • The mouse-wheel support can be changed also using the control.disablewheel setting.

capturetouch:true
  • Control the capturing of touch events.
  • When set to true (the default), then the touch events will be captured and can be used in the viewer (e.g. for panning and zooming).
  • When set to false, then touch events itself will be still used by the viewer, but their default event processing will be not stopped. That means in this case the Browser might pan or zoom the webpage.
  • This setting can be changed also using the control.capturetouch setting.

focus:true
  • When set to true (the default), the viewer will get the input / keyboard focus on startup.
  • When set to false, the current focus will be not changed.
  • 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.

webgl:true
  • Use WebGL for the rendering (recommended).
  • Instead of WebGL, CSS 3D-transforms could be used for displaying the panos, but compared to using WebGL this is very limited.
  • Settings:
    • true - Only use WebGL (the default).
    • false - Don't use WebGL, always use CSS 3D-transforms.
    • "auto" - Use WebGL when available, otherwise use CSS 3D-transforms.
  • When WebGL and CSS 3D-transforms are not available, an Error will be shown.
  • Note - without WebGL these features are not available:
  • Note - depending on the Browser and device the number of WebGL elements on a single webpage is limited (e.g. to only 8 WebGL elements). When requesting more WebGL elements, then the least recently used one will get released.
    This needs to be considered when putting multiple panos on one single webpage. For simple panos/tours disabling WebGL for this usage case can be an option.

webglsettings:{webgl2:true, depth:true, stencil:true, ...}
  • 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:
    • webgl2
      • Use the WebGL 2.0 API when available (true by default).
      • If WebGL 2.0 will be available can be checked using the device.webgl2 variable and the devices xml filter.
      • WebGL2 advantages in krpano:
        • Non-power-of-two textures also can use mipmapping.
        • Non-power-of-two textures can use repeatable texture-coordinates (needed for some .obj 3D-Models) without shader-workarounds.
        • Better ThreeJS support.
    • depth - Create a depth buffer. Required for depthmap support and 3D-object rendering. Set to true by default, but could be disabled when not needed.
    • stencil - Create a stencil buffer. Required for a correct line rendering of polygonal-hotspots when using an alpha-transparent line-border color. Set to true by default, but could be disabled when not needed.
    • 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 in some Browsers. Set to false by default for better performance.
    • failIfMajorPerformanceCaveat - Don't use WebGL when the rendering performance would be dramatically lower than the OpenGL rendering performance of a native application. Set to false by default.
    • antialias - Set if anti-aliasing should be used - true or false.
      When not set, krpano decided itself for optimal performance because some device/Browser/gpu combinations are performing very bad (e.g. half framerate) with enabled anti-aliasing. This setting should be used only for internal testing or very special cases.

webxr:"auto"
  • Control the WebXR API support.
  • For using the WebXR API it is neccesady to do several initial setup-steps already on startup, therefore the usage of the WebXR API need to be defined already when embedding the viewer.
  • Available settings:
    • auto (the default)
      • Use the WebXR API only on desktop Browsers and dedicated VR systems/Browsers. On Android mobile systems the alternative krpano MobileVR support has a currently a better and wider device support.
      • When the WebVR API and the WebXR API are both available the same time, then prefer the WebVR API. In such cases the WebVR API is typically the better choice.
    • preferwebvr
      • Prefer the WebVR API when WebVR and WebXR are both available.
    • prefer or true
      • Prefer the WebXR API when WebVR and WebXR are both available.
    • no or false
      • Don't use the WebXR API at all, always use the WebVR API or the krpano MobileVR support for VR display.

mobilescale:1.0
  • A setting for optionally using a different global scale for mobile devices.
  • See also the xml stagescale setting.

safearea:"auto"
  • Enable or disable the general Safe-Area support (for iOS devices with a notch).
  • Available settings:
    • auto (the default) - Automatically enable the Safe-Area support when the viewer gets embedded into a 'full-page' html-element.
    • true - Always enable the Safe-Area support. Could be used when the embedding-target-html-element is not full-page-sized during embedding.
    • false - Disable enable the Safe-Area support.
  • Note - in the html file there need to be also this <meta> setting in the html <head> element to be able to use the Safe-Area:
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, viewport-fit=cover">
  • More information: krpano Forum Post

touchdevicemousesupport:true
  • A setting for optionally disabling the mouse support on touch devices.

iosfullscreen:false
  • Enable / Disable (=default) the iOS HTML5 Fullscreen API support.
  • On iOS the HTML5 Fullscreen Mode is unfortunately not very usable. Every swipe downwards ends the fullscreen mode and this disrupts the typical panorama control. Additionally there will be always an non-adjustable exit-button in the left top corner.
  • Because of these restrictions, the HTML5 fullscreen mode support is currently disabled for iOS by default. As an alternative, the special iPhone Landscape Fullscreen Mode will be used.

passQueryParameters:false
  • With this setting it will be possible to pass/redirect http-query parameters from the url to the krpano viewer as variables.
  • Possible values:
    • false - don't pass any parameters (the default).
    • true - pass all parameters to the viewer. Deprecated! Will be removed in future versions due security implications. There will be a console message when enabled.
    • "param1,param2,param3,..." - define a custom list of comma-separated parameters that are allowed to be passed.
  • Usage example:
    tour.html?startscene=scene2&initvars.design=flat
  • Security Warning:
    When allowing all parameters (set to true) or parameters that can contain executable code to be passed, this can open potentials for Cross-site-scripting. If this can be a problem depends on the individual usage-case and the surrounding/containing website.

onready:...Javascript-Callback-Function...
  • The onready function will be called when the krpano viewer is ready for usage.
  • The given function will be called with the krpano Interface Object as argument.
  • Notes - when a startup xml file is set, the onready event will be called when all startup xml files are loaded.
  • Example:
    embedpano({target:"...", onready:function(krpano)
    {
      console.log("krpano is ready - version="+krpano.version);
      krpano.actions.loadpano("pano.xml",null,null,null,function()
      {
        var hs = krpano.addhotspot();
        hs.type = "text";
        hs.text = "Test Hotspot";
        hs.ath = 20;
        hs.atv = 10;
        hs.onclick = function()
        {
          alert("Test");
        }
      });
    }});

Viewer Removing

There are two ways for correctly removing a krpano viewer from the page and unloading / freeing all its allocated resources:

removepano(id)
  • The removepano() function can to be called either with:
    • the id of the html target element,
    • or directly the html target element itself,
    • or with the viewer id that was defined during embedding.
  • Example:
    embedpano({target:"panoDIV"});
    ...
    removepano("panoDIV");
    
    or:
    embedpano({target:"panoDIV", id:"viewer1"});
    ...
    removepano("viewer1");
    

krpano.unload()
  • When having a krpano Interface Object (e.g. from onready callback) it is also possible to call its unload() function to remove the krpano viewer.
  • Example:
    embedpano({..., onready:function(krpano)
    {
      ...
      krpano.unload();
    }});