Creating View Extensions

Use DOMScripts to display custom UI using HTML/DOM.

Normally, extension code runs in a headless JSContext. This code has access to Bike-specific APIs, but cannot use HTML/DOM. To display custom UI your extension installs a DOMScript into a WebView that's hosted by Bike.

If you’ve used Web Workers, the architecture will feel familiar: both run in isolated script contexts and communicate with the originating context using postMessage and onmessage.

DOMScripts are loaded by name and must be located in the src/dom folder of your extension. Bike API's that allow you to install DOMScripts include window.presentSheet and window.inspector.addItem.

DOMScripts Summary:

1. Used to display UI using HTML/DOM.

2. Do not have access to standard extension APIs.

3. Run in a separate context from standard extension code.

4. Must be located in the extension's src/dom folder and loaded by name.

5. Communicate with extension code via postMessage and onmessage.

6. For security network access is disabled for DOMScripts. To display network accessed information the originating extension should perform a fetch and the postMessage to results to the DOMScript.

Getting Started

To install a DOMScript:

1. Create a dom script in /src/dom/<scriptname>.

2. Add the domScript permission to your extension's manifest.json.

3. Pass the DOMScriptName to a Bike's API such as window.inspector.addItem.

4. Use the returned handle to communicate with the DOMScript using onmessage and postMessage.

Example

First lets modify our manifest.json so that our extension is allowed to install DOMScripts.

{
  ...
  "permissions": [
    "domScript"
  ]
}

Next create a new DOMScript at src/dom/inspector_item.ts. Note, DOMScript must always be placed in the top level of the src/dom subfolder.

import { DOMExtensionContext } from "bike";

// This script starts by displaying a "Loading..." message, and then listens 
// for messages to display from the main extension script. 
export function activate(context: DOMExtensionContext) {
    context.element.textContent = "Loading..."
    context.onmessage = (message) => {
        context.element.textContent = message
    }
}

Finally add the following code to your extensions main.ts file. This extension code adds our DOMScript to each window's inspector. Once the DOMScript has loaded our extension posts a message to the script.

import { AppExtensionContext, Window } from "bike";

export function activate(context: AppExtensionContext) {
    bike.observeWindows((window: Window) => {
        window.inspector.addItem({
            id: "startup:inspector_item",
            name: "inspector_item.ts",
        }).then((handle) => {
            // Once the item is added use the handle to send the dom script a message
            handle.postMessage("Hello from app context!");
        });
    });
}