Altair EEvision is used for interactive visualization and exploration of cable harnesses. It comprises two parts:
the EEvision Core (eevcore.html), which is essentially a white
drawing area for rendering cable harness diagrams. It can be controlled via
a TypeScript/JavaScript API. This is the required component if you want to
integrate EEvision into another tool.
the EEvision GUI (main2.html). This is a web-based tool for
end users. It allows users to interactively explore a wire harness
database (in Altair's EDB format). The EEvision GUI is extensible using
plugins that are written in JavaScript (and Tcl if some server-side
extension is required).
This documentation describes the EEvision APIs that can either be used to integrate the EEvision Core into other systems or to extend the EEvision GUI through plugins.
All APIs for controlling the EEvision Core are included in the NPM package
eevision, which has two modules: eevision/api is the primary module with
the core functionality; eevision/edb contains an extension that enables
direct access to the contents of EEvision's cable harness database.
The EEvision Core runs within an <iframe> element of the embedding
web page. The iframe must load the file eevcore.html from the EEvision
distribution.
<!DOCTYPE html>
<html lang="en-US">
...
<body>
...
<button id="lall" disabled>Load All</button>
...
<iframe id="eevision"></iframe>
...
</body>
</html>
It is possible to load eevcore.html from a different URL than the embedding
web page as long as the security rules of the server shipping EEvision allows
such cross-origin usage.
Using JavaScript, the behavior of the iframe can be controlled using an EEvisionAPI object, which is the starting point for every integration effort:
import { EEvisionAPI } from "eevision";
const iframe = document.getElementById("eevision");
iframe.onload = async () => {
const eev = new EEvisionAPI(iframe);
await eev.Init("?edb=dataset.edb");
// Now all EEvision Core API functions can be used.
// Use the "Load All" button to execute an API function:
const lall = document.getElementById("load_all");
lall.onclick = async () => {
await eev.LoadAll();
};
lall.disabled = false;
};
iframe.src = "eevcore.html";
This code snippet first retrieves the HTMLIFrame object from the web page's
DOM. In order not to miss the onload event, the URL to be loaded into
the iframe should be set after installing the event handler.
When the iframe has finished loading, an instance of the EEvisionAPI
is created. The eev object is initialized with the
harness database dataset.edb, which must be available on the server.
After initialization, the button with the ID load_all is retrieved from
the DOM. A handler is registered that is called when the user clicks on
the button. This handler executes the LoadAll() function of EEvision.
There are essentially two kinds of errors that can occur:
Errors resulting from failed API calls. They result in a rejected promise and can be handled accordingly:
try {
eev.LoadObj([17, 346]);
} catch (error) {
// report the error
}
Apart from these errors, also the interaction of the user with EEvision might fail (like double-clicking an object to expand it). In this case, there is no API call that can fail. Such errors are therefore reported to the error handler that can be installed on the EEvisionAPI object:
const eev = new EEvisionAPI(...);
eev.onError = (message, type) => {
// handle the error
};
It is desirable to install an error handler in EEvision before initialization. This way, also unexpected errors are reported, e.g., resulting from lost server connections.
Since the EEvision API uses message passing to communicate with the iframe, essentially every API function call can throw an error.
The EEvision GUI can be extended using plugins. Every plugin is a JavaScript module that exports a set of functions, which are called by EEvision when certain events happen. The following two functions are mandatory. If necessary, they can be asynchronous (as in the following).
export async function load() {
/* Initialize the plugin */
}
export async function unload() {
/* Cleanup, remove created DOM elements etc. */
}
They are called when the plugin is loaded and unloaded, respectively.
The purpose of load() is to create the GUI elements of the plugin like
buttons, entries of the dropdown menu etc. together with their event handlers.
If a server-side extension is required, it is also loaded here.
The function unload() is called when the plugin is removed from EEvision.
It must remove all GUI elements it has created, unload the server extension etc.
The remaining exported functions are event handlers that are called by EEvision, e.g., when the set of selected objects or the schematic changes.
export async function onSelection(selected) {
// The set of selected objects has changed.
}
export async function onSchematicChange(reason) {
// The set of loaded objects has changed, e.g., because of a
// call to API.LoadObj(...) or because the user has interactively
// expanded or reduced the schematic.
}
export async function onPageChange(details, page, npages) {
// The number of pages or the current page has changed.
// Since EEvision by default only has one page, this handler
// is rarely needed.
}
export async function onHistoryRequest(...) {
// A new history state is created or the current history state is
// updated. If the plugin needs to store data as part of the history
// state, this handler is expected to return that data.
}
export async function onHistoryRestore(eev_state, plugin_state) {
// A previously stored history state needs to be restored.
}
These functions are optional; they are only called if the plugin module exports them.
The PluginAPI is an extension of the class EEvisionAPI by
GUI-specific methods. It is available as the global variable API such that
plugins do not have to import the module eevision_gui/plugin_api, but
(if they are written in TypeScript) should contain the declaration
declare const API: PluginAPI; instead.
Note: The GUI-specific methods that are available to plugins via the API
object are not available when only the EEvision Core is integrated via an
<iframe> element!
The following TypeScript code snippet creates a button in the toolbar of EEvision with the text "Fit". Clicking on the button zooms the schematic such that it fits completely onto the screen.
import { type PluginAPI } from "plugin_api";
declare const API: PluginAPI;
export function load(): void {
const button = API.CreateButton("zoom_fit", {
text: "Fit",
title: "Zoom such that the whole schematics fits onto the screen",
location: "center",
});
button.onclick = async (): Promise<void> => {
await API.Fullfit("xy");
};
}
export function unload(): void {
const button = document.getElementById("zoom_fit");
if (button) button.remove();
}