Skip to content

Q42/Micrio.Templates

BranchesTags

Repository files navigation

Micrio Templates

Overview

Welcome to the Micrio Integration Templates repository! This project is designed to provide you with a collection of easy-to-use starter templates for integrating the powerful Micrio viewer into your web projects.

Contents

Jumpstart your Micrio integration! This repository offers a collection of ready-to-use templates designed to get you embedding the powerful Micrio Client into your web projects quickly and easily. Explore different patterns, learn best practices, and leverage support for popular web technologies like plain HTML/JS, Next.js/React, and SvelteKit. Save time, learn by example, and choose the setup that fits your needs.

Whether you're a developer looking for a solid foundation for your React or Svelte project, or someone less technical wanting to embed Micrio content with minimal code using simple HTML/JS, these templates are designed for you. Get your Micrio viewer running in minutes!

What is Micrio?

Micrio is a cutting-edge platform for creating, publishing, and exploring ultra-high-resolution images and immersive virtual tours. It allows you to bring incredible detail and interactivity to your visual content.

Learn more at the Micrio website and check out the core client library at the Q42/Micrio.Client GitHub repository.

Available Examples

This repository currently offers the following integration patterns:

  1. FloatingIntro:

    • Description: A simple example featuring a Micrio viewer with an introductory screen overlaid on top. This screen provides basic information or context and can be easily clicked away to reveal the full Micrio experience underneath.
    • Stacks:

  2. MinimizablePanel:

    • Description: Shows how to replace the standard Micrio menu with a custom, minimizable panel. This compact panel provides quick shortcuts to specific markers or tours within the Micrio image, offering a streamlined navigation experience.
    • Stacks:

  3. CustomStyling:

    • Description: Illustrates how to customize the Micrio viewer's appearance using Micrio's CSS variables. This example shows a basic HTML/JS setup demonstrating changes to various UI elements.
    • Stacks:

  4. CustomSerialTour:

    • Description: Illustrates how to customize the Micrio player's appearance to show a multi-image tour styled like a video with multiple segments shown as chapters. This example shows a basic HTML/JS setup demonstrating how this mechanism works.
    • Stacks:

Coming Soon:

  • Examples using Vue.js.

Prerequisites

For All Users:

  • A Micrio Account: You'll need a Micrio account to host your images and get your Image IDs. If you don't have one, you can sign up at Micrio.

For Non-Technical Users:

  • Text Editor (Optional but Recommended): A simple text editor like Notepad (Windows), TextEdit (Mac), or a more advanced one like VS Code will be helpful for making small changes (like updating the Micrio Image ID).

For Technical Users:

  • Node.js and npm: Required for the Next.js/React and Svelte examples. Download Node.js (which includes npm) from nodejs.org.
  • Git (Optional): Useful for cloning the repository. Alternatively, you can download the project as a ZIP file.
  • Basic Web Technology Familiarity: A basic understanding of HTML, CSS, JavaScript, and (if applicable) React or Svelte will be beneficial.

Finding Your Micrio IDs (Image, Marker, Tour)

To use these templates with your own Micrio content, you'll need the specific IDs for your images, and optionally, for any markers or tours you wish to feature.

  1. Log in to Micrio: Go to your Micrio dashboard at https://dash.micr.io/.
  2. Finding an Image ID:
    • Navigate to your list of images/projects.
    • Open or select an image. The Image ID is typically part of the URL in your browser's address bar when viewing the image directly (e.g., https://i.micr.io/YOUR_IMAGE_ID).
    • Alternatively, from the list view in your Micrio dashboard (https://dash.micr.io/), click the three dots (︙) context menu next on the image's card. The Image ID will be the first item listed; clicking it copies the ID directly to your clipboard.
  3. Finding a Marker or Tour ID (for programmatic use):
    • The example templates (especially Svelte/React) may use specific alphanumeric IDs (looking like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) to refer to markers or tours in their configuration files (e.g., content.ts).
    • Important: These specific alphanumeric IDs are generally not directly visible in the Micrio v3 dashboard editor UI's properties panels.
    • How to get them:
      • Primary Method (Editor URL): The easiest way is often directly from the Micrio Editor. When you select a specific marker or tour step within the editor interface (https://dash.micr.io/), look at your browser's address bar. The URL will contain the ID you need. For example, a marker URL might look like https://dash.micr.io/micrio-shared/micriotemplates/@YOUR_IMAGE_ID/en/content/markers/MARKER_ID_HERE. Copy the long alphanumeric string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) which is the Marker or Tour ID.
      • Secondary Method (Developer Console): For developers needing programmatic access or bulk retrieval, you can inspect the Micrio instance in your browser's developer console. After an image is loaded in a <micr-io> element, you can access its data. Run this one-liner in the console: console.log(document.querySelector('micr-io').$current.$data) This will output the image data, including arrays markers and tours, where each object has an id property containing the required alphanumeric ID. You can identify the specific marker/tour by its i18n.en.title (which is visible in the editor) and then retrieve its id. Consult the Micrio Client JS API Documentation for more details.
      • Note on Deep Links: The Micrio viewer also updates the browser URL with human-readable names (slugs) for the current marker or tour (e.g., https://i.micr.io/IMAGE_ID/en/tour-slug/marker-slug). While these slugs are useful for direct linking, they are not the same as the alphanumeric IDs needed for configuration in these templates.
    • If you are unsure how to obtain the correct ID for a template, please check the specific template's documentation or consider opening an issue in this repository for guidance.

Note: The Micrio dashboard UI may change. For the most up-to-date instructions, please refer to the official Micrio Knowledge Base.

Getting Started / Installation

Follow these steps to get a template running:

1. Get the Templates:

  • Option A: For Non-Technical Users (Recommended - Download ZIP):

    1. Go to the GitHub Repository Page.
    2. Click the green "Code" button.
    3. Select "Download ZIP".
    4. Extract the downloaded ZIP file to a folder on your computer.

  • Option B: For Technical Users (Clone with Git):

    git clone [email protected]:Q42/Micrio.Templates.git
cd Micrio.Templates

2. Choose Your Example:

  • Navigate into the folder of the example and technology stack you want to use. For instance, go to FloatingIntro/html-js, either using your file explorer or terminal.

Quick Start Guide (Simplest Path: HTML/JS Example)

Let's get your first Micrio project running in just 3 steps using the html-js example!

(Ensure you have your Micrio Image ID ready - see section "Finding Your Micrio IDs" above.)

  1. Navigate:

  2. Configure:

    • Open the index.html file in a text editor.
    • Look for a line similar to this (the ID ffoTBWj is an example): 
      <micr-io id="ffoTBWj" lang="en" class="micrio-viewer"></micr-io>
    • Replace ffoTBWj (or the existing ID) with your actual Micrio Image ID within the id attribute. For example: 
      <micr-io id="YOUR_MICRIO_IMAGE_ID" lang="en" class="micrio-viewer"></micr-io>

  3. View:

    • Save the changes to index.html.
    • Open the index.html file in your web browser (usually by double-clicking it).
    • You should now see your Micrio image!

Detailed Usage Instructions

HTML/JS Examples (e.g., FloatingIntro/html-js/ or CustomStyling/html-js/)

Next.js/React Examples (e.g., FloatingIntro/nextjs-react/)

Svelte (SvelteKit) Examples (e.g., FloatingIntro/svelte/)

In-Depth Customization Options

Beyond changing the Micrio content ID, you can customize these templates further:

  • Changing Micrio Content (Recap):

    • Image ID: As detailed above, change in index.html (for HTML/JS) or content.ts (for React/Svelte).
    • Marker and Tour IDs: In React/Svelte examples, check the content.ts files for constants like startMarkerId, tourId, etc., and update them with IDs from your Micrio dashboard if you want to point to different markers/tours within your image.

  • Theming & Styling:

    • CSS: All examples use CSS for styling. Modify the .css files (e.g., style.css, app.css, globals.css, component-specific CSS files) to match your brand or desired look. Use your browser's developer tools (F12) to inspect elements and identify their classes for targeted styling.
    • Micrio CSS Variables: Micrio provides CSS variables for easy customization of common elements like menus and popups. Refer to the "Styling a Micrio embed using CSS" guide for available variables and examples.
    • Step-by-Step Tutorial: For a detailed tutorial on styling the Micrio UI, including CSS variables and targeting Micrio-specific elements, see the Micrio CSS Styling Tutorial.
    • Tailwind CSS (Next.js/Svelte): The Next.js and Svelte examples integrate Tailwind CSS. Component styles (e.g., for the main page structure, text content, or custom panels) are often applied using Tailwind utility classes directly in the .tsx or .svelte files, alongside traditional CSS files.
    • Micrio Runtime Attributes: Micrio offers a range of runtime attributes that control the viewer's behavior and appearance (e.g., data-show-info="false"). Configure these directly as HTML attributes on the <micr-io> element.

  • Modifying Text and Layout:

    • Text: Directly edit the text content within HTML files (.html), TSX files (.tsx), or Svelte files (.svelte).
    • Layout: Adjust HTML structure or CSS properties (like Flexbox, Grid, positioning, margins, padding) to change the layout.

Deployment Instructions

Once you've customized your template, here's how to deploy it:

General Advice:

  • HTML/JS examples are static sites and can be hosted on any static web host.
  • Next.js/React and SvelteKit examples typically require a build process and can be deployed to platforms that support Node.js applications or modern JavaScript frameworks.

HTML/JS Examples:

  • Any Static Host: (e.g., Netlify, Vercel, GitHub Pages, AWS S3, traditional web hosting). Simply upload the entire contents of your chosen html-js example folder (e.g., FloatingIntro/html-js/).
  • GitHub Pages (Step-by-step):
    1. Create a new GitHub repository or use an existing one.
    2. Push the contents of your chosen html-js example folder (e.g., FloatingIntro/html-js/) to the repository.
    3. Go to your repository's "Settings" tab, then click on "Pages" in the left sidebar.
    4. Under "Build and deployment", select "Deploy from a branch" as the Source.
    5. Choose the branch (e.g., main) and the folder (usually / (root) if you pushed the example's contents directly, or /docs if you placed them there) and click "Save".
    6. Your site will be available at https://your-username.github.io/your-repository-name/.
  • Netlify / Vercel (Drag & Drop):
    1. Log in to your Netlify or Vercel account.
    2. Simply drag the html-js example folder (e.g., FloatingIntro/html-js/) from your computer onto the Netlify/Vercel dashboard's deployment area (often labeled "Sites" or "Projects").

Next.js/React Examples:

  • Vercel (Recommended for Next.js):
    1. Push your project (the specific nextjs-react example folder, e.g., FloatingIntro/nextjs-react/) to a Git repository (GitHub, GitLab, Bitbucket).
    2. Sign up or log in to Vercel.
    3. Connect your Git provider to Vercel.
    4. Import the project from Vercel. Vercel typically auto-detects Next.js settings.
    5. Configure environment variables if needed.
    6. Click "Deploy".
  • Netlify:
    1. Push your project to a Git provider.
    2. Sign up or log in to Netlify.
    3. Connect your Git provider and import the project.
    4. Netlify usually detects Next.js.
      • Build command: npm run build (or next build)
      • Publish directory: .next (or out if you're using static export next export)
    5. Deploy.
  • Docker:
  • Self-hosting (Node.js server):
    1. Run npm run build in your project directory.
    2. Then run npm run start to start the production server.
    3. Ensure your server environment is set up for Node.js applications and can serve the application (e.g., using PM2 or similar process managers).

Svelte (SvelteKit) Examples:

  • Vercel / Netlify (Adapters Recommended):

    1. Ensure your SvelteKit project uses an appropriate adapter in its svelte.config.js. @sveltejs/adapter-auto (default) works well for Vercel, Netlify, and Cloudflare Pages. For specific platforms, you can use adapters like @sveltejs/adapter-vercel or @sveltejs/adapter-netlify.

      // Example: svelte.config.js
import adapter from '@sveltejs/adapter-auto'; // Or adapter-vercel, adapter-netlify

/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: { adapter: adapter() },
};
export default config;

    2. Install the chosen adapter if you are not using @sveltejs/adapter-auto: npm install -D @sveltejs/adapter-vercel (example).

    3. Push your project (the specific svelte example folder) to a Git provider.

    4. Connect and import on Vercel or Netlify. They usually auto-detect SvelteKit settings based on the adapter.

  • Docker:

    • You'll typically use @sveltejs/adapter-node to build a Node.js server.
    • Create a Dockerfile to copy your built application and run the Node.js server. Refer to SvelteKit documentation on adapter-node and Dockerizing Node applications.

  • Self-hosting (Node.js server with adapter-node):

    1. Ensure @sveltejs/adapter-node is configured in your svelte.config.js (e.g., FloatingIntro/svelte/svelte.config.js).
    2. Run npm run build. This will create a build directory (or as configured by the adapter).
    3. Deploy the contents of the build directory to your server and run the Node.js server (e.g., node build/index.js). Use a process manager like PM2 for production.

Troubleshooting

  • "My Micrio image isn't loading!"
    • Check Image ID: Double-check that the Micrio Image ID you've entered is correct and that the image is published and publicly accessible in your Micrio dashboard. Try visiting https://i.micr.io/YOUR_IMAGE_ID (replacing YOUR_IMAGE_ID with your actual ID) directly in your browser – you should see your image load.
    • Internet Connection: Verify your internet connection.
    • Browser Console: Open your browser's developer console (usually by pressing F12) and look for any error messages in the "Console" tab. These can provide clues about what's going wrong.
  • Build Errors (for Next.js/Svelte projects):
    • Dependencies: Ensure npm install completed without errors. If you see errors, try deleting node_modules and package-lock.json and running the install command again.
    • Node.js Version: Check that your Node.js version is compatible with the project. The .nvmrc file specifies the recommended Node.js version.
  • Refer to Official Documentation:

Contributing

We welcome contributions to improve these templates!

  • Reporting Issues: If you find a bug or have a suggestion, please open an issue on the GitHub Issues page.
  • Pull Requests: If you'd like to contribute code, please fork the repository, make your changes on a new branch, and submit a pull request.
  • Code Style: This project uses Prettier for code formatting. Please ensure your code is formatted before submitting a pull request. You can usually format by running npm run format if a script is configured in package.json, or by using a Prettier extension in your code editor. Check the .prettierrc file for configuration.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements & Further Links

We hope these templates help you create amazing Micrio integrations!

About

Example Micrio implementations

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages