Embed ARender in an application

To integrate ARender into your application, simply add an iframe tag pointing to the ARender server in the HTML code of your application.

1. Embedding the iframe

The ARender iframe should be inserted into your application at the most relevant location, depending on your use of ARender.

Here is a minimal example compatible with any type of framework:

    <iframe
        id="arender-iframe"
        src="Insert the ARender URL here"
        title="Integrated ARender iframe"
        allow="microphone"
    />

The id uniquely identifies the iframe and allows its instance to be retrieved in JavaScript: const iframe = document.getElementById('arender-iframe');
The src parameter must contain the URL of the installed version of ARender.
The title provides a textual description of the iframe’s content for accessibility purposes.
The allow=‘microphone’ parameter is essential to enable the use of voice annotations in ARender.

At this stage of the ARender integration, an iframe pointing to ARender appears in the DOM of the host application. However, it might not yet be visible depending on where it is integrated into the host application. You will need to define its position and dimensions, as shown in the example below.

2. Framework Information

ARender integration tests have been conducted with the following versions:

React : version 18.3.1
Angular : version 19.0.0
VueJs : version 3.5.13
Svelte : version 5.19.0

- Create a component called ARender.tsx or ARender.jsx and insert the iframe as shown in the code below. The component can then be instantiated wherever you need it using the tag: ‹ARender /›

- In React, you can use a reference to interact with the iframe using the ref parameter, instead of using an ID query.

- You can also style the iframe by adding the classname parameter.

- Finally, the URL associated with the iframe through the src parameter can be made dynamic, allowing it to be modified dynamically.

  import {useRef, useState} from 'react';

  function ARender() {
      const iframeRef = useRef(null);
      const [arenderUrl, setARenderUrl] = useState('')
      // A dynamic url allow you to update easily the parameters
      const [arenderIsDisplayed, setArenderIsDisplayed] = useState(true)

  return (
      <>
        {
          <iframe
            ref={iframeRef}
            className={`iframe ${arenderIsDisplayed ? '' : 'hidden'}`}
            title='integrated-arender'
            id='arender-iframe'
            src={arenderUrl}
            allow='microphone'
          />
        }
      </>
    );
  }

  export default ARender;

- Create an angular component (you can do it using this CLI command : ng generate component Arender) - Fill typescript and html files as presented below :

import { Component, ElementRef, ViewChild } from '@angular/core';

@Component({
  selector: 'app-arender',
  templateUrl: './arender.component.html',
  styleUrls: ['./arender.component.css']
})
export class ARenderComponent {
  @ViewChild('iframeRef', { static: false }) iframeRef!: ElementRef<HTMLIFrameElement>; // Reference to the iframe
  arenderIsDisplayed: boolean = true; // Controls the iframe visibility
}

<iframe
  #iframeRef
  class="iframe" 
  [class.hidden]="!arenderIsDisplayed" 
  title="integrated-arender"
  id="arender-iframe"
  src="" // Add ARender url here
  allow="microphone"
></iframe>

- Add ARenderComponent to the main module (file app.module.ts) if necessary by adding the arender component to the declarations list.

- Insert the component into the application by placing this tag in the HTML code of the appropriate file: <app-arender></app-arender>

- The @ViewChild attribute will allow easy interaction with the iframe without needing to use getElementById.

Installation

- Create a new file named ARenderItem.vue and insert the following code:

<script setup>
  import { ref } from 'vue'

  const { arenderIsDisplayed = true } = defineProps()
  const iframeRef = ref(null)
</script>

<template>
  <iframe
    ref="iframeRef"
    :class="{ hidden: !arenderIsDisplayed }"
    class="iframe"
    title="integrated-arender"
    id="arender-iframe"
    :src="arenderUrl"
    allow="microphone"
  ></iframe>
</template>


<style scoped>
  iframe {
    ...
  }
</style>

Usage

You can use the ARender component in your Vue application as follows:

<script setup>
	import Arender from './components/ArenderItem.vue'
  import { ref } from 'vue'
</script>

<template>
  <Arender ref="arenderRef" />
</template>

Features

- Dynamic iframe visibility: The arenderIsDisplayed prop controls whether the iframe is shown or hidden.
- Direct iframe reference: The iframeRef prop binds the iframe element, allowing direct interaction.
- Custom styling: The iframe can be styled using CSS classes.
- Dynamic URL: You can modify the iframe source dynamically by updating the src attribute.

Installation

- Create a new file named ARender.svelte and insert the following code:

<script>
  let { arenderIsDisplayed = $bindable(true), iframeRef = $bindable() } = $props();
</script>

<iframe
  bind:this={iframeRef}
  class="iframe"
  class:hidden={!arenderIsDisplayed}
  title="integrated-arender"
  id="arender-iframe"
  src="" <!-- Add Arender url here -->
  allow="microphone"
></iframe>

<style>
  ...
</style>

Usage

You can use the ARender component in your Svelte application as follows:

<script>
	import Arender from '$components/Arender.svelte'
</script>

<Arender bind:iframeRef />

Features

- Dynamic iframe visibility: The arenderIsDisplayed prop controls whether the iframe is shown or hidden.
- Direct iframe reference: The iframeRef prop binds the iframe element, allowing direct interaction.
- Custom styling: The iframe can be styled using CSS classes.
- Dynamic URL: You can modify the iframe source dynamically by updating the src attribute.

To integrate with pure CSS, without using a specific framework, create the following script file:

    document.addEventListener('DOMContentLoaded', function () {
    // Iframe creation
    const iframe = document.createElement('iframe');
    iframe.title = 'integrated-arender';
    iframe.id = 'arender-iframe';
    iframe.allow = 'microphone';
  
    // Variables for the URL and the iframe states
    let arenderUrl = '';
    let arenderIsDisplayed = true;
  
    // Add attributes to iframe
    function updateIframe() {
      iframe.src = arenderUrl;
      iframe.className = arenderIsDisplayed ? 'iframe' : 'hidden';
    }
  
    // Add the iframe to the HTML body
    document.body.appendChild(iframe);
  
    // Function to update the HTML after an url change in the iframe
    function setARenderUrl(newUrl) {
      arenderUrl = newUrl;
      updateIframe();
    }
  
    // Display / hide iframe
    function toggleArenderVisibility() {
      arenderIsDisplayed = !arenderIsDisplayed;
      updateIframe();
    }
  
    // Initial update to manage the display of the iframe and the url
    updateIframe();
  
    // Add ARender URL
    setARenderUrl(''); // <= Add ARender URL here
  
    // Listen to the button click
    const toggleButton = document.getElementById('toggleButton');
    toggleButton.addEventListener('click', function() {
      toggleArenderVisibility();
    });
  });

This script waits for the HTML document's DOM to load, creates an iframe element with the necessary parameters, and adds the element to the DOM. Then add the script to the HTML file of your choice :


<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <button id="toggleButton">Afficher / Masquer l'iframe</button>

    <script src="./index.js"></script>
</body>
</html>

In this example, a button has been added to dynamically show/hide the iframe. (It will only work once the CSS is added in the next section.)

In this example, a ‘hidden’ class has been added to the iframe when we want to hide it (for example, by setting its width to 0px).

It is also possible to completely remove the iframe when it’s not displayed, but this will result in a reload of ARender each time it’s shown again.

You can replicate this method of associating a button with code to test the ARender features described in the following pages.

3. Style the iframe with CSS

The CSS classes associated with the iframe will allow us to style it. Often, we want to display ARender on a fixed portion of the screen, occupying, for example, 60% of the screen width, and not disappearing during scrolling. Here is an example of commented CSS:

iframe {
  position: fixed; /* ARender will remain displayed even if you scroll in your application */
  top: 0;
  right: 0;
  width: 60%; /* 60% of screen width */
  transition: width 0.2s ease-in-out; /* Facultative transition when displaying d'ARender */
  height: 100%; /* Takes all screen height */
  border: none; /* Remove iframe borders */
  border-left: 1px solid var(--ar-color-gray-700); /* Add a customized border on the left side of the iframe to separate it from the rest of the application */
  
  &.hidden {
    width: 0px; /* Visualy hides ARender. ARender stays open to avoid reloading each time. */
    transition: width 0.2s ease-in-out; /* Facultative transition when hiding d'ARender */
  }
}