[PageVisibility] Feedback on example in the Page Visibility editor's draft April 27, 2011

Permalink to the version of this draft:
http://dvcs.w3.org/hg/webperf/raw-file/c46bff617f9e/specs/PageVisibility/Overview.html

The example given in the introduction is poorly chosen and has a number of
issues.  While this section is non-normative I think it's important to
carefully consider the examples we provide as they are often the first
exposure people have to a new API and they serve as a reference for best
practices using the API.  Examples are also a good way to demonstrate that
useful use cases are addressed by the API.

The first and largest problem with the example is that it suggests that
animations should be driven by the page visibility API.  I think this is the
wrong API to use for animations and we've already agreed to work on a
different API specifically to solve the animation use case.  Having an
animation example in the page visibility API is confusing and misleading to
authors.  I suggest that an example is chosen with a better use case for the
page visibility API (I'm not sure what a better such use case is, but that's
another issue).

The second issue is that the example assumes the page is always visible at
load, which isn't always the case - for example if the page is loaded in a
background tab it will not be visible at load time.  In fact, if the page is
not visible on load but then later becomes visible, the visibilityChanged()
listener will clobber the 'timer' variable and set a second setInterval() so
the "draw()" function will be called twice every 16 milliseconds.

Finally the example code does not follow web best practices.  Since the
example text represents an entire document it should have a <!DOCTYPE html>
declaration.  The type="text/javascript" attribute on the <script> tags is
useless and should be omitted.  The calls to setInterval() should not use a
string as the first parameter, they should directly reference the draw
function.  The timer management is a bit sloppy for lack of a better word
and leaks the interval id.  The use of { } and newlines for blocks is
inconsistent.

- James

Received on Thursday, 28 April 2011 22:15:06 UTC