dbrowser.panes

dBrowser includes the ability to split the page into multiple panes which navigate independently. This API gives applications the ability to "attach" to other panes and coordinate their browsing as well as inject JS/CSS.

Currently each pane can attach and manage one other pane at a time. The user must grant permission to use the panes API.

API

dbrowser.panes.setAttachable()

Mark the pane as "attachable." This will cause the attachment UI to display in the app's status bar, even if the pane is not attached to anything.

  • Returns Void.
dbrowser.panes.setAttachable()

dbrowser.panes.getAttachedPane()

Get the currently attached pane. Returns undefined if no pane is attached.

  • Returns Void|Object.
    • id Number. The pane's identifier.
    • url String. The pane's current location.
var pane = dbrowser.panes.getAttachedPane()
if (pane) {
console.log(pane.id) // some number
console.log(pane.url) // the current address of the pane
}

dbrowser.panes.attachToLastActivePane()

Attempts to attach to the pane that was active prior to the current pane. Can be used during setup to automatically attach to the pane in use.

Requires permission from the user.

  • Returns Promise<Void|Object>.
    • id Number. The pane's identifier.
    • url String. The pane's current location.
var pane = await dbrowser.panes.attachToLastActivePane()
if (pane) {
console.log(pane.id) // some number
console.log(pane.url) // the current address of the pane
}

dbrowser.panes.create(url, {attach: boolean})

Creates a new pane and optionally attaches to the pane automatically.

Requires permission from the user.

  • url String. The URL to open in the new pane.
  • opts Object.
    • attach Boolean. Attach to the new pane. Defaults to false.
  • Returns Promise<Object>.
    • id Number. The pane's identifier.
    • url String. The pane's current location.
var pane = await dbrowser.panes.create('https://dbrowser.com', {attach: true})
console.log(pane.id) // some number
console.log(pane.url) // the current address of the pane

dbrowser.panes.navigate(paneId, url)

Navigates the pane to the given URL. The given pane must be attached.

  • paneId Number. The ID of the pane to navigate.
  • url String. The URL to open in the target pane.
  • Returns Promise<Void>.
await dbrowser.panes.create(pane.id, 'https://dbrowser.com')

dbrowser.panes.focus(paneId)

Gives focus to a different pane. The given pane must be attached.

  • paneId Number. The ID of the pane to navigate.
  • Returns Promise<Void>.
await dbrowser.panes.focus(pane.id)

dbrowser.panes.executeJavaScript(paneId, script)

Runs the given javascript in a different pane. The given pane must be attached.

Requires permission from the user.

  • paneId Number. The ID of the pane to navigate.
  • script String. The script to execute.
  • Returns Promise<Any>.
var res = await dbrowser.panes.executeJavaScript(pane.id, 'alert("hello!")')
console.log(res) // undefined
var res = await dbrowser.panes.executeJavaScript(pane.id, 'window.location.toString()')
console.log(typeof res) // string

dbrowser.panes.injectCss(paneId, styles)

Inserts CSS into a different pane. The given pane must be attached.

Requires permission from the user.

  • paneId Number. The ID of the pane to navigate.
  • styles String. The styles to inject.
  • Returns Promise<Number>. An ID which can be used to uninject the styles.
var cssId = await dbrowser.panes.injectCss(pane.id, 'body { color: red; }')
console.log(typeof cssId) // number

dbrowser.panes.uninjectCss(paneId, cssId)

Removes injected CSS from a pane. The given pane must be attached.

Requires permission from the user.

  • paneId Number. The ID of the pane to navigate.
  • cssId Number. The ID of the injected styles to remove.
  • Returns Promise<Void>.
var cssId = await dbrowser.panes.injectCss(pane.id, 'body { color: red; }')
console.log(typeof cssId) // number
await dbrowser.panes.uninjectCss(pane.id, cssId)

"pane-attached" event

Emitted when a pane has been attached to the current app.

  • detail.id Number. The ID of the attached pane.
dbrowser.panes.addEventListener('pane-attached', e => {
console.log(e.detail.id) // some number
})

"pane-detached" event

Emitted when a pane has been detached from the current app.

dbrowser.panes.addEventListener('pane-detached', e => {
// ...
})

"pane-navigated" event

Emitted when the attached pane has changed its current location.

  • detail.url String. The new URL of the attached pane.
dbrowser.panes.addEventListener('pane-navigated', e => {
console.log('navigated to', e.detail.url)
})

Example app

This example app can help you familiarize with the panes API.

<!doctype html>
<html>
<head>
<title>Panes Demo</title>
<style>
body {
font-family: sans-serif;
text-align: center;
max-width: 600px;
margin: 0 auto;
}
button {
display: block;
padding: 10px;
width: 100%;
margin-bottom: 10px;
font-size: 16px;
}
</style>
</head>
<body>
<h1>dbrowser.panes API Demo</h1>
<button id="create">Create Attached Pane</button>
<button id="nav1" class="requires-attached" disabled>Navigate pane to dbrowser.dev</button>
<button id="nav2" class="requires-attached" disabled>Navigate pane to example.com</button>
<button id="exec" class="requires-attached" disabled>Execute JS in pane</button>
<button id="inject" class="requires-attached" disabled>Inject CSS in pane</button>
<script type="module">
function setDisabled (b) {
if (b) Array.from(document.body.querySelectorAll('.requires-attached'), el => el.setAttribute('disabled', 'disabled'))
else Array.from(document.body.querySelectorAll('.requires-attached'), el => el.removeAttribute('disabled'))
}
setDisabled(true)
dbrowser.panes.setAttachable()
dbrowser.panes.attachToLastActivePane().then(res => {
if (res) setDisabled(false)
})
const on = (el, evt, fn) => el.addEventListener(evt, fn)
on(create, 'click', e => dbrowser.panes.create('https://example.com', {attach: true}))
on(nav1, 'click', e => dbrowser.panes.navigate(dbrowser.panes.getAttachedPane().id, 'https://dbrowser.dev'))
on(nav2, 'click', e => dbrowser.panes.navigate(dbrowser.panes.getAttachedPane().id, 'https://example.com'))
on(exec, 'click', e => dbrowser.panes.executeJavaScript(dbrowser.panes.getAttachedPane().id, 'alert("hello from " + location.toString())'))
on(inject, 'click', e => dbrowser.panes.injectCss(dbrowser.panes.getAttachedPane().id, 'body { color: red !important; }'))
dbrowser.panes.addEventListener('pane-attached', e => {
console.log('pane attached')
setDisabled(false)
})
dbrowser.panes.addEventListener('pane-detached', e => {
console.log('pane detached')
setDisabled(true)
})
dbrowser.panes.addEventListener('pane-navigated', e => {
console.log('pane has changed url', e.detail.url)
})
</script>
</body>
</html>
Edit this page