« For Developers: Embedding, JS, APIs

Micrio JavaScript API - Legacy pre-v3.2

The JS API documentation for older Micrio client versions

WARNING: This documentation is for older Micrio client versions (pre 3.2), and is no longer updated. For the most up-to-date version, go to the v4 JS API documentation for documentation on markers, tours and audio.

1. The Micrio class

You can create or access existing Micrio images using Javascript. The Micrio object is the basis for accessing the camera, events, and marker classes.

Accessing the JS instance

You can access a Micrio image in Javascript by referencing a <micr-io> embed like this:

let image = document.getElementById('your-micrio-id').micrio;

Properties

Property Type Description
camera camera A reference to the camera controller object
container HTML element The Micrio main DOM element
data Object The image settings as received from the editor
el HTML Element The Micrio <canvas> DOM element
height Number The original image height
id String The image ID
modules modules A reference to the modules controller object
onDraw Array Array with functions triggered for every frame drawn
startView Array The client or editor specified start view
thumbSrc Url The thumbnail image src for this image (direct link)
width Number The original image width

Methods

Method Returns Description
show() Promise This initializes and shows the image, returning a promise for when the initial view is fully downloaded.
hide() Use this to remove the image from the DOM and remove all event handlers
setSharpRatio(float) Set the image sharpness. 1 is default, 2 would make all pixels 200% larger, but will decrease tile downloads
setZoomLimit(float) Set the maximum level the user can zoom to. Defaults to 1 (100%)

Events

Event name Description
hide Fires when the image is hidden or destroyed
load Fires when the image is loaded and ready to be shown
preset Fires when settings for this image have been loaded and the image is ready for its first draw
show Fires when the image is fully loaded and shown

2. The Camera class

Properties

Property Type Description
events events A reference to the events controller object

Methods

Method Returns Description
draw() Forces a redraw of the current canvas
flyTo(x, y, scale, duration (ms)) Promise Fly to a certain coordinate and zoom level. Returns a promise for when the animation is done.
flyToCoverView(duration (ms)) Promise Fly to a cover-view of the image, like CSS background-size: cover
flyToFullView(duration (ms)) Promise Fly to a full overview of the image
flyToView(viewport ([x0,y0,x1,y1]), duration (ms)) Promise Fly to the specified view of the image
fullScreenToggle() Toggle image fullscreen mode. This only works when called within a user event handler (click, touch).
getCoo([xPx, yPx]) Coordinates Gets relative image coordinates based on X and Y in pixels
getView() Viewport [x0,y0,x1,y1] Gets the current screen viewport
getXY([xPerc, yPerc]) Screen pixels [x,y] Gets screen pixel coordinates based on an image coordinate [x,y]
hook() Hook all event types (resize, pan, zoom, swipe, pinch)
isZoomedOut() Boolean Return true if the user is fully zoomed out
onresize() Resizes the Micrio canvas element to fit its container after a manual element resize
pause() Pauses any camera animation
reset() Resets the viewport to the starting view
resume() Resumes any camera animation
setCoo([xPerc, yPerc]) Sets viewport coordinates without animating
setScale(scale) Immediately sets the image scale to this (1 = 100%)
setView(viewport ([x0,y0,x1,y1])) Immediately sets current viewport
unhook() Unhook all event types (resize, pan, zoom, swipe, pinch)
zoomIn(factor, duration (ms)) Zooms in factor (default 1) taking duration ms (default 0)
zoomOut(factor, duration (ms)) Zooms out factor (default 1) taking duration ms (default 0)

Events

These events are fired on the Micrio JS instance (not the HTML element)

micrioInstance.addEventListener('move', e => {
	console.log('Current viewport:', e.detail);
});
Event name Description
draw When a frame is drawn, even if the camera position didn't change
move Fires only on unique framedraws, meaning when the camera has panned/zoomed
zoom Fires only when the image is being zoomed

3. The Camera.Events class

This class contains all the internal Micrio event handlers for user interactions (mouse and touch).

Properties

This class has no relevant public properties.

Methods

Method Description
hook() Hook all user input event types (pan, mousewheel zoom, swipe, pinch)
hookDrag() Hook panning and dragging events
hookKeys() Hook keyboard controls
hookPinch() Hook trackpad/touchscreen pinching for zooming
hookScroll() Hook mousewheel/trackpad scrolling for zooming
unhook() Unhook all user input event types (pan, mousewheel zoom, swipe, pinch)
unhookDrag() Unhook pan and dragging events
unhookKeys() Unhook keyboard controls
unhookPinch() Unhook trackpad/touchscreen pinching controls
unhookScroll() Unhook mousewheel/trackpad scrolling for zooming

4. The Micrio.Modules class

The Micrio.Modules class contains all functionality relating to the minimap, markers, tours, and audio.

Properties

Property Type Description
markers Markers A reference to the Markers controller object
markerTours MarkerTours A reference to the MarkerTours objects
minimap MiniMap A reference to the MiniMap controller object
navigator Navigator A reference to the Navigator controller object
tours Tours A reference to the Tour objects

Events

All events are fired on the Micrio container element.

Event name Description
metadata Fires when all image module metadata (markers, tours, audio) has been loaded

5. The Markers class

Properties

Property Type Description
_container HTML Element The DOM marker container element
items Array of markers An array of all existing markers

Methods

Method Description
place() Places all markers on the image
remove() Removes all markers from the image
addItem(marker) Add a new marker to the image

6. The Marker class

This class is the controller for all Markers that have been added to the image in the editor.

Properties

Property Type Description
_container HTML Element Gets the marker HTML container element
_marker HTML Element Gets the marker HTML marker icon element
audio String The marker audio URL when entered
body String The marker body text
class String Any custom class names entered in the editor
data Object Any custom JSON added to the marker
html String Any custom HTML added to the marker in the editor
iconUrl URL Gets or sets the icon image URL to use as marker icon
images Array An array of image URLs added to the marker in the editor
json Object All marker data from the editor
onbeforeopen Function Gets or sets the function to call when the marker is opened, but the camera hasn't started animating yet
onbeforeclose Function Gets or sets the function to call at the start of the marker closing handling
onclose Function Gets or sets the function to call when the marker is closed
onflownto Function Gets or sets the function to call when the camera animation to the marker view has finished
onopen Function Gets or sets the function to call when the marker is opened
opened Boolean Returns whether the marker is opened or not
popup Popup controller The marker main popup controller object
popups Array of Popups All marker popup controllers
title String The marker title
view Viewport The viewport to zoom to when the marker is opened
x Number Gets or sets the X-coordinate (0-1) of the marker on the image
y Number Gets or sets the Y-coordinate (0-1) of the marker on the image

Methods

Method Description
close() Close the marker
open() Open the marker
draw() Force an individual marker draw action
addPopup(popup) Add an individual Popup to this marker

Events

Event name Description
marker-closed Fires when this marker has been closed
marker-open Fires when this marker has been opened
marker-opened Fires when this marker has been opened and the camera has flown to its viewport

7. The Marker.Popup class

Properties

	<tr>
		<td><code>onclose</code></td>
		<td>Function</td>
		<td>Gets or sets the function to call when the popup is closed</td>
	</tr>
	<tr>
		<td><code>onopen</code></td>
		<td>Function</td>
		<td>Gets or sets the function to call when the popup is opened</td>
	</tr>
</tbody>
Property Type Description
_audio HTML Element Returns the marker audio HTML5 element if entered
_body HTML Element Gets the popup body contents element
_container HTML Element Gets the popup container container element
_content HTML Element Gets the popup main content element
_html HTML Element Gets the popup custom HTML container element
_images HTML Element Gets the popup images container element
_title HTML Element Gets the popup title element

Methods

Method Description
close() Close the popup
open() Open the popup

8. The MarkerTour class

The MarkerTour class contains all functionality relating to the marker tours.

A Marker Tour itself is no more than a sequence of marker IDs coming from the editor. This class allows you to stop and start a marker tour.

Property Type Description
_controls HTML Element The HTML controls element shown when the tour is running (previous, next, steps)
steps Array of Markers Returns the ordered list of all the tour Marker steps
onstart Function Gets or sets the function to call when the tour is started
onstop Function Gets or sets the function to call when the tour is stopped

Methods

Method Description
goto(step (index int)) Open the specified step in the tour
next() Go to the next step in the tour
prev() Go to the previous step the tour
start() Start the tour
stop() Stop the tour

Events

All events are fired on the main Micrio container element (<micr-io>). The reference to the marker-tour object is the argument event.detail.

Event name Description
markerTours-start Fires when this tour has been started
markerTours-stop Fires when this tour has been stopped

9. The MiniMap class

The MiniMap class contains all functionality relating to the minimap navigator of the image.

Properties

Property Type Description
_el HTML Element The minimap HTML container element

Methods

Method Description
draw Force a redraw of the minimap
hook Hook the minimap to the image navigation
hookEvents Hook user event listeners (zoom, pan)
remove Remove the minimap
show Place the minimap
unhook Unhook the minimap to the image navigation
unhookEvents Unhook user event listeners (zoom, pan)

10. The Navigator class

The Navigator class contains all functionality relating to navigating from one image to another.

With Micrio, you can navigate between images inside the same Micrio instance. You can even switch from 360° images to 2D images. When you navigate to another image, any playing audio, including music, also switches to the new image.

Properties

This class has no relevant public properties.

Methods

Method Description
goto(id) Navigate to Micrio image with id id
getCurrent() Returns the current active Micrio image

11. The Tours class

A Tour class controls a video tour made in the editor.

This is a sequence of viewports put out over a timeline, with an optional single audio file. Once a tour is started, no user interaction is required to finish it.

Properties

Property Type Description
_controls HTML Element The controller HTML element container
data Object JSON tour data from the editor
timeline Array The parsed timeline metadata used for the tour
playing Boolean Returns true if the tour is currently playing
paused Boolean Returns true if the tour is currently paused
onchange Array of functions Get or set the functions that are called when a tour step is changed
onstart Function Gets or sets the function that's called when the tour is started
onstop Function Gets or sets the function that's called when the tour is stopped

Methods

Method Description
hook() Hooks the input event listeners to the control HTML elements (start/stop/pause buttons and interactive timebar)
pause() Pauses the running tour
start() Starts the tour
stop() Stops the tour
unhook() Unhooks the input event listeners to the control HTML elements (start/stop/pause buttons and interactive timebar)

Events

All events are fired on the main Micrio container element (<micr-io>). The reference to the tour object is the argument event.detail.

Event name Description
tours-start Fires when this tour has been started
tours-stop Fires when this tour has been stopped
✉ Can't find what you're looking for? Contact us!