DOM Context Tutorial

Use the DOM context to display custom UI using HTML/DOM. Currently you can present a sheet over a window or you can add views to the inspector bar.

Summary

• DOM Context API.

• Entry points dom/*.ts

• Code runs in web views embedded in Bike’s UI.

• Web views are sandboxed and have no network access.

• These views are loaded dynamically using bike/app context APIs.

• Communicate with app context using postMessage and onMessage.

• Import dom context API using import { SYMBOL } from 'bike/dom'.

Tutorial

Note: Finished tutorial can be found in src/tutorial.bkext.

To display custom UI your app context code 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.

Steps

1. Create a dom script at dom/<scriptname>.

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

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

Example

Create a new DOMScript at dom/inspector_item.ts:

import { DOMExtensionContext } from "bike/dom";

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

Next, add code that loads the DOMScript from the app context in app/main.ts:

import { AppExtensionContext, Window } from "bike/app";

export async function activate(context: AppExtensionContext) {
  bike.observeWindows(async (window: Window) => {
    let handle = await window.inspector.addItem({
      id: 'tutorial:inspector-item',
      name: 'inspector-item.js',
    })
    handle.postMessage('Hello from the app context!')
  })
}

Build and install your extension and reveal the inspector bar with View > Show Inspector. You should see the text "Hello from app context" in the sidebar. Success!

Using React

Bike bundles a copy of react that you can use in your DOM extensions. For example when you import { useState } from 'react' you will access the bundled version of React from your extension.

Next Steps

Create an outline editor stylesheet using: Exensions: Style Context.