krpano embedding - j. marshall pittman

# Embedding into HTMLVersion 1.24 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()](https://krpano.com/docu/embedpano/#embedpano) function be called. Documentation topics: - [Script Including](https://krpano.com/docu/embedpano/#including) - [Viewer Embedding](https://krpano.com/docu/embedpano/#syntax) - [Embedding Parameters](https://krpano.com/docu/embedpano/#embeddingparameters) - [URL Query Parameters](https://krpano.com/docu/embedpano/#queryparameters) - [Viewer Removing](https://krpano.com/docu/embedpano/#removing) ## [Script Including](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/embedpano/#syntax) 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()](https://krpano.com/docu/embedpano/#embedpano) function: [embedpano](https://krpano.com/docu/embedpano/#embedpano)({...[embedding parameters](https://krpano.com/docu/embedpano/#embeddingparameters)...}) - The embedpano() function needs an Object with the [Embedding Parameters](https://krpano.com/docu/embedpano/#embeddingparameters) 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](https://krpano.com/docu/embedpano/#embeddingparameters) The embedpano() function requires an Object as argument. This Object is used to pass various settings. All parameters are optional. If they are not defined, their default values are used. The [Embedding Parameters Object](https://krpano.com/docu/embedpano/#embeddingobjectparameters) provides the following settings: embedpano({ [target](https://krpano.com/docu/embedpano/#target) : null, [xml](https://krpano.com/docu/embedpano/#xml) : null, [id](https://krpano.com/docu/embedpano/#id) : "krpanoSWFObject", [bgcolor](https://krpano.com/docu/embedpano/#bgcolor) : "#000000", [vars](https://krpano.com/docu/embedpano/#vars) : null, [initvars](https://krpano.com/docu/embedpano/#initvars) : null, [basepath](https://krpano.com/docu/embedpano/#basepath) : null, [cors](https://krpano.com/docu/embedpano/#cors) : false, [sameorigin](https://krpano.com/docu/embedpano/#sameorigin) : true, [consolelog](https://krpano.com/docu/embedpano/#consolelog) : false, [mwheel](https://krpano.com/docu/embedpano/#mwheel) : true, [capturetouch](https://krpano.com/docu/embedpano/#capturetouch) : true, [focus](https://krpano.com/docu/embedpano/#focus) : true, [webgl](https://krpano.com/docu/embedpano/#webgl) : true, [webglsettings](https://krpano.com/docu/embedpano/#webglsettings) : {webgl2:true, depth:true, stencil:true}, [webxr](https://krpano.com/docu/embedpano/#webxr) : "auto", [mobilescale](https://krpano.com/docu/embedpano/#mobilescale) : 1.0, [safearea](https://krpano.com/docu/embedpano/#safearea) : "auto", [touchdevicemousesupport](https://krpano.com/docu/embedpano/#touchdevicemousesupport) : true, [iosfullscreen](https://krpano.com/docu/embedpano/#iosfullscreen) : false, [passQueryParameters](https://krpano.com/docu/embedpano/#passQueryParameters) : false, [onready](https://krpano.com/docu/embedpano/#onready) : function(krpano){ ... } }); Note - the Embedding Parameters Object is available in the viewer as [embeddingparameters](https://krpano.com/docu/actions/#embeddingparameters) variable. The Embedding Parameters in detail: [target](https://krpano.com/docu/embedpano/#target):null - Set the target html-element in which the pano viewer should be embedded. - Can be either the id of a html-element or directly the html-element itself. - If not set (or set to null), the parent element of the current <script> element is used. - A Javascript alert() error is shown if no valid target is set or if no html-element with the given id can be found. [xml](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/embedpano/#id):"krpanoSWFObject" - The id of the internal viewer object. - This will be the object for interfacing the viewer via the [Javascript-Interface](https://krpano.com/docu/js/#top). - 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](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/xml/#layer.parent) layers) behind the pano (behind partial panos or 3D-models). - _Note - when using a transparent background, only normal crossfade [pano-blending](https://krpano.com/docu/actions/#loadpano.blend) is possible (other blending modes will automatically fallback to this)._ [vars](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/embedpano/#initvars):{...} - Pass an Object with krpano **variable:value** pairs. - This is basically the same as the [vars](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/xml/#url-notes) inside [url paths](https://krpano.com/docu/xml/#url-notes) in the xml files and / or to set variables that can be used inside [xml-if-checks](https://krpano.com/docu/xml/#if) for [<include>](https://krpano.com/docu/xml/#include) elements. - Example: embedpano({..., initvars:{mypath:"./panos1/"} }); XML: url="%$mypath%image.jpg" - To be able to pass [initvars](https://krpano.com/docu/embedpano/#initvars) variables via [http queries](https://krpano.com/docu/embedpano/#passQueryParameters) directly at the url of the html file this syntax need to be used: tour.html?initvars.variable=value [basepath](https://krpano.com/docu/embedpano/#basepath):... - Sets a custom path for resolving relative to the krpano viewer url paths. - Note - changing this will affect the [%VIEWER%](https://krpano.com/docu/xml/#url) url placeholder. [cors](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/xml/#security.cors) setting to use-credentials. [sameorigin](https://krpano.com/docu/embedpano/#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 if using the [passQueryParameters](https://krpano.com/docu/embedpano/#passQueryParameters) setting. - Image and media files are not affected by this settings. [consolelog](https://krpano.com/docu/embedpano/#consolelog):false - If enabled, the krpano [log/trace](https://krpano.com/docu/actions/#trace) messages will also be displayed in the Browser's Javascript console. [mwheel](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/xml/#control.disablewheel) setting. [capturetouch](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/xml/#control.capturetouch) setting. [focus](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/embedpano/#webgl):true - Use [WebGL](https://en.wikipedia.org/wiki/WebGL) for the rendering (recommended). - Instead of WebGL, [CSS 3D-transforms](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transforms/Using_CSS_transforms#3d_specific_css_properties) 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. - 2.0 - Only use WebGL 2.0, when not available an Error will be shown. - When WebGL and CSS 3D-transforms are not available, an Error will be shown. - Note - without WebGL these features are not available: - [Spherical, Cylindrical and Fisheye Panos](https://krpano.com/docu/xml/#image.type) (only Cubical and Flat Panos) - [Video-Panos](https://krpano.com/plugins/videoplayer/#top) - [Viewing Projections](https://krpano.com/docu/xml/#view.distortion) (Little-Planet-View) - [Depthmap / 3D-Model Panos](https://krpano.com/docu/xml/#depthmap) - [Pano-blending modes](https://krpano.com/docu/actions/#loadpano.blend) - [Mipmapping](https://krpano.com/docu/xml/#display.mipmapping) - [Postprocessing](https://krpano.com/plugins/postprocessing/#top) - [Chromakey](https://krpano.com/docu/xml/#hotspot.chromakey) and [alphachannel](https://krpano.com/docu/xml/#hotspot.alphachannel) hotspots - [Hotspot blendmodes](https://krpano.com/docu/xml/#hotspot.blendmode) - [WebGL Hotspot colormatrix filters](https://krpano.com/docu/xml/#hotspot.colormatrix) - [VR](https://krpano.com/plugins/webvr/#top) and [Stereo](https://krpano.com/docu/xml/#display.stereo) support - Note - without WebGL 2.0 these features are not available: - [Gaussian Splatting](https://krpano.com/docu/xml/#splats) - 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](https://krpano.com/docu/embedpano/#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](https://en.wikipedia.org/wiki/WebGL) - Use the [WebGL 2.0 API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext) when available (true by default). - If WebGL 2.0 will be available can be checked using the [device.webgl2](https://krpano.com/docu/actions/#device.webgl2) variable and the [devices](https://krpano.com/docu/xml/#devices) xml filter. - WebGL2 advantages in krpano: - Support for [3D-Gaussian-Splatting](https://krpano.com/docu/xml/#splats). - 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](https://krpano.com/plugins/threejs/) support. - [depth](https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.2.1) - 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](https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.2.1) - 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](https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.2.1) - 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](https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.2.1) - 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](https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.2.1) - 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](https://krpano.com/docu/embedpano/#webxr):"auto" - Control the [WebXR API](https://krpano.com/plugins/webvr/) 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](https://krpano.com/docu/embedpano/#mobilescale):1.0 - A setting for optionally using a different global scale for mobile devices. - See also the xml [stagescale](https://krpano.com/docu/actions/#stagescale) setting. [safearea](https://krpano.com/docu/embedpano/#safearea):"auto" - Enable or disable the general [Safe-Area](https://krpano.com/docu/xml/#display.safearea) 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](https://krpano.com/forum/wbb/index.php?thread/15736-krpano-1-19-pr14/&l=2&postID=73517#news119iphonex) [touchdevicemousesupport](https://krpano.com/docu/embedpano/#touchdevicemousesupport):true - A setting for optionally disabling the mouse support on touch devices. [iosfullscreen](https://krpano.com/docu/embedpano/#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](https://www.youtube.com/watch?v=uPtbSTrZYDU) will be used. [passQueryParameters](https://krpano.com/docu/embedpano/#passQueryParameters):false - With this setting it will be possible to pass/redirect [http-query parameters](https://krpano.com/docu/embedpano/#queryparameters) from the url to the krpano viewer as variables. - Possible values: - false (the default) - Don't pass any parameters. - "param1,param2,param3,..." - Define a custom list of comma-separated parameters that are allowed to be passed. - Limitations: - For security reasons not all parameters and values can be used! Parameters that could contain code or load something are filtered. - If setting the startup [xml](https://krpano.com/docu/embedpano/#xml) parameter will be allowed, then the given xml file paths are restricted to be within the current folder. - The length of a parameter value is limited to 30 characters. - The number of parameters is limited to 20. - Usage example: embedpano({..., passQueryParameters="startscene,design"}); ... tour.html?startscene=scene2&initvars.design=flat - Security Warning: Versions before 1.20.12 / 1.22.4 allowed also the usage of 'true' to allow all kind of parameters! This can open potentials for [Cross-site-scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) security vulnerabilities and should be strongly avoided! Updating to the latest krpano version or changing the settings to passQueryParameters:false is highly recommended! [onready](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/js/#krpanointerface) as argument. - _Notes - if a [startup xml](https://krpano.com/docu/embedpano/#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](https://krpano.com/docu/xml/#krpano.version)); krpano.actions.[loadpano](https://krpano.com/docu/actions/#loadpano)("pano.xml",null,null,null,function() { var hs = krpano.[addhotspot](https://krpano.com/docu/actions/#addhotspot)(); hs.type = "text"; hs.text = "Test Hotspot"; hs.ath = 20; hs.atv = 10; hs.onclick = function() { alert("Test"); } }); }}); ## [URL Query Parameters](https://krpano.com/docu/embedpano/#queryparameters) An URL can have a [Query String](https://en.wikipedia.org/wiki/Query_string) to set certain assigns parameters to specific values, e.g.: tour.html?bgcolor=transparent&antialias=false - By setting the embedpano() setting [passQueryParameters](https://krpano.com/docu/embedpano/#passQueryParameters) to a list of allowed variables, the values for these variables can be set directly from the URL. Additionally to custom variables, there are these settings, which can be always set by URL: - [bgcolor](https://krpano.com/docu/embedpano/#bgcolor) - change the default background-color or set it to transparent. - [webgl](https://krpano.com/docu/embedpano/#webgl) - enable or disable the WebGL support. - [webgl2](https://krpano.com/docu/embedpano/#webglsettings) - enable or disable the WebGL 2.0 support. - [antialias](https://krpano.com/docu/embedpano/#webglsettings) - enable or disable the WebGL Antialiasing support. ## [Viewer Removing](https://krpano.com/docu/embedpano/#removing) There are two ways for correctly removing a krpano viewer from the page and unloading / freeing all its allocated resources: [removepano](https://krpano.com/docu/embedpano/#removepano)(id) - The removepano() function can to be called either with: - the id of the html [target](https://krpano.com/docu/embedpano/#target) element, - or directly the html [target](https://krpano.com/docu/embedpano/#target) element itself, - or with the viewer [id](https://krpano.com/docu/embedpano/#id) that was defined during embedding. - Example: embedpano({target:"panoDIV"}); ... removepano("panoDIV"); or: embedpano({target:"panoDIV", id:"viewer1"}); ... removepano("viewer1"); [krpano.unload](https://krpano.com/docu/embedpano/#unload)() - When having a [krpano Interface Object](https://krpano.com/docu/js/#krpanointerface) (e.g. from [onready](https://krpano.com/docu/embedpano/#onready) callback) it is also possible to call its [unload()](https://krpano.com/docu/js/#unload) function to remove the krpano viewer. - Example: embedpano({..., onready:function(krpano) { ... krpano.unload(); }});