browsertab

BrowserTab

Building Javascript applications that run across multiple browser tabs can be tricky:

• Which browser tab is visible (if any)? You may want to do less work if you know that your current tab is not visible anyway.
• Which browser tab is primary? You may not want all tabs to process a server side event at the same time. For example, you would not want all of your tabs to generate a "new message" alert or sound.

BrowserTab encapsulates all of this behavior into a simple API:

• BrowserTab.hidden() true when the current tab is hidden from the visitor
• BrowserTab.primary() true when the current tab is the most-recently-used tab

Usage

In the browser, just include the module with <script src="browsertab.js"></script>. Then you should be able to use the global BrowserTab object:

if (BrowserTab.hidden()) {
  // This tab is not visible, maybe you can stop requesting data from the server
}

if (BrowserTab.primary()) {
  // This tab is primary, should be okay to trigger things like sounds from this one
}

You can also listen for changes to hidden/primary state:

BrowserTab.on("change:hidden", function() {
  // This tab changed from visible to hidden, or vice-versa.
});

BrowserTab.on("change:primary", function() {
  // This tab changed from primary to non-primary, or vice-versa.
});

Advanced Usage

You can use BrowserTab in node:

• Install the module using npm install browsertab
• At the top of your code, var BrowserTab = require("browsertab")
• Create a new BrowserTab object, for example: var tab = new BrowserTab({window: jsdom().createWindow()})

In general, you can inject all of the BrowserTab dependencies using the options:

var tab = new BrowserTab({
  window: window, // override window (helpful when mocking in unit tests)
  document: document, // override document (helpful when mocking in unit tests)
  localStorage: localStorage, // override localStorage (helpful when mocking in unit tests)
  storageNamespace: "_BrowserTabStorageNamespace" // change storage namespace for coordinating "primary" tab
})

Contributing

Found a bug? Have a new idea? Fork away and send us a pull request! Or call us, maybe?