JS API Client 2.x
WARNING
This page is about the Micrio client version 2, which is no longer supported. Use the links below to navigate to alternative versions.
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:
js
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)
js
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
| 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 |
onclose | Function | Gets or sets the function to call when the popup is closed |
onopen | Function | Gets or sets the function to call when the popup is opened |
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 |