W3C home > Mailing lists > Public > whatwg@whatwg.org > December 2010

[whatwg] Proposal for a tab visibility API

From: Maciej Stachowiak <mjs@apple.com>
Date: Wed, 08 Dec 2010 22:48:49 -0800
Message-ID: <561A8D0C-6AFB-4386-A947-D00E42C804ED@apple.com>

On Dec 8, 2010, at 11:47 AM, Alex Komoroske wrote:

> Hi all,
> On the Chromium team we?ve identified a couple of use cases that we?d like to address with a simple API, and we?d love your feedback.
> In particular, there is currently no good way for a web page to detect that it is a background tab and is thus completely invisible to the user, although some heuristics do exist (like detecting mousemove events).  In the future, there may be cases where such detection is even more important, for example in the prerendering feature (http://code.google.com/p/chromium/issues/detail?id=61745)  that Chromium is currently in the early stages of experimentation with.
> ==Use cases==
> * A streaming video site doesn?t want to start the video until the user actually views the tab for the first time (i.e. video shouldn?t start automatically if a user opens the tab in the background).

This use case can be handled without help from the page. In Safari, video (whether through media elements or plugins) won't start playing when a user opens a tab in the background, until the user switches to that tab.

> * A page wants to detect when it is moving into or out of the back-forward cache.

This use case is already handled with events specific to the back/forward cache (pagehide and pageshow).

That leaves the following use cases:

> * A puzzle game has a timer that keeps track of how long the user has taken to solve the puzzle.  It wants to pause the timer when the user has hidden the tab.
> * A web app that uses polling to fetch dynamic content can pause polling when it knows the page is hidden from the user.
> * A page wants to detect when it is being prerendered so it can behave appropriately.

I am not sure what the third needs exactly, but it seems like first two could be better served with an API that sets a timer which will only fire when the page is visible. That kind of API might be easier to use right, and avoids the need for JS to run when switching tabs, just to cancel and restart timers.

Also I wonder if pagehide and pageshow could be broadened to help the prerendering use case. It seems a bit speculative to make API just so Web pages can find out about an experimental feature being used.


> With these use-cases in mind, there are a number of requirements.
> ==Requirements==
> * Easy for developers to write scripts that fall back on old behaviors for browsers that do not implement this API
> * Ability to query the document?s current visibility state
> * Events fired when the document transitions between visibility states
> * Ability for browser vendors to add new visibility states in the future
> ==Strawman API==
> What follows is a proposed API that fits the requirements.  Note that another route would be to attempt a mostly-compatible extension of Mozilla?s existing pageshow and pagehide events, which would not necessarily be perfectly backwards compatible.
> =document.visibility=
> A read-only property that returns a string, one of:
> * ?visible? : the tab is focused in its window
> * ?hidden? : the tab is backgrounded within its window
> * ?prerender? : the tab is currently being loaded in an off-screen tab, and may never be shown to the user.
> * ?cache? : the tab is currently in the back-forward-cache.  Note that in Mozilla?s current implementation, document.visibility would never actually be ?cache? because Javascript cannot execute when in the cache.
> In the future, the list of possible values may be extended.  Of these states in this list, all except ?visible? are considered to be hidden.  Developers can use the existence of this property to know that they can rely on the rest of this API, too.
> =document.isVisible=
> A simple convenience read-only property that returns a boolean. Returns true if document.visibility?s current value is in the set of visibility states considered to be visible (for the first iteration of this API, that would only include the ?visible? state).
> =visibilitychanged=
> A simple event, fired at the document object immediately after document.visibility transitions between visibility states.  The event has a property, fromState, that is set to the value of document.visibility just before it was changed to the current value.  Note that visibility has nothing to do with whether the document?s contents have fully loaded or not, which implies that for any given visibility transition event, onload may or may not have already fired.
> Thoughts or comments are welcome.
> --Alex Komoroske

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.whatwg.org/pipermail/whatwg-whatwg.org/attachments/20101208/124f95a2/attachment.htm>
Received on Wednesday, 8 December 2010 22:48:49 UTC

This archive was generated by hypermail 2.4.0 : Wednesday, 22 January 2020 16:59:28 UTC