Using the Micrio client API Client 5.x

This page is about the Micrio client version 5. Use the links below to navigate to alternative versions.

• Version 3.x
• Version 4.x

This is a step by step tutorial. For more in-depth documentation on the JS API, visit the relevant documentation.

TIP

The full example for this tutorial can be found HERE.

Before starting this tutorial, we're assuming you've already completed the previous tutorial: How to use your own custom CSS styling.

1. Access the image in JavaScript

To access a Micrio image using JavaScript, put this in a <script> tag below where the <micr-io> element is in your HTML:

// The Micrio HTML element
const _micrioElement = document.getElementById('your-micrio-id');

This _micrioElement object will be the main reference HTML Element throughout this tutorial.

1.2. TypeScript bindings

Micrio 5 is fully TypeScript-compatible, and comes with its own declaration file!

If you are using Micrio in a TypeScript project:

1. Download the micrio-5.0.min.d.ts declarations file, and include it in your project
2. Now you can simply cast the Micrio HTML element as a HTMLMicrioElement:

import type { HTMLMicrioElement } from 'Micrio';

// This gives you full type checking and any editor autocompletion
const micrio = document.querySelector('micr-io') as HTMLMicrioElement;

// VS Code will fully know what you're doing here
micrio.camera.flyToView([.2,.2,.3,.3]).then(() => console.log('done!'));

3. Now your TypeScript-enabled IDE, such as VS Code, will offer full autocompletion, error checking, and deep referencing your code!

2. Custom behavior on image events

This section covers some examples for when you're working with your own HTML controls to control the image from inside your own webpage.

You can use the Events API to listen to many different image and user events.

A custom action when the image is loaded

If you have a custom UI element that you want to show or hide based on whether the user is zoomed in or not, you can use the load event:

_micrioElement.addEventListener('load', (evt) => {
    console.info('The image is done loading!');

    // You can do whatever you want here
});

TypeScript

The event.detail of this event is a MicrioImage TypeScript object of the loaded image itself.

Find out when the user is zoomed in

If you have site behaviour based on whether the user is zoomed in or not, you can use the zoom event.

_micrioElement.addEventListener('zoom', (evt) => {
  // The current image and image viewport are in evt.detail
  console.info('Current camera viewport', evt.detail.view);

  // Let's check if the user is fully zoomed out
  // The Micrio HTML element has a virtual .camera
  if(evt.detail.image.camera.isZoomedOut()) {
    console.info('The user is totally zoomed out!');
  }
  else {
    // If you have any scale-based custom actions, run them here:
    console.info('The user has zoomed in to scale', evt.detail.image.camera.getScale());
  }
});

TypeScript

The event.detail of this event is a an object with .image as MicrioImage, and .view as Viewport

3. Custom marker behavior

Markers are very powerful objects within an image. They can trigger a popup, jump to another image, or have a custom action defined within your website. This section gives some examples for marker interaction.

A custom action when a marker is opened

When you want to have a custom action executed once a user has opened a marker and you want to wait for the camera to have flown to the marker's viewport, do this:

_micrioElement.addEventListener('marker-opened', (evt) => {
    // The current camera coordinates and scale are evt.detail
    let marker = evt.detail;

    console.info('Opened marker and the camera has flown there :', marker);

    // Do something cool!
});

TypeScript

The event.detail of this event is a a Marker

No popup on marker open

To prevent a marker popup from being opened, you can use the marker-open event, which is fired when the user has clicked a marker, but before any animation or popup rendering is done.

_micrioElement.addEventListener('marker-open', (evt) => {
    // The current camera coordinates and scale are evt.detail
    let marker = evt.detail;

    // Prevent anything from happening by immediately closing the marker
    _micrioElement.$current.state.marker.set(null);

    console.info('Marker is clicked and prevented popup to open :', marker);

    // Do something cool!
});

Conclusion

In this tutorial, you've gone through some examples to handle custom Micrio events. From here on, you can implement these with your own functions and wishes.

The full working HTML of this tutorial can be found HERE.

If you have any more questions, please drop us a line and we'll try to help you further!