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

[whatwg] Proposal for a tab visibility API

From: Alex Komoroske <komoroske@chromium.org>
Date: Wed, 8 Dec 2010 11:47:34 -0800
Message-ID: <AANLkTi=HsDhhGuoY+LAvW+OfXKxdvfsJvKUBBGhwZda9@mail.gmail.com>
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 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 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).
* A page wants to detect when it is being prerendered so it can behave
appropriately.
* A page wants to detect when it is moving into or out of the back-forward
cache.


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/cae5a54e/attachment.htm>
Received on Wednesday, 8 December 2010 11:47:34 UTC

This archive was generated by hypermail 2.3.1 : Monday, 13 April 2015 23:09:02 UTC