App Context Tutorial

Use the app context to add commands, keybindings, and work with system resources such as the clipboard. When creating an extension the app context is likely where you should start.

Summary

• App Context API.

• Entry point app/main.ts

• Code runs in Bike's native app environment.

• Interact with outlines, clipboard, networking, etc.

• Some API's require appropriate manifest.json permissions.

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

Tutorial

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

Inside the app/main.ts entry point your extension should export an activate function, which is called when the extension is loaded.

export async function activate(context: AppExtensionContext) {
  ...
}

Look at existing extensions in the Bike Extension Kit to see some activate examples. For example the !bike.bkext extension adds commands, keybindings, and sidebar items. Right-click on any symbol and then choose "Go to Definition" from the popup to see API comments and options.

Many APIs follow a similar pattern: when you add something (like a command), a Disposable is returned. This disposable acts as a handle to the addition. To remove it, call .dispose().

Bike automatically disposes of everything added by your extension when it reloads. You only need to keep track of disposables if you plan to update or remove items dynamically.

Create a new Command

Let's modify !startup.bkext to define a new "Archive Done" command. The command will move all completed items to an "Archive" row. We'll be editing the main.ts file.

First add a function that will implement the archive done command:

function archiveDoneCommand(): boolean {
  console.log("Archive Done!");
  return true;
}

So far we've just added a function, next let's associate that function with a Bike Command:

export async function activate(context: AppExtensionContext) {
  bike.commands.addCommands({
    commands: {
      "startup:archive-done": archiveDoneCommand,
    },
  });
}

After saving your changes, Bike will automatically reload extensions, and the command will be available in the Command Pallet (Command-Shift-P). Try it out! When you select the command you should see "Archive Done!" printed in Bike's Logs Explorer window.

Next lets add a keybinding to activate this command. This will allow us to activate the command without having to use the Command Pallet:

export async function activate(context: AppExtensionContext) {
  ...
  bike.keybindings.addKeybindings({
    keymap: "block-mode",
    keybindings: {
      "a": "startup:archive-done",
    },
  });
}

After saving, enter block mode (press Escape), then type a. You should see "Archive Done!" printed in the Logs Explorer window. Keybindings are used when Bike's outline editor has keyboard focus. They are not used when other UI elements have keyboard focus.

Let's implement the archive done command for real:

1. Find checked-off rows.

2. Locate (or create) the Archive row.

3. Move completed items into the Archive row.

function archiveDoneCommand(): boolean {
  // Get frontmost editor
  let editor = bike.frontmostOutlineEditor
  if (!editor) return false

  // Get the outline, done rows, and archive row
  let outline = editor.outline
  let donePath = "//@data-done except //@id = archive//*"
  let doneRows = outline.query(donePath).value as Row[]
  let archiveRow = (outline.query("//@id = archive").value as Row[])[0]
  
  // Insert an Archive row if needed and move done rows
  outline.transaction({ animate: "default" }, () => {
    if (!archiveRow) {
      archiveRow = outline.insertRows([{ 
        id: "archive",
        text: "Archive",
      }], outline.root)[0]
    }
    outline.moveRows(doneRows, archiveRow)
  })
    
  return true
}

Now, when you run the Archive Done command, completed rows will be moved into the Archive section.

Next Steps

Create a custom UI for your extension using: Exensions: DOM Context.