Add some more info on the event page docs to explain how to switch from

Add some more info on the event page docs to explain how to switch from
background pages.

BUG=120972
TEST=no

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=148234

[Aaron Boodman, 2012-07-23 20:35:37]

http://codereview.chromium.org/10800064/diff/1/chrome/common/extensions/docs/...
File chrome/common/extensions/docs/extensions/event_pages.html (right):

http://codereview.chromium.org/10800064/diff/1/chrome/common/extensions/docs/...
chrome/common/extensions/docs/extensions/event_pages.html:275: <h2
id="transition">Making the switch from a Background Page</h2>
I think it would be more confidence inspiring if this was phrased as a series of
steps, rather than 'some tips'. Can it be something like:

1) Set the 'persistent:false' bit
2) Register to receive any events your extension is interested in each time the
event page is loaded. The event page will be loaded once for each new version of
your extension. After that it will only be loaded to deliver events.
3) If your extension stores information in memory across a browser session that
can't be reconstructed from persistent storage, move that information into
storage using the _storage_ API or _indexed db_. You can use the onSuspend event
for this, but we recommend persisting periodically instead. That way if your
extension crashes without receiving onSuspend, no data will typically be lost.
4) If your extension uses chrome.extension.getBackgroundPage(), switch to
chrome.runtime.getBackgroundPage().
5) If your extension uses setTimeout() or setInterval(), change to using the
_alarms_ API instead. DOM-based timers won't be honored if the event page shuts
down.


... etc ..

[mkearney, 2012-07-23 20:49:14]

Working off of Aaron's review comments:
-- Rename section to be Convert background page to event page
-- For each step in the conversion process, include an example.

What about adding a section on using the 'View Background Pages' to test?

On Mon, Jul 23, 2012 at 1:35 PM, <aa@chromium.org> wrote:

>
> http://codereview.chromium.**org/10800064/diff/1/chrome/**
>
common/extensions/docs/**extensions/event_pages.html<http://codereview.chromium.org/10800064/diff/1/chrome/common/extensions/docs/extensions/event_pages.html>
> File chrome/common/extensions/docs/**extensions/event_pages.html (right):
>
> http://codereview.chromium.**org/10800064/diff/1/chrome/**
>
common/extensions/docs/**extensions/event_pages.html#**newcode275<http://codereview.chromium.org/10800064/diff/1/chrome/common/extensions/docs/extensions/event_pages.html#newcode275>
> chrome/common/extensions/docs/**extensions/event_pages.html:**275: <h2
> id="transition">Making the switch from a Background Page</h2>
> I think it would be more confidence inspiring if this was phrased as a
> series of steps, rather than 'some tips'. Can it be something like:
>
> 1) Set the 'persistent:false' bit
> 2) Register to receive any events your extension is interested in each
> time the event page is loaded. The event page will be loaded once for
> each new version of your extension. After that it will only be loaded to
> deliver events.
> 3) If your extension stores information in memory across a browser
> session that can't be reconstructed from persistent storage, move that
> information into storage using the _storage_ API or _indexed db_. You
> can use the onSuspend event for this, but we recommend persisting
> periodically instead. That way if your extension crashes without
> receiving onSuspend, no data will typically be lost.
> 4) If your extension uses chrome.extension.**getBackgroundPage(), switch
> to chrome.runtime.**getBackgroundPage().
> 5) If your extension uses setTimeout() or setInterval(), change to using
> the _alarms_ API instead. DOM-based timers won't be honored if the event
> page shuts down.
>
>
> ... etc ..
>
>
http://codereview.chromium.**org/10800064/<http://codereview.chromium.org/108...
>

[Matt Perry, 2012-07-23 22:50:16]

OK, new version is up. I found it hard to come up with examples for each point,
so I left those out for now.

> What about adding a section on using the 'View Background Pages' to test?

I don't understand this part.

[mkearney, 2012-07-23 23:06:49]

On Mon, Jul 23, 2012 at 3:50 PM, <mpcomplete@chromium.org> wrote:

> OK, new version is up. I found it hard to come up with examples for each
> point,
> so I left those out for now.
>
>
>  What about adding a section on using the 'View Background Pages' to test?
>>
>
> I don't understand this part.
>
>
http://codereview.chromium.**org/10800064/<http://codereview.chromium.org/108...
>

OK, let me explain in a different way. I think we should add something to
this doc on viewing background/event page behavior in the task manager.

Developers can see the behavior of persistent background pages and
transient event pages by selecting the wrench icon and choosing View
Background Pages. This is a very handy way to see the performance
improvements that you get by using event pages. It is also possible to use
the task manager to see how an event page behaves (what causes it to load,
unload, and how long it stays live).

[Aaron Boodman, 2012-07-23 23:07:29]

lgtm w/ nits

It might be good to have a little lifecycle diagram on event_page.html, too.

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
File chrome/common/extensions/docs/static/event_pages.html (right):

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
chrome/common/extensions/docs/static/event_pages.html:80: loaded to deliver
events.
.append(" you have registered for") ?

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
chrome/common/extensions/docs/static/event_pages.html:94: <li>If you need to
keep runtime state in memory throughout a browser
Makes more sense if this point goes before the previous one.

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
chrome/common/extensions/docs/static/event_pages.html:108: instead.
.append(" The newer method is asynchronous so that it can start the background
page if necessary before returning it.");

[Matt Perry, 2012-07-24 00:11:02]

OK, I added a paragraph on using "View Background Pages".

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
File chrome/common/extensions/docs/static/event_pages.html (right):

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
chrome/common/extensions/docs/static/event_pages.html:80: loaded to deliver
events.
On 2012/07/23 23:07:29, Aaron Boodman wrote:
> .append(" you have registered for") ?

Done.

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
chrome/common/extensions/docs/static/event_pages.html:94: <li>If you need to
keep runtime state in memory throughout a browser
On 2012/07/23 23:07:29, Aaron Boodman wrote:
> Makes more sense if this point goes before the previous one.

Done.

http://codereview.chromium.org/10800064/diff/1003/chrome/common/extensions/do...
chrome/common/extensions/docs/static/event_pages.html:108: instead.
On 2012/07/23 23:07:29, Aaron Boodman wrote:
> .append(" The newer method is asynchronous so that it can start the background
> page if necessary before returning it.");

Done.

[Aaron Boodman, 2012-07-24 21:48:22]

lgtm

[mkearney1, 2012-07-24 21:57:20]

lgtm