Micrio Knowledge Base

Appearance

Migrating from Micrio 4.x to 5.x Client 5.x ​

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

This guide only applies to upgrading existing custom JS and CSS implementations in your own website using Micrio 4.x and older to version 5.x.

If you don't know what that is, or if you are simply using Micrio out of the box without any customizations, this article is not for you.

If you do have a Micrio implementation inside your own website which makes use of the Micrio API, and/or has custom CSS, please read on.

Should I upgrade? ​

Each Micrio JavaScript major version has a stable working release:

This means that Micrio projects using those versions will always keep working as they are. Since Micrio only uses standard browser functions, older versions will not suddenly stop working at some point in time.

If you have a current running Micrio implementation in your own site, and it works well, there is no need to upgrade to Micrio 5.

We also still offer limited support on the previous major release, in this case Micrio 4.1. If you find any bugs, please contact us.

When should I upgrade? ​

There are a few reasons where upgrading makes sense:

  • You want to use newly added features, like 360° object viewing support or built-in swipeable albums
  • You are using Micrio on many places inside your website (ie. a collection viewer), and you want to be sure you are running the latest and greatest Micrio version for performance or code cleanliness reasons

If either of these questions can be answered with "Yes", this article is for you.

What's changed? ​

Micrio 5.0 comes with quite some changes under the hood (see also the technical CHANGELOG) compared to Micrio 4.x, resulting in changed HTML/CSS, and a new JavaScript API.

Micrio 5.0 also has a slightly different HTML DOM model compared to Micrio 4.x, including some changed UI visuals, and dark and light mode support. For more info and the latest CSS variables you can use, see the UI Section.

How to update? ​

You can update your existing Micrio integration in two steps:

  • Replace your current Micrio JS reference (https://b.micr.io/micrio-{version}.min.js) with Micrio 5: https://r2.micr.io/micrio-5.0.min.js. Note the change from b.micr.io to r2.micr.io: you can use both, however r2.micr.io has a better global distribution.

  • If your project uses TypeScript, and an existing TypeScript declarations file for Micrio, replace it with https://r2.micr.io/micrio-5.0.min.d.ts.

1. HTML & CSS ​

Overall, Micrio 5 has a new look compared to Micrio 4.1. It's been made a little more modern, with rounded borders, more spacing, a more readable font, and some sleek added transitions and animations.

It is however very easy to overwrite the default Micrio styling using CSS variables, instead of using HTML selectors. See this page for all available settings.

1.1. Changed CSS classes and DOM structure ​

All HTML element changes are below in this table. Rule of thumb is, that all CSS class names are now prefixed with micrio-, for better scoping. If an element is not listed here, it hasn't changed.

NOTE: & refers to the main Micrio element

HTML element4.1 CSS selector5.0 CSS selector
All Micrio icon buttonsbutton.micrio-actionbutton.micrio-button
Image marker& > .micrio-markers > .marker& > .micrio-markers > .micrio-marker
Marker popup& > .marker-popup& > .micrio-marker-popup
Minimap& > canvas.minimap& > canvas.micrio-minimap
Image info panel& > details& > details.micrio-details
Control buttons& > aside.controls& > aside.micrio-controls
Video tour controls& > div.tour& > div.micrio-tour.videotour
Marker tour controls& > div.tour& > div.micrio-tour
Full-window popover& > div.popover > sectiondialog.micrio-popover > article.micrio-article

As you can see, it's not all that different. If you are only using custom CSS for your Micrio implementations, upgrading can be done quickly by updating your CSS selectors.

Do mind to double check your changes: it's possible some underlying HTML of the main selected element has also changed, for instance the marker popup HTML.

1.2. <micr-io> element option attributes now mostly prefixed with data- ​

To adhere to the open web standards, we have updated the list of option attributes of the <micr-io> element to use W3C-compatible Dataset properties.

To see the list of supported option attributes, see this page.

1.3. Popovers use <dialog> ​

A relatively recent feature in web browsers, which solves many cross-platform UI issues, is the <dialog> element (see the MDN documentation).

With this, you can create an accessibility-friendly user dialog, which acts as a full-window popup overlay by itself.

This is great for full-window marker popup elements (ie. a full-window video), or a custom page you have created in the editor.

1.4. Marker popups are always statically placed ​

Where the default behavior of Marker Popups always was that they were connected to the marker itself, ie. moved around by panning through the image, we came to the conclusion that this feature is used in virtually no Micrio projects. Virtually all released Micrio projects have a statically placed marker popup.

We have removed the dynamically placed popup, and all marker popups are statically placed. The location of which can of course be overwritten using your own CSS.

If you really want to keep the old method, consider using the JS API to place the popups dynamically yourself.

1.5. WCAG accessibility compatibility ​

Micrio 5 has implemented the Web Content Accessibility Guidelines (WCAG) 2.2, to ensure that you can navigate through Micrio by keyboard, and includes full screen reader support.

This means that the HTML element order and tabindex properties have been adjusted accordingly.

1.6. CSS z-index has been mostly removed ​

Following the previous point, since the Micrio HTML structure has simplified and became more semantic, the use for z-indexes has been largely been removed. While there are still a few minor elements which use z-index for purely visual use, they range from z-index: 1 to z-index: 2.

So if you want to force any hard overlays, if you use a z-index larger than 2, you are safe.

2. JavaScript (& TypeScript) ​

Micrio 5.0 has some internal data and TypeScript/JavaScript updates. Below are the key points highlighted:

2.1. Unified language data ​

INFO

The below change comes together with the release of the newest Micrio dashboard, version 3. More info

Prior to Micrio 5, all language-specific published data was delivered as separate data.[lang].json files. This came with some inherent problems, such as possible differently placed markers per published language, or the impossibility to have realtime translated content.

Micrio 5 published content is a single pub.json file, which includes all translations, locally to the specific content item such as a marker. Which means that visitors can now switch to different languages realtime, no longer being dependent on a separate download.

Data-wise, all content items (markers, tours, articles, etc) no longer have direct .title attributes, but a multi-lingual .i18n sub-object, with all translations under the respective language code. For example, a marker now looks like this:

json
{
	"id": "7176b9d0-3b94-3bb5-3907-a635ce17aebb",
	"y": 0.340582,
	"x": 0.5998,
	"i18n": {
		"en": {
			"title": "New marker",
			"body": "<p>Marker body</p>",
			"slug": "new-marker"
		}
	}
}

WARNING

This is a structural data content change, and means that older versions of the Micrio client cannot view content published from the latest dashboard, version 3. However, Micrio 5 is fully backwards compatible, meaning it is still able to correctly display older published Micrio projects.

In addition, the TypeScript model namespace Micrio.Models.ImageCultureData has been renamed to Micrio.Models.ImageData.

2.2. Each MicrioImage has its own virtual Camera ​

In prior Micrio viewer versions, there was a single dynamic Camera, which handled all viewing logic for any image that was currently active. This complicated matters when viewing multiple images at once, or doing crossfading while also animating the individual images.

In Micrio 5, each MicrioImage has its own .camera property, which allows you to animate and control the individual image viewports.

To access the active image camera, what was:

js
MicrioHTMLElement.camera

is now

js
MicrioHTMLElement.$current.camera

However, for backwards compatibility, MicrioHTMLElement.camera is still available as a shorthand to the active current image's camera object.

2.3. Image settings have moved ​

In order to allow for more reactive Image Settings, which is downloaded as a sub-object of the MicrioInfo object, there is now a direct Svelte WritableMicrioImage.settings property, which is how you can update the settings.

To read the current settings value directly, you can use the MicrioImage.$settings property.

For instance, to hide the UI on the current active image:

ts
HTMLMicrioElement.$current.settings.update(s:Micrio.Models.ImageInfo.Settings => {
	s.noUI = true;
	return s;
});

2.4. Audio ​

2.4.1. Positional audio ​

With an update to the new V3 editor, we have combined independent positional audio with markers. Both already had a large overlap, and having them merged adds to the data model simplicity.

In the dashboard, you can now add a positional audio fragment to any already created marker, so that when the user zooms or pans past the marker in view, they will hear the audio at that precise location.

Since it is also possible to create hidden markers, positional audio can still be made stand-alone, by hiding the marker it's connected to. Functionally, nothing has changed.

Data-wise, where there used to be a MicrioCultureData.audio.locations[] JSON property with independent positional audio entries, this is now the (optional) property Micrio.Models.ImageData.Marker.positionalAudio.

2.4.2. Audio / music playlist ​

The data model for the looping, static audio playlist linked to the image, has been moved from MicrioCultureData.audio.playlist[] to MicrioData.music.

2.5. In-image embeds ​

With the release of the new dashboard, in-image embeds, which act as if they are part of the original image, have been functionally expanded. Now, you can add other Micrio images, static images, videos (on request), and even IFrames to your Micrio images.

Before Micrio 5, this was possible in a more limited way, by creating in-image embeds under individual markers, which would show the embed only when the marker was opened.

To reduce complexity and add functionality, we have introduced a stand-alone MicrioData.embeds[], which is an array of Embed entities created in the Micrio editor.

2.6. Marker .class has become .tags ​

To add custom class names to individual markers, which show up in the HTML of both the marker element, as the connected popup, allowing you to add custom CSS for them, this function was also often used to give marker tags, to add custom JavaScript behavior to them based on their tags.

Where Marker.class was a single string with each name space-separated, the new Micrio editor now has an easy to use tagging tool, which also allows you to reuse earlier entered tags of other markers, reducing the chance of typos.

This is published in the data as the Marker.tags[] property, which is an array of strings.

Each tag will still also be printed as a classname of the marker's respective HTML elements.

2.7. Type location changes (TypeScript) ​

Two more significant TypeScript type changes are:

There have been minor other changes, however unsignificant. If you are upgrading an existing project to Micrio 5, just use the latest declarations include, and your IDE will most likely point you to any other changes.

3. Others ​

3.1. Automatic backwards compatibility ​

Micrio 3 and 4, both running on a modern browser engine (WebAssembly), had an automatic fallback to Micrio 2.9, for browsers that did not support WebAssembly. Generally, these were browsers older than 2017 (7 years ago, at the time of writing).

Micrio 5 no longer has the automatic fallback, as these browsers are generally not used anymore. So if your visitors still are using these very old browsers, either:

  • Make the Micrio version distinction yourself, serving Micrio 2.9 based on their userAgent string,
  • Do not upgrade to Micrio 5, or
  • Create a notification in your site for these users that they need to update their browser.