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

I agree that we should provide strong examples and supporting context in the introduction sections. In addition to serving as best practices, the introduction is an important opportunity to help the reader understand how the specification originated and provide clear goals for the design. Many specification jump straight to the design without providing this upfront context which I find personally find valuable.

We should have a few examples in the introduction showing how applications can leverage these events to provide a better experience, while at the same time improving performance/power. Including animation as one of the examples doesn't concern me considering developers today use timers/intervals for animation and it's a familiar pattern. It's a good example of the "don't do any work when hidden" scenario.

There's also a "scale back the work you're doing when hidden" scenario. For example, if a web based email client is visible it may check the server for new mail every few seconds. When hidden it might scale back to checking every few minutes.

We should also include a "provide a better user experience" example that's not as much about performance/power. For example, a puzzle site may give you 20 minutes to complete a stage. It may have a countdown clock on the page. When the browser window becomes hidden that countdown may pause (not just the animation but the actual clock and game logic) and the continue when you make the window visible again.

Another good example would be the "don't charge advertisers for ads that aren't visible" scenario. Today a customer may have several tabs open in the browser with advertisements cycling in all of the tabs. Because the site and advertisement don't know if they're visible they consider these views.

I also expect everyone agrees on the code snippet quality and readability. At this stage the goal was to get a scenario into the document and start the dialog around the scenarios. In the past we've talked through the exact code snippet once everyone agrees on the scenario which I think is an effective model. That way we're not spending cycles debating syntax or debugging code snippets which will never make the final spec. Agree with your feedback though on the code.

Thanks, Jason



From: public-web-perf-request@w3.org [mailto:public-web-perf-request@w3.org] On Behalf Of James Robinson
Sent: Thursday, April 28, 2011 3:15 PM
To: public-web-perf@w3.org
Subject: [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