Embedding Canvas Envision Creator and evCreate API Calls Into HTML

You can embed the front end of the Canvas Envision Creator web app and your JS code that calls the app's functionality with the evCreate API functions into custom web pages.

Prerequisites for embedding Canvas Envision Creator into HTML

The Canvas Envision Creator is a web application with front and back ends. Each end has its own codebase. The front end embedded in a custom HTML page requires its codebase to be on the same drive as the HTML page. Without the front-end codebase, the embedded web app and custom scripts will not work.

You can download the front-end codebase to your local environment as discussed in the following section: Downloading and Running Front-end Codebase Locally.

Additionally, a web server app should host the custom HTML page.

Embedding Canvas Envision Creator into HTML

To embed the front end of the Canvas Envision Creator web application into a custom web page, you should do the following:

Add the elements necessary for the front end to your custom HTML file according to the HTML template for Canvas Envision Creator.
If necessary, set the custom attributes of the ev-creator tag for the deployed app instance.
If necessary, configure the size, position, and other standard HTML and CSS attributes for the ev-creator element on the web page.
If there is a connection or download latency, use the waitForEvCreateApiReady() asynchronous function to wait for the evCreate API to be ready for calls.

HTML template for Canvas Envision Creator

To integrate the front end of the Canvas Envision Creator web app into a web page, you should add the HTML elements with the app instance data to the HTML file of that page according to the following template:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Your Page Title</title>
            <base href='/'>
            <meta name='viewport' 
                  content='width=device-width, initial-scale=1'>
            <link
                rel='icon'
                type='image/x-icon'
                href='favicon.ico'
            >
            <link rel='stylesheet' href='styles.css'>
            <script src='assets/spacemouse/3dconnexion.min.js' 
                    type='text/javascript'>
            </script>
        </head>
        <body>
            <div>
               <ev-creator env_web_viewer_url='https://app.instance.url/' 
                           env_api='https://api.instance.url/' 
                           env_ws='wss://app.instance.url/'
                           workspace='workspace-name'
               ></ev-creator>
            </div>
            <script src='envision/polyfills.js' type='module'></script>
            <script src='envision/main.js' type='module'></script>
            <script>
                // Optional helper function that ensures 
                // the evCreate API is ready to be called.
                // Usage:
                //   await waitForEvCreateApiReady();
                //   ...Code that uses the evCreate API...
                async function waitForEvCreateApiReady() {
                    // Wait for the evCreate API to be ready.
                    const until = function (predicateFn, intervalMsec) {
                        const poll = resolve => {
                            if (predicateFn())
                                resolve();
                            else
                                setTimeout(() => poll(resolve), intervalMsec);
                        }
    
                        return new Promise(poll);
                    }
                    // Wait for the window.evCreate property to be set.
                    await until(() => window.evCreate !== undefined, 500);
                    // Wait for the 'ready' API event.
                    await window.evCreate.config.WhenApiReady();
                }
            </script>
        </body>
    </html>

HTML elements for Canvas Envision Creator

The embedded front end of the Canvas Envision Creator web app requires some elements nested in the <head> and <body> sections of an HTML document. Along with the required elements, you can use your custom elements constructed with the standard HTML tags as you need.

Required elements in `<head>`

The <head> section should include the following child elements:

<base> with a single slash to construct correct relative paths to 3D parts:

<script> with a path to the 3dconnexion.min.js file in the front end's assets library necessary to support manipulating 3D models and parts with a SpaceMouse® 3D mouse by 3Dconnexion:

Required elements in `<body>`

The <body> section should include the following child elements:

<ev-creator> that represents the embedded front end of the Canvas Envision Creator web app. The front-end codebase resolves the <ev-creator> element and runs the application on the web page. Without the front-end codebase, <ev-creator> will raise an error because it is not a standard HTML tag. The <ev-creator> tag:
- Provides custom attributes for configuring the embedded front-end app.
- Supports standard HTML and CSS attributes and features for managing the layout of the embedded front-end app on the page.

<ev-creator workspace='workspace-name'></ev-creator>

<script> with a path to the polyfills.js file in the front-end codebase library necessary to support old browser versions.

<script> with a path to the main.js file in the front-end codebase library, which is the entry point for executing the app's front-end code.

Custom `<ev-creator>` tag attributes

The <ev-creator> HTML tag provides custom attributes to configure the embedded front end of the Canvas Envision Creator web app. All such custom attributes are optional. The tag can have no, one, or more than one of its custom attributes. If a custom attribute is not given, the front end will automatically use its configuration provided in the codebase.

The custom attributes of the <ev-creator> tag are the following:

workspace

A number or string identifying a workspace in the Canvas Envision Portal cloud solution that stores evdoc files. It can be either:

A static ID generated during the Envision account setup, e.g., workspace='165'.
A slug to sign into the workspace, e.g., workspace='abc_company'.

It is recommended to use slugs instead of IDs because slugs are more user-friendly. You can easily find and read slugs in the system.

If the workspace attribute is not given, the system will ask a user to enter the name of a workspace when the user signs into the embedded Canvas Envision Creator web app. If it is given, this step is omitted, and the user is asked to sign into the given workspace.

The Sign in to your workspace pop-up dialog box

center

A number or string identifying a work center in a given workspace in the Canvas Envision Portal cloud solution. It is a static ID generated during the work center creation, e.g., center='165', center='work', etc.

id

A path to an evdoc file relative to a given work center in the Canvas Envision Portal cloud solution, e.g., id='/MyFolder/MyDoc.evdoc'.

wasm_path

A path to a location from where the Canvas Envision Creator assets should be loaded. It can be an absolute URL to the assets folder.

env_web_viewer_url

A URL to a Canvas Envision Creator server. By default, it is set to the Canvas Envision SaaS server. You should provide a custom URL for a self-hosted Canvas Envision Creator instance, e.g., env_web_viewer_url='https://app.canvasenvision.com'

env_api

A URL to the API endpoint of a Canvas Envision Creator server. By default, it is set to the Canvas Envision SaaS server's API endpoint. You should provide a custom URL for a self-hosted Canvas Envision Creator instance, e.g., env_api='https://api.canvasenvision.com'

env_ws

A URL to the WebSockets endpoint of a Canvas Envision Creator server. By default, it is set to the Canvas Envision SaaS server's WebSockets endpoint. You should provide a custom URL for a self-hosted Canvas Envision Creator instance, e.g., env_ws='wss://api.canvasenvision.com'

Managing the `<ev-creator>` element on the web page

There are two ways to manage the layout of the embedded front end of the Canvas Envision Creator web app:

With the help of a parent container.
Directly in the <ev-creator> tag.

As the <ev-creator> tag is custom, it is highly recommended to put it into a parent container element, usually <div>, and set the standard HTML and CSS attributes in the container element tag for applying standard HTML and CSS features to the embedded front-end app. It is the most flexible way to control the front-end app layout on the page. For example, to make the embedded front-end app occupy 50% of the screen, the <ev-creator> element should be inside a <div> container, whose style attribute should be set to 'height:50vh; width:50vw'.

<div id='myDiv' style='height:50vh; width:50vw'>
    <ev-creator></ev-creator>
</div>

The second way is to set the standard HTML and CSS attributes right in the <ev-creator> tag without placing it into a standard container element. This approach is not recommended and should be avoided because it directly modifies the styles of the embedded front-end app.

<ev-creator
        style='height:50vh; width:50vw'
></ev-creator>

`waitForEvCreateApiReady()` function

The waitForEvCreateApiReady() asynchronous function ensures that the custom code calls the evCreate API when the API is available.

async function waitForEvCreateApiReady() {
// Wait for the evCreate API to be ready.
  const until = function (predicateFn, intervalMsec) {
    const poll = resolve => {
      if (predicateFn())
          resolve();
      else
          setTimeout(() => poll(resolve), intervalMsec);
    }
  return new Promise(poll);
  }
  // Wait for the window.evCreate property to be set.
  await until(() => window.evCreate !== undefined, 500);
  // Wait for the 'ready' API event.
  await window.evCreate.config.WhenApiReady();
}

To use the waitForEvCreateApiReady() function, call it before calling the evCreate API functions.

const insertText = async function () {
	await waitForEvCreateApiReady();
	await window.evCreate.object.text.Create('Hello world!', 
	        { left: 400, right: 800, top: 200, bottom: 700 })
}

const insertBox = async function () {
	await waitForEvCreateApiReady();
	await window.evCreate.object.rectangle.Create({ left: 100, 
	        right: 200, top: 400, bottom: 600 })
}

The waitForEvCreateApiReady() function is optional: you may choose not to use it when you are confident that the API is ready before the calls. For example, you may call it once on the front-end application startup or reloading and then skip it before calling the API functions.

</html>
  ...
  <body>
    ...
    <div>
      <ev-creator></ev-creator>
    </div>
    <script src='envision/polyfills.js' type='module'></script>
    <script src='envision/main.js' type='module'></script>
    <script>
        async function waitForEvCreateApiReady() {
            ...
        }
    
        async function run() {
            await waitForEvCreateApiReady();
        }
    
        run();
    </script>
    <script>
      // Custom Script calling the evCreate API
    </script>
  </body>
</html>

You can declare and call the waitForEvCreateApiReady() function as a JS script placed in the HTML document or as a function in .js files.

Including scripts with evCreate API calls

You can embed custom JS code that calls the evCreate API into the HTML document with the standard <script> HTML element following the conventional practices and rules for JS and this element. The code can be nested in this element or attached to it in external .js files or modules. The custom <script> element should be placed in the <body> section after the <ev-creator> element and required <script> elements with the polyfills.js and main.js modules.

</html>
  ...
  <body>
    ...
    <div>
      <ev-creator></ev-creator>
    </div>
    <script src='envision/polyfills.js' type='module'></script>
    <script src='envision/main.js' type='module'></script>
    <script>
      // Custom Script calling evCreate API functions
    </script>
  </body>
</html>

The code calling evCreate API functions will not work without the front-end codebase in the given environment.

Example of the embedded Canvas Envision Creator and custom script

The image below displays an example of a front-end Canvas Envision Creator app embedded in a custom web page. The front-end app occupies the page partially. The page has two custom buttons outside the embedded app. The buttons insert objects into a given Envision document page as follows:

Insert Text: a text object with the following phrase: Hello world!
Insert Box: a rectangular shape object.

An example of embedded Canvas Envision Creator front-end app

Below is the source code for the discussed example.

<!DOCTYPE html>
  <html lang='en-US'>
  <head>
    <meta charset='utf-8'>
    <title>Testing stand alone</title>
    <base href='/'>
    <meta name='viewport' 
          content='width=device-width, initial-scale=1'>
    <link
            rel='icon'
            type='image/x-icon'
            href='favicon.ico'
    >
    <link rel='stylesheet' href='styles.css'>
    <script type='text/javascript' 
            src='assets/spacemouse/3dconnexion.min.js'
    ></script>
  </head>
  <style>
    /* CSS */
    .button-5 {
        align-items: center;
        background-clip: padding-box;
        background-color: #B3282E;
        border: 1px solid transparent;
        border-radius: .25rem;
        box-shadow: rgba(0, 0, 0, 0.02) 0 1px 3px 0;
        box-sizing: border-box;
        color: #fff;
        cursor: pointer;
        display: inline-flex;
        font-family: system-ui,-apple-system,system-ui,
                     "Helvetica Neue",
                     Helvetica,Arial,sans-serif;
        font-size: 16px;
        font-weight: 600;
        justify-content: center;
        line-height: 1.25;
        margin: 0;
        min-height: 3rem;
        padding: calc(.875rem - 1px) calc(1.5rem - 1px);
        position: relative;
        text-decoration: none;
        transition: all 250ms;
        user-select: none;
        -webkit-user-select: none;
        touch-action: manipulation;
        vertical-align: baseline;
        width: auto;
    }
  
    .button-5:hover,
    .button-5:focus {
        background-color: #D7272E;
        box-shadow: rgba(0, 0, 0, 0.1) 0 4px 12px;
    }
    .buttons-container{
        align-items: center;
        width: 40vw;
        flex-direction: column;
        display: flex;
    }
  </style>
  <body>
    <div>
      <div id='myDiv' style='justify-content: center; display: flex;'>
        <div class="buttons-container">
          <button class="button-5" role="button" onclick="insertText()">
            Insert Text
          </button>
          <button class="button-5" role="button" onclick="insertBox()">
            Insert Box
          </button>
        </div>
        <div style='width: 60vw; height: 800px;'>
          <ev-creator
                  env_api='https://apidev.canvasgfx.com/'
                  env_ws='wss://apidev.canvasgfx.com'
                  env_web_viewer_url='https://evdev.canvasgfx.com'
                  workspace='demo'
          ></ev-creator>
        </div>
      </div>
    </div>
    <script src='envision/polyfills.js' type='module'></script>
    <script src='envision/main.js' type='module'></script>
    <script>
      async function waitForEvCreateApiReady() {
          // Wait for evCreate Api to be ready.
          const until = function (predicateFn, intervalMsec) {
              const poll = resolve => {
                  if (predicateFn())
                      resolve();
                  else
                      setTimeout(() => poll(resolve), intervalMsec);
              }
    
              return new Promise(poll);
          }
          // Wait for window.evCreate property to be set.
          await until(() => window.evCreate !== undefined, 500);
          // Wait for api 'ready' event.
          await window.evCreate.config.WhenApiReady();
      }
    
      const insertText = async function () {
          await waitForEvCreateApiReady();
          await window.evCreate.object.text.Create('Hello world!', 
                { left: 400, right: 800, top: 200, bottom: 700 })
      }
    
      const insertBox = async function () {
          await waitForEvCreateApiReady();
          await window.evCreate.object.rectangle.Create(
                { left: 100, right: 200, top: 400, bottom: 600 })
      }
    </script>
  </body>
</html>

28 January 2025