chrome app webview event definitions and order

Question

I'm developing a Chrome App that includes a webview tag to display web content.

I'm having trouble understanding when the contentload, loadcommit, and loadstop events actually fire during the process of loading a page in the webview.

1) Can someone please describe (in better detail and context than the documentation) when I can expect these events to fire?
2) Also, what happens when/if I change the webview's src (url)? Will the events fire differently than on the initial load of the webview (or at all) or will it be the same as the first page's load?

https://developer.chrome.com/apps/tags/webview

Answer 1

UPDATE: A loadstop event occurs every time the number of committed frame-level loads transitions from non-zero to zero. In practice, this is often one-per-loadcommit. See updated response for details.

The loadcommit, contentload, and loadstop events you observe from navigating within the webview (e.g., clicking a link) and setting the webview.src attribute are roughly the same, though both depend on whether the new URL refers to the currently loaded document. These events depend on the difference between a browser navigation and a genuine document load. Note that, in the context of your question, the "browser" is the webview.

Summary

• A loadcommit event fires for every browser navigation within the top-level document (loadcommit.isTopLevel=true), as well as within any frame/iframe (loadcommit.isTopLevel=false).

• A loadstop event fires every time the number of frame-level loads (in the top-level frame or an inner frame/iframe) transitions from non-zero to zero. When frames are loaded dynamically (as is often the case for ads) this roughly equates to once-per-loadcommit.

• A contentload event fires (usually before its associated loadstop event) for every top-level document load; this excludes frame/iframe document loads and top-level browser navigation that does not load a new document.

Details

It is entirely possible for your browser to navigate to a new location without loading a new document. Examples include clicking a link that jumps to a location in the current document, and an AJAX workflow wherein the developer uses a browser history API to force navigation when some asynchronously fetched content loads. Of course, most browser navigation does cause the browser to load a new document; this constitutes what I refer to as a genuine document load.

A loadcommit event occur for every browser navigation. These events are fired for each navigation in the top-level document, as well as each frame/iframe in the document (and frames/iframes within frames/iframes, etc.) This is why, in many cases, you will see several loadcommit events to load a single top-level document. Note that only top-level loadcommit events have isTopLevel=true; this also applies to loadabort, loadredirect, and loadstart events, but not loadstop events.

A loadstop event fires every time the number of frame-level loads (in the top-level frame or an inner frame/iframe) transitions from non-zero to zero. When frames are loaded dynamically (as is often the case for ads) this roughly equates to once-per-loadcommit. However, if frames are not loaded dynamically, then usually there will only be one loadstop event for the page.

A contentload event is fired when a top-level document load completes. This means that a contentload event will not accompany a loadcommit event when:

• The loadcommit event does not apply to the top-level frame,

  or

• The loadcommit event is associated with a browser navigation that does not constitute a genuine page load.

As such, listening to contentload is generally suitable for actions that should occur exactly once per top-level document load (e.g., injecting a script exactly once into certain documents). Listening to loadcommit is suitable for reacting to "browser is about to navigate" (be sure to check isTopLevel if you wish to ignore inner frames/iframes). Listening to loadstop is suitable for reacting to "browser finished navigating", but be careful if you're interested in top-level events, because the isTopLevel property doesn't appear in loadstop events.

NOTE: The examples below dynamically load their frames. As such, it is usually the case that one loadstop appears for every loadcommit, but this is not guaranteed, because if a second inner frame load is committed before the first one completes, only one loadstop will fire after both have finished.

Example 1

Action

Load http://www.google.com.

Result

loadcommit.isTopLevel=true, contentload, loadstop

Explanation

This constitutes loading a page with no additional frames/iframes. The document is ready before the loadstop event fires. This appears to be the case in general, but I don't know whether it is guaranteed.

Example 2

Action

From http://www.google.com, type in a search phrase and wait for "instant search" to load search results.

Result

loadcommit.isTopLevel=true, loadstop

Explanation

This constitutes a page navigation without loading a new document. Notice that the anchor portion of the URL is what changes.

Example 3

Action

Load http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_iframe.

Result

loadcommit.isTopLevel=true, [ several loadcommit.isTopLevel=false, one contentload, and several loadstop -- not necessarily in that order ]

Explanation

This constitutes loading a document with several inner frames (there are ads in addition to the sample iframe). You will observe that the number of loadstop events fired never exceeds the number of loadcommit events (because you can't finish loading before starting to load). Again, you will almost certainly see that contentload event is fired before at least one of the loadstop events is fired.