Plugins

Plugins are custom code you can write for the Navigator. They are written for a particular context, for example written for the cursor-bar where you can write your own "click" handling.

Plugins are written in Javascript with an optional HTML file as well.

You can add, edit, and enable plugins through the Navigator project view dashboard.

File layout

A Plugin is a zipped folder that includes an index.js and index.html file.

The HTML file (if present) will automatically be added to the context's HTML container. It will also be automatically removed when disposed.

Here is an example of a Plugin's index.js file.

// Ensure you have a Run function that takes a params object.
function Run(params) {
    console.log("Plugin was run", params);

    // HTML container the plugin is sitting in.
    // This may not exist if it's run as a background script!
    const container = params.container;

    // The element of the plugin itself.
    // This will be sitting inside the container element.
    // This will not exist if either the container or HTML template is not present.
    const element = params.element;

    // Ensure to return a dispose function.
    return () => {
        console.log("Plugin was disposed");
    };
}

Here is an example of a Plugin's index.html file. Please note the usage of an HTML ID for the styles and root element. It is highly recommended to work with a very unique ID to avoid conflicts with other Plugins and the Navigator itself.

<style>
    #MyPlugin {
        background-color: red;
        padding: 8px;
        border-radius: 8px;
        position: absolute;
        z-index: 1;
        left: 0;
        top: 0;
    }
</style>

<div id="MyPlugin">
    <span>
        My plugin!
    </span>
</div>

Plugin Locations

Location	Description
Cursor bar	The cursor bar is the toolbar found in the top-left corner of the Navigator. It is responsible for actions the user performs when clicking on the scene or Entities in the scene.
Info View	The Info View panel is the dialog that appears when an Entity is selected.
Sidebar	The side bar is the toolbar found in the left side of Navigator which holds Menu Items, Bookmarks, and Scene Tree. Note: Set the Plugin setting "panelWidth" to a CSS width to change the default panel width, eg: "500px". The default value is "300px".
Background	Plugins that are set to load in the background will load automatically when the page loads without the user needing to click any buttons.

Plugin Params

Below are what parameters are passed into the Plugin's Run function in Navigator.

function Run(params) {
    console.log("Plugin was run", params);
    const pluginParams = params.pluginParams;

    // Plugin record itself.
    // Useful for accessing the settings object within it.
    const plugin = params.plugin;

    // Reference to the Cesium viewer.
    const viewer = pluginParams.viewer;

    // Reference to the Menu Item manager and visual register.
    // This lets you manage Menu Items and know what is currently rendered in the scene.
    const manager = pluginParams.menuItemManager;
    const register = pluginParams.visualRegister;

    // Reference to Cesium, bruce-models, and bruce-cesium NPM libraries.
    const Cesium = pluginParams.Cesium;
    const BModels = pluginParams.BModels;
    const BEngine = pluginParams.BEngine;

    // Reference to function to call so you can force the plugin to dispose and the tool to be disabled.
    const close = pluginParams.close;
    // close();

    // Reference to function to call to open/close a Navigator side-panel.
    // Options are: "dashboard", "menu-items", "bookmarks", "scene-tree", "user", "scene-config", "entity-editor"
    // "comments", "markup", and "walkthrough".
    // If you have an active side-bar plugin, you can open it through "PLUGIN_<THE_PLUGIN_ID>" eg: "PLUGIN_1234abcd".
    const setPanelActive = pluginParams.setPanelActive;

    // Open a panel:
    // setPanelActive("bookmarks", true);

    // Close a panel:
    // setPanelActive("bookmarks", false);

    // Reference to function to call to select or deselect Entities.
    const select = pluginParams.select;
    /*
     * select({
     *     entityIds: ["a", "b"]
     * })
     */

    // Reference to function to call to refresh Entities in the scene/panels.
    const refreshData = pluginParams.refreshData;
    /*
    * refreshData({
    *     entityIds: ["a", "b"]
    * });
    */

    // Reference to function to call to toggle "liveness" of Entities.
    // When an Entity is live, it periodically refreshes its data.
    const updateLiveData = pluginParams.updateLiveData;

    /*
    * Replace current live Entity IDs with given IDs.
    * updateLiveData({
    *     entityIds: ["a", "b"]
    * });
    */

    /*
    * Add given Entity IDs to the current live Entities.
    * updateLiveData({
    *     entityIds: ["a", "b"],
    *     action: true
    * });
    */

    /*
    * Remove given Entity IDs to the current live Entities.
    * updateLiveData({
    *     entityIds: ["a", "b"],
    *     action: false
    * });
    */

    return () => {
        console.log("Plugin was disposed");
    };
}