Plugin APIs

Build small tools that extend your Emberly workspace.

Table of content
  1. Available APIs
  2. A plugin project
  3. Edit, save, preview

Emberly plugins are JavaScript projects that can show interfaces, store settings, read map content, draw on topics, and add custom note blocks.

Experimental. This reference describes the plugin workspace currently in development. Availability depends on your Emberly instance; these APIs are not yet a stable public contract.

Available APIs

Each API is a capability that your plugin requests in its manifest and the user approves before it runs.

API What you can do Where it runs
ui Show dialogs, controls, and plugin output Workspace or live preview
kv Save private plugin settings and state Workspace or live preview
theme Read the current theme Workspace or live preview
app Read navigation state and navigate within Emberly Workspace or live preview
data Read topics, notes, and resources in the approved map Live preview in an open map
map Draw temporary graphics and text around topics Live preview in an open map
editor Register custom note blocks and save their content Live preview in an editable map; also requires ui

A plugin project

Every project has a manifest.json and an index.js. The manifest names the plugin and requests only the APIs it needs.

{
  "name": "Hello Emberly",
  "version": 1,
  "api": { "ui": true }
}

The entry file exports a class extending PluginAPI. Emberly calls onMount() when the plugin starts.

export default class HelloEmberly extends PluginAPI {
  async onMount() {
    const dialog = await this.ui.openDialog({ title: 'Hello Emberly' });
    const message = await dialog.createElement('p', {
      text: 'Your plugin is running.'
    });
    await dialog.appendChild(message);
  }
}

Edit, save, preview

  1. Open the Plugin workspace and create a plugin from a template.
  2. Edit and save your JavaScript. The editor shows problems as you type; Compile checks saved files.
  3. Choose Run for workspace plugins, or Live preview to connect another Emberly window with an open map.
  4. Approve the requested capabilities in the window where the plugin will run.
  5. Save changes to update a connected live preview. A failed build keeps the previous successful preview running and labels it as such.

You can save unfinished code. Errors block compilation; warnings do not. A successful build still needs to be run to test its behavior.

Read Capabilities and permissions for the scope of each grant and current limitations.