Plugins


Plugins are custom code you can write for Navigator. They are written for a particular location, for example a side bar panel, a tool in the cursor bar, or a tab in the selected Entity panel.

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

You can create Plugins, upload their code and enable them on a Project View through the Plugins menu in Navigator. Plugins can also be managed in Operator. This article covers the shape of a Plugin, where it can run and what it is handed. You can read about writing, testing and uploading one in Plugins: Development.

File layout

A Plugin is a ZIP with an index.js file at its root, and an optional index.html file beside it.

The HTML file, if present, is added to the Plugin's element when it loads. It is removed with the element when the Plugin is disposed.

Any other file in the ZIP is served from ui.plugin/{pluginId}/file/{fileName}, so a Plugin can ship images, data or libraries of its own and fetch them at runtime. The UI toolkit is loaded this way.


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.
    // In the cursor bar and background locations this is the viewer's own container.
    const container = params.container;

    // The element of the plugin itself, sitting inside the container.
    // Navigator removes it when the plugin is disposed.
    const element = params.element;

    // The plugin's own ID and record. The record carries Settings,
    // which is where per-account configuration belongs.
    const pluginId = params.pluginId;
    const plugin = params.plugin;

    // 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 Navigator itself. The UI toolkit generates its class names per Plugin, so a Plugin built with it does not need this.

<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

A Plugin's location decides where it can be loaded, what container it gets, and which params it is handed.

LocationDescription
Cursor bar
NAVIGATOR_CURSOR_BAR
The cursor bar is the toolbar found in the top-left corner of Navigator. It is responsible for actions the user performs when clicking on the scene or Entities in the scene.

The Plugin loads when the user picks the tool and is disposed when they pick another, so a cursor Plugin needs no state of its own to know whether it is active. Its element sits over the viewer rather than in a panel.
Cursor bar
Info View
NAVIGATOR_INFO_VIEW
The Info View panel is the dialog that appears when an Entity is selected. This location replaces that panel's contents, so the Plugin is responsible for presenting the Entity itself.

It is chosen by a Project View's selection settings rather than by enabling it: a selection action of "PLUGIN" with the Plugin's ID in "actionParams". You can read about selection settings in Project Views.
Info View
Selected Entity panel tab
NAVIGATOR_INFO_VIEW_ENTITY
Adds a tab alongside Navigator's own tabs in the selected Entity panel, rather than replacing it. This is usually what you want: the user keeps the built-in views and gains yours.
Selected Multi-Entity panel tab
NAVIGATOR_INFO_VIEW_MULTI_ENTITY
The same, for when several Entities are selected at once.
Sidebar
NAVIGATOR_SIDE_BAR
The side bar is the toolbar found in the left side of Navigator which holds Menu Items, Bookmarks, and Scene Tree. The Plugin gets a panel of its own.

Set the Plugin setting "panelWidth" to control the panel's width. See Side panel width below. The Plugin is reloaded when the Project View changes.
Background
NAVIGATOR_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. Its element sits over the viewer.

A background Plugin loads once the first Bookmark has loaded, and is reloaded when the Project View or the active Bookmark changes.
AI Tool
AI_TOOL
Not a piece of UI. The Plugin is offered to the AI agent as a callable tool and exports Invoke rather than Run. You can read about it in Plugins: AI Tools.
Operator
OPERATOR
Loads inside the Operator management portal rather than Navigator. See Operator Plugins below, since its params are not Navigator's.

A Plugin can also run inside a Custom Form, as a form component of "PLUGIN" with the Plugin's ID in its "pluginId" param and an optional "height", which is 250 pixels by default. You can read about Custom Forms in Custom Forms.

Enabling a Plugin

Setting a location is not enough on its own. Every Plugin must have "Enabled" set on its record, and most must also be enabled on the Project View being viewed:

  • Cursor bar, Sidebar, Background and both selected Entity panel tabs must be enabled on the Project View. Navigator's Plugins menu does this, and it is stored in the view's "plugins.enabledIds" setting.
  • Info View and Custom Form Plugins are chosen by the Project View's selection settings and by the form, so they are not enabled on the view.
  • AI Tools are available across the account as soon as they are enabled.

A Plugin that appears to do nothing is almost always a Plugin that was never enabled on the view.

Plugin Params

Below are the parameters every Navigator location passes into the Plugin's Run function.

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.
    // No location is handed the selected Entity, read the selection from the register.
    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;

    // The current context, without needing a request for any of it.
    // 'getters' is already pointed at this account and session.
    const getters = pluginParams.getters;
    const session = pluginParams.session;
    const account = pluginParams.account;
    const version = pluginParams.version;

    // Reference to function to call so you can force the plugin to close.
    // What closing means depends on the location, see the table below.
    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 from the current live Entities.
     * updateLiveData({
     *     entityIds: ["a", "b"],
     *     action: false
     * });
     */

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

Params by location

Not every location is handed every param. The params above are present everywhere in Navigator. The ones below depend on where the Plugin runs, so check for a param rather than assuming it.

ParamWhereWhat it is
viewEvery location except the cursor barThe active Project View record.
getCursor, setCursor, cursorIdsEvery location except the cursor barReads and sets the active cursor tool. "cursorIds" holds the tool IDs, so a Plugin can call setCursor([cursorIds.Pan]) while it asks the user to click a position, without the click selecting an Entity.
setPanelWidthSidebarChanges the panel width at runtime, taking the same value as the panelWidth setting. Affects the current session only.
setFocusedAttachmentInfo View, selected Entity panel tab, Custom FormOpens Navigator's own attachment viewer on an attachment, with its siblings, so a Plugin does not need to build media browsing itself. Called as setFocusedAttachment(attachment, siblings).
viewId, bookmark, bookmarkId, enableBookmarkBackgroundThe active Project View's ID, the active Bookmark, its ID, and a call to activate a Bookmark.
d3Custom FormThe d3 library, for drawing charts inside the form.

What close does also depends on the location:

Locationclose()
Cursor barSwitches back to the select tool, which disposes the Plugin.
SidebarCloses the panel.
BackgroundDisposes this Plugin until it is next reloaded.
Info View, both selected Entity panel tabs, Custom FormDeselects everything, which closes the panel.

The Plugin record

Every Plugin is handed its own record as params.plugin. It is worth knowing what is on it, because several fields exist specifically so a Plugin does not have to be edited per account or per deployment.

FieldWhat it does
SettingsArbitrary JSON, passed to the Plugin when it loads. This is where an Entity Type ID, an endpoint, a threshold or a colour belongs, so one Plugin serves every account with no code change. Also carries the reserved panelWidth, and tool for AI Tools.
EnabledTurns a Plugin off without unpicking it from every Project View that references it.
GroupAn arbitrary grouping you can query against, so a whole related set can be retrieved and enabled at once. This is how an embedded Navigator can be told to enable a group of Plugins by URL param, and have that set change without the URL changing.
VersionIncreased every time a new code bundle is uploaded, and used as the cache key for the Plugin's code. You can read about caching in Plugins: Development.
Icon, IconSourceThe button icon, either a Font Awesome class (FONT_AWESOME) or a Client File ID (CLIENT_FILE) for your own image. For background Plugins the icon is only for identification in admin panels.
IsLoginRequiredRequires a logged-in user. The Plugin's files are then fetched with the user's session rather than through the CDN.
IsAccessRestrictedRestricts the Plugin to users granted access to it, either through the UIPlugin_<pluginId> permission or a User Group grant set in Operator. The API refuses the Plugin's code to anyone else, and Navigator shows them a message that they do not have access.

We recommend leaving both of these off. Users usually control access through Project View access control and Entity Type access control, and a Plugin runs with the user's own permissions, so it can only show what that user can already see. Restrictions on the Plugin itself add a second set of rules to keep in step with those. Turn them on only when the Plugin itself must be hidden from some users. You can read about Project View access in Project Views.

Side panel width

A side bar Plugin's panel is 300px wide by default. The panelWidth setting takes either a fixed CSS width or a range, and a range is what makes the panel user-resizable.

{
    "panelWidth": "500px"
}

{
    "panelWidth": "300px-900px"
}

{
    "panelWidth": "300px-900px-480px"
}

A single value is a fixed width. Two values are a minimum and a maximum, which the user can drag between. Three values add the width to open at. A Plugin can also change this while it runs through the setPanelWidth param, which affects the current session only and does not rewrite the setting.

On a phone the side panel opens as a sheet across the bottom of the screen and takes the full width, so "panelWidth" does not apply there. Lay the panel out to fit whatever width it is given.

Operator Plugins

An Operator Plugin is handed a smaller set of params. There is no viewer, register or Menu Item manager, and none of the Navigator calls such as "close" and "select".

function Run(params) {
    const pluginParams = params.pluginParams;

    // A function here rather than an ApiGetters instance.
    // Call it to get one: pluginParams.getters().GetBruceApi()
    const getters = pluginParams.getters;

    const session = pluginParams.session;
    const account = pluginParams.account;
    const version = pluginParams.version;
    const Cesium = pluginParams.Cesium;
    const BModels = pluginParams.BModels;
    const BEngine = pluginParams.BEngine;

    // Opens an Operator blade beside the Plugin's own.
    const openChild = pluginParams.openChild;

    return () => {};
}

Worked examples

The FAQ pages in this section answer the cases most Plugins start from: making API requests, letting the user pick a position in the scene, and rendering directly to the Cesium viewer. The AI Tools page covers the agent-callable location, which uses a different entry point entirely.

You can read about writing, testing and uploading a Plugin in Plugins: Development, and about building its panel in Plugins: UI toolkit.