Hosting a model viewer
Important: Online model publishing is only available to PRO subscription plan users.
This page describes in detail how to autonomously host a Web Excelsior Viewer and a collection of WEBEX models on your website.
This is the preferred method if you wish to:
- Embed interactive jewelry on the body of your web page, like we do in our Homepage.
- Showcase a gallery of designs, like we do in our Gallery.
Advantages of self-hosting the Viewer
There are several advantages to hosting the Viewer in your site over sharing Viewer links or using an <iframe>:
- True embedding. Shared Viewer links or iframes (as also covered by the docs) are not truly embedded content.
- No CORS problems. Hosting the Viewer and the interactive models under the same domain avoids CORS problems.
- Load speed. Hosting the Viewer and the interactive models under the same domain optimizes transfer (load) speed.
- Version-locking. Hosting the Viewer yourself (instead of relying on the master copy in maverickexcelsior.com) keeps you safe from compatibility-breaking changes that might happen in the future.
Step-by-step guide
Important: This section assumes that you have sufficient knowledge of JavaScript, HTML and CSS to get our Viewer module to work.
It is also assumed that you manage a web server with an FTP you can upload files to.
1- Uploading the Viewer’s JavaScript files
The Web Excelsior Viewer is comprised of a handful of files that you must upload to your FTP.
This .zip file below contains the Viewer files for version 53573:
Compatibility note: As we keep improving Maverick Excelsior, newer versions of the Viewer will become available. However, you should stick to a version of the Viewer that matches as closely as possible the version of the Editor you created your webex files with. i.e., once you’re up and running there is no need to upgrade the Viewer files to a newer version, unless you produce newer .webex models with a newer Editor.
Inflate and upload these files to your FTP. Throughout this example we will assume that the files will be placed in the directory:
/htdocs/wp-content/builds/wasm/
Like this:
/htdocs/wp-content/builds/wasm/webex-viewer-53573.data /htdocs/wp-content/builds/wasm/webex-viewer-53573.js /htdocs/wp-content/builds/wasm/webex-viewer-53573.wasm /htdocs/wp-content/builds/wasm/webex-viewer-module.js /htdocs/wp-content/builds/wasm/webex-viewer-version.js
Important: You may choose any directory in your FTP as long as these files are publicly accessible.
2- Editing the version file
Edit the webex-viewer-version.js file you just uploaded so the basedir variable matches the directory you chose in the previous step.
const g_webex_basedir = '/htdocs/wp-content/builds/wasm/'; const g_webex_viewer_version_js = 'webex-viewer-53573.js';
3- Uploading your WEBEX models
Now upload your .webex model files to the FTP.
Important: It is required that these files are publicly accessible from the outside world via URL.
Let’s say that you upload the WEBEX models to the same folder, next to the Viewer files.
/htdocs/wp-content/builds/wasm/My-Model-01.webex /htdocs/wp-content/builds/wasm/My-Model-02.webex ...
So their public URLs are:
https://yourdomain.com/wp-content/builds/wasm/My-Model-01.webex https://yourdomain.com/wp-content/builds/wasm/My-Model-02.webex ...
4- CSS/HTML/JS
Next you will need to add some code to your web page.
For the sake of providing a working example, this piece of CSS is just an example with a few definitions to go along the rest of the code presented here.
Note that you will most likely want to provide your own CSS to accomodate to your website’s look and feel.
<style>
.frame-div {
display: block;
position: fixed;
left: 0;
top: 0;
width: 100%;
height: 100%;
}
.frame-div .frame-canvas-div {
position: fixed;
left: 0;
top: 0;
width: 100%;
height: 100%;
}
.frame-div canvas {
width: 100%;
height: 100%;
touch-action: none;
visibility: visible;
aspect-ratio: 1;
}
</style>
The important part in the next piece of HTML code is the <canvas> element that will host the Web Excelsior Viewer. The existence of this canvas its mandatory, and its id must be “canvas” just like in the code below.
You may freely change the resolution, aspect ratio, and the host divs or their CSS styling to your liking, though.
<div class="frame-div"> <div class="frame-canvas-div"> <canvas id="canvas" width="640" height="640" oncontextmenu="event.preventDefault()"></canvas> </div> </div>
The next piece of code is where the Web Excelsior Viewer is initialized.
Before you copy-paste this code snippet you must:
- Replace the two occurrences of the /htdocs/wp-content/builds/wasm/ string by the directory you uploaded the .js files to.
- Replace the URL next to open_scene by the public URL of the .webex model you want the Viewer to display on start.
<script type="text/javascript" src="/htdocs/wp-content/builds/wasm/webex-viewer-version.js"></script>
<script type="text/javascript" src="/htdocs/wp-content/builds/wasm/webex-viewer-module.js"></script>
<script type="text/javascript">
document.addEventListener("DOMContentLoaded", () => {
const js = document.createElement("script");
js.setAttribute("src", (g_webex_basedir + g_webex_viewer_version_js));
js.onload = () => {
Module.json = {
'open_scene': 'https://yourdomain.com/wp-content/builds/wasm/My-model-01.webex'
};
}
document.head.appendChild(js);
});
</script>
5- Alternate method
The method described so far assumes that you are hosting the Viewer module yourself, which is the preferred solution. As explained above, this guarantees version-locking and future-proofing.
However, should you prefer to rely on the master copy of the Viewer hosted in maverickexcelsior.com, you could:
- Not upload/edit the module files in the .zip as explained above.
- Replace the last snippet of code above by this:
<script type="text/javascript" src="https://maverickexcelsior.com/wp-content/builds/wasm/webex-viewer-version.js"></script>
<script type="text/javascript" src="https://maverickexcelsior.com/wp-content/builds/wasm/webex-viewer-module.js"></script>
<script type="text/javascript">
document.addEventListener("DOMContentLoaded", () => {
const js = document.createElement("script");
js.setAttribute("src", (g_webex_basedir + g_webex_viewer_version_js));
js.onload = () => {
Module.json = {
'open_scene': 'https://yourdomain.com/wp-content/builds/wasm/My-model-01.webex'
};
}
document.head.appendChild(js);
});
</script>
This method will be free of CORS problems as long as the HTML you enter this code in is hosted in the same domain (https://yourdomain.com/) as your .webex files.
But note that, despite simpler, this alternate solution relies on the newest version of the Viewer available in maverickexcelsior.com, which may become incompatible with your WEBEX models at some point.
Summary: We recommend that you host the Viewer’s module files yourself.
Creating a gallery
The code example provided above will allow you to embed one instance of the Web Excelsior Viewer right into the body of your webpage. This is pretty much what we did for the emerald ring we showcase at the top of the Maverick Excelsior Homepage.
However, you may want to create a gallery of models like our Interactive Gallery. To this end you will need to code your way into some sort of lightbox or modal popup to host the Viewer canvas. This is what our gallery does. Feel free to View Page Source to learn how.
In our gallery there is just one <canvas> element hosted by a modal dialog, and every time the user clicks on a new thumbnail card, the popup is recalled and the canvas is signaled to open a different .webex file.
This is accomplished with the JavaScript command webex_in(), which syntax is:
webex_in( 'open_scene', 'https://yourdomain.com/wp-content/builds/wasm/My-model-01.webex', '', '', '' );
You can invoke this command in response to onclick events and such.
—
Previous docs: