PR 792

Introduction

PR #792 introduces two new callbacks and modifies the behavior of the existing done callback. This was necessary because the done callback fired at different load time-points depending on if the src/script parameters were given or not. This document describes the new behavior, and how to upgrade code based on the older versions.

Changes

Behavior change: done(errors, window)

done will now always fire with the window's 'loaded' event, after all scripts are finished downloading and executing. This means that you can't set the window.onload = ... or do window.addEventListener('load', ...) in the done callback anymore, since the 'loaded' event was already fired.

The semantics of the arguments did not change. All errors (URL load errors, script errors, etc.) will still be in the errors argument. Note however that loading errors are now presented as an array with one element, instead of as the error object itself.

New callback: created(error, window)

The new created callback is called as soon as the window is created. You may access all window properties here; however, window.document is not ready for use yet, as the HTML has not been parsed.

The primary use-case for created is to modify the window object (e.g. new functions on built-in prototypes) before any scripts execute.

You can also set an event handler for 'load' or other event handlers on the window if you wish. But the loaded callback, below, can be more useful, since it includes errors.

If the error argument is non-null, it will contain whatever loading error caused the window creation to fail; in that case window will not be passed. Note that unlike loaded or done, script errors will not show up here, since when created is called the document's scripts haven't been evaluated yet.

New callback: loaded(errors, window)

The loaded callback, like the done callback, is called along with the window's 'loaded' event. However, loaded (unlike done) will not be called if created was already called with an error. This is to make error handling easier, so you don't have to handle errors in two places. It also allows one to differentiate between loading errors and document script errors, since the former are always passed to created, while the latter are passed to loaded.

Upgrading

• For robust lifecycle control:
  • If you previously added a listener for the 'load' event in the done callback, you will have to remove it, and move it to loaded.
  • If you had other code inside done, move that code to created.
• For the easy use-case where you just want to load a document and use it: just use done. It will be called when the document has fully loaded and all scripts have executed, so there shouldn't be any problems.
• If you want to modify the window before any scripts execute, use created. (This wasn't possible before this pull request.)