How to update your plugin to support pop-out windows

With the desktop release of Obsidian v0.15, we’re introducing a new way of putting panes into pop-out windows. For most plugins adding simple DOM based plugin views, this should work out-of-the-box.

However, there are some things that work differently when your plugin renders things in pop-out windows.

Pop-out windows come with a complete different set of globals. It has its own Window object, Document object, and fresh copies of all global constructors (like HTMLElement and MouseEvent).

This means that some of the things you previously had assumed to be global and can have only one, will now only work in the main window. Here are some examples:

let myElement: HTMLElement = ...;

// this will always append to the main window
document.body.appendChild(myElement);

// this will actually be false if element is in a pop-out window
if (myElement instanceof HTMLElement) {

}

element.on('click', '.my-css-class', (event) => {
    // This will be false if the event is triggered in a pop-out window
    if (event instanceof MouseEvent) {

    }
}

To facilitate plugins, we’ve updated the Obsidian API to include various helper function and accessors.

• A global activeWindow and activeDocument variable, which always points to the current focused window and its document.
• element.win and element.doc, which points to the Window and Document objects that the element belongs to.
• A function for performing cross-window compatible instanceof checks. Use element.instanceOf(HTMLElement) and event.instanceOf(MouseEvent)
• HTMLElement.onWindowMigrated(callback) which hooks an event on the element for when it is inserted into a different window than it originally was in. This can be used for complex renderers like canvases to re-initialize the rendering context.

Using the new APIs, the previous example would look like this:

let myElement: HTMLElement = ...;

// this will append myElement to the same window as someElement
someElement.doc.body.appendChild(myElement);

// this will work correctly in pop-out windows
if (myElement.instanceOf(HTMLElement)) {

}

element.on('click', '.my-css-class', (event) => {
    // this will work correctly in pop-out windows
    if (event.instanceOf(MouseEvent)) {

    }
}