up

1-js/13-modules/01-modules-intro/article.md

@@ -226,7 +226,7 @@ You may want skip those for now if you're reading for the first time, or if you
 
 ### Module scripts are deferred
 
-Module scripts are *always* deferred, same effect as `defer` attribute (described in the chapter [](info:onload-ondomcontentloaded)), for both external and inline scripts.
+Module scripts are *always* deferred, same effect as `defer` attribute (described in the chapter [](info:script-async-defer)), for both external and inline scripts.
 
 In other words:
 - external module scripts `<script type="module" src="...">` don't block HTML processing.

2-ui/3-event-details/10-onload-ondomcontentloaded/article.md → 2-ui/10-loading/01-onload-ondomcontentloaded/article.md

@@ -1,4 +1,4 @@
-# Page lifecycle: DOMContentLoaded, load, beforeunload, unload
+# Page: DOMContentLoaded, load, beforeunload, unload
 
 The lifecycle of an HTML page has three important events:
 
@@ -10,7 +10,8 @@ Each event may be useful:
 
 - `DOMContentLoaded` event -- DOM is ready, so the handler can lookup DOM nodes, initialize the interface.
 - `load` event -- additional resources are loaded, we can get image sizes (if not specified in HTML/CSS) etc.
-- `beforeunload/unload` event -- the user is leaving: we can check if the user saved the changes and ask them whether they really want to leave.
+- `beforeunload` event -- the user is leaving: we can check if the user saved the changes and ask them whether they really want to leave.
+- `unload` -- the user almost left, but we still can initiate some operations, such as sending out statistics.
 
 Let's explore the details of these events.
 
@@ -22,6 +23,7 @@ We must use `addEventListener` to catch it:
 
 ```js
 document.addEventListener("DOMContentLoaded", ready);
+// not "document.onDOMContentLoaded = ..."
 ```
 
 For instance:
@@ -43,40 +45,46 @@ For instance:
 <img id="img" src="https://en.js.cx/clipart/train.gif?speed=1&cache=0">
 ```
 
-In the example the `DOMContentLoaded` handler runs when the document is loaded and does not wait for the image to load. So `alert` shows zero sizes.
+In the example the `DOMContentLoaded` handler runs when the document is loaded, so it can see all the elements, including `<img>` below.
 
-At the first sight `DOMContentLoaded` event is very simple. The DOM tree is ready -- here's the event. But there are few peculiarities.
+But it doesn't wait for the image to load. So `alert` shows zero sizes.
 
-### DOMContentLoaded and scripts
+At the first sight `DOMContentLoaded` event is very simple. The DOM tree is ready -- here's the event. There are few peculiarities though.
 
-When the browser initially loads HTML and comes across a `<script>...</script>` in the text, it can't continue building DOM. It must execute the script right now. So `DOMContentLoaded` may only happen after all such scripts are executed.
+### DOMContentLoaded and scripts
 
-External scripts (with `src`) also put DOM building to pause while the script is loading and executing. So `DOMContentLoaded` waits for external scripts as well.
+When the browser processes an HTML-document and comes across a `<script>` tag, it needs to execute before continuing building the DOM. That's a precaution, as scripts may want to modify DOM, and even `document.write` into it, so `DOMContentLoaded` has to wait.
 
-The only exception are external scripts with `async` and `defer` attributes. They tell the browser to continue processing without waiting for the scripts. This lets the user see the page before scripts finish loading, which is good for performance.
+So DOMContentLoaded definitely happens after such scripts:
 
-### Scripts with `async` and `defer`
+```html run
+<script>
+  document.addEventListener("DOMContentLoaded", () => {
+    console.log("DOM ready!");
+  });
+</script>
 
-Attributes `async` and `defer` work only for external scripts. They are ignored if there's no `src`.
+<script src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.3.0/lodash.js"></script>
 
-Both of them tell the browser that it may go on working with the page, and load the script "in background", then run the script when it loads. So the script doesn't block DOM building and page rendering.
+<script>
+  alert("Library loaded, inline script executed");
+</script>
+```
 
-There are two differences between them.
+In the example above, we first see "Library loaded...", and then "DOM ready!" (all scripts are executed).
 
-|         | `async` | `defer` |
-|---------|---------|---------|
-| Order | Scripts with `async` execute *in the load-first order*. Their document order doesn't matter -- which loads first runs first. | Scripts with `defer` always execute *in the document order* (as they go in the document). |
-| `DOMContentLoaded` | Scripts with `async` may load and execute while the document has not yet been fully downloaded. That happens if scripts are small or cached, and the document is long enough. | Scripts with `defer` execute after the document is loaded and parsed (they wait if needed), right before `DOMContentLoaded`. |
+```warn header="Scripts with `async`, `defer` or `type=\"module\"` don't block DOMContentLoaded"
 
-So `async` is used for independent scripts, like counters or ads, that don't need to access page content. And their relative execution order does not matter.
+Script attributes `async` and `defer`, that we'll cover [a bit later](info:script-async-defer), don't block DOMContentLoaded. [Javascript modules](info:modules) behave like `defer`,  they don't block it too.
 
-While `defer` is used for scripts that need DOM and/or their relative execution order is important.
+So here we're talking about "regular" scripts, like `<script>...</script>`, or `<script src="..."></script>`.
+```
 
 ### DOMContentLoaded and styles
 
-External style sheets don't affect DOM, and so `DOMContentLoaded` does not wait for them.
+External style sheets don't affect DOM, so `DOMContentLoaded` does not wait for them.
 
-But there's a pitfall: if we have a script after the style, then that script must wait for the stylesheet to execute:
+But there's a pitfall. Isf we have a script after the style, then that script must wait until the stylesheet loads:
 
 ```html
 <link type="text/css" rel="stylesheet" href="style.css">
@@ -98,7 +106,6 @@ For instance, if the page has a form with login and password, and the browser re
 
 So if `DOMContentLoaded` is postponed by long-loading scripts, then autofill also awaits. You probably saw that on some sites (if you use browser autofill) -- the login/password fields don't get autofilled immediately, but there's a delay till the page fully loads. That's actually the delay until the `DOMContentLoaded` event.
 
-One of minor benefits in using `async` and `defer` for external scripts -- they don't block `DOMContentLoaded` and don't delay browser autofill.
 
 ## window.onload [#window-onload]
 
@@ -123,15 +130,15 @@ The example below correctly shows image sizes, because `window.onload` waits for
 
 When a visitor leaves the page, the `unload` event triggers on `window`. We can do something there that doesn't involve a delay, like closing related popup windows.
 
-This event is a good place to send out analytics.
+The notable exception is sending analytics.
 
-E.g. we have a script that gathers some data about mouse clicks, scrolls, viewed page areas -- the statistics that can help us to see what users want.
+Let's say we gather data about how the page is used: mouse clicks, scrolls, viewed page areas, and so on.
 
-Then `onunload` is the best time to send it out. Regular networking methods such as [fetch](info:fetch-basics) or [XMLHttpRequest](info:xmlhttprequest) don't work well, because we're in the process of leaving the page.
+Naturally, `unload` event is when the user leaves us, and we'd like to save the data on our server.
 
-So, there exist `navigator.sendBeacon(url, data)` method for such needs, described in the specification <https://w3c.github.io/beacon/>.
+There exists a special `navigator.sendBeacon(url, data)` method for such needs, described in the specification <https://w3c.github.io/beacon/>.
 
-It sends the data in background. The transition to another page is not delayed: the browser leaves the page and performs `sendBeacon` in background.
+It sends the data in background. The transition to another page is not delayed: the browser leaves the page, but still performs `sendBeacon`.
 
 Here's how to use it:
 ```js
@@ -148,37 +155,48 @@ window.addEventListener("unload", function() {
 
 When the `sendBeacon` request is finished, the browser probably has already left the document, so there's no way to get server response (which is usually empty for analytics).
 
+There's also a `keepalive` flag for doing such "after-page-left" requests in  [fetch](info:fetch-basics) method for generic network requests. You can find more information in the chapter <info:fetch-api>.
+
+
 If we want to cancel the transition to another page, we can't do it here. But we can use  another event -- `onbeforeunload`.
 
 ## window.onbeforeunload [#window.onbeforeunload]
 
 If a visitor initiated navigation away from the page or tries to close the window, the `beforeunload` handler asks for additional confirmation.
 
-It may return a string with the question. Historically browsers used to show it, but as of now only some of them do. That's because certain webmasters abused this event handler by showing misleading and hackish messages.
+If we cancel the event, the browser may ask the visitor if they are sure.
 
-You can try it by running this code and then reloading the page.
+You can try it by running this code and then reloading the page:
 
 ```js run
 window.onbeforeunload = function() {
-  return "There are unsaved changes. Leave now?";
+  return false;
 };
 ```
 
-```online
-Or you can click on the button in `<iframe>` below to set the handler, and then click the link:
+For historical reasons, returning a non-empty string also counts as canceling the event. Some time ago browsers used show it as a message, but as the [modern specification](https://html.spec.whatwg.org/#unloading-documents) says, they shouldn't.
+
+Here's an example:
 
-[iframe src="window-onbeforeunload" border="1" height="80" link edit]
+```js run
+window.onbeforeunload = function() {
+  return "There are unsaved changes. Leave now?";
+};
 ```
 
+The behavior was changed, because some webmasters abused this event handler by showing misleading and annoying messages. So right now old browsers still may show it as a message, but aside of that -- there's no way to customize the message shown to the user.
+
 ## readyState
 
 What happens if we set the `DOMContentLoaded` handler after the document is loaded?
 
 Naturally, it never runs.
 
-There are cases when we are not sure whether the document is ready or not, for instance an external script with `async` attribute loads and runs asynchronously. Depending on the network, it may load and execute before the document is complete or after that, we can't be sure. So we should be able to know the current state of the document.
+There are cases when we are not sure whether the document is ready or not. We'd like our function to execute when the DOM is loaded, be it now or later.
+
+The `document.readyState` property tells us about the current loading state.
 
-The `document.readyState` property gives us information about it. There are 3 possible values:
+There are 3 possible values:
 
 - `"loading"` -- the document is loading.
 - `"interactive"` -- the document was fully read.
@@ -192,13 +210,15 @@ Like this:
 function work() { /*...*/ }
 
 if (document.readyState == 'loading') {
+  // loading yet, wait for the event
   document.addEventListener('DOMContentLoaded', work);
 } else {
+  // DOM is ready!
   work();
 }
 ```
 
-There's a `readystatechange` event that triggers when the state changes, so we can print all these states like this:
+There's also `readystatechange` event that triggers when the state changes, so we can print all these states like this:
 
 ```js run
 // current state
@@ -208,15 +228,14 @@ console.log(document.readyState);
 document.addEventListener('readystatechange', () => console.log(document.readyState));
 ```
 
-The `readystatechange` event is an alternative mechanics of tracking the document loading state, it appeared long ago. Nowadays, it is rarely used, but let's cover it for completeness.
+The `readystatechange` event is an alternative mechanics of tracking the document loading state, it appeared long ago. Nowadays, it is rarely used.
 
-What is the place of `readystatechange` among other events?
+Let's see the full events flow for the completeness.
 
-To see the timing, here's a document with `<iframe>`, `<img>` and handlers that log events:
+Here's a document with `<iframe>`, `<img>` and handlers that log events:
 
 ```html
 <script>
-  function log(text) { /* output the time and message */ }
   log('initial readyState:' + document.readyState);
 
   document.addEventListener('readystatechange', () => log('readyState:' + document.readyState));
@@ -244,23 +263,22 @@ The typical output:
 6. [4] readyState:complete
 7. [4] window onload
 
-The numbers in square brackets denote the approximate time of when it happens. The real time is a bit greater, but events labeled with the same digit happen approximately at the same time (+- a few ms).
+The numbers in square brackets denote the approximate time of when it happens. Events labeled with the same digit happen approximately at the same time (+- a few ms).
 
-- `document.readyState` becomes `interactive` right before `DOMContentLoaded`. These two events actually mean the same.
+- `document.readyState` becomes `interactive` right before `DOMContentLoaded`. These two things actually mean the same.
 - `document.readyState` becomes `complete` when all resources (`iframe` and `img`) are loaded. Here we can see that it happens in about the same time as `img.onload` (`img` is the last resource) and `window.onload`. Switching to `complete` state means the same as `window.onload`. The difference is that `window.onload` always works after all other `load` handlers.
 
 
-## Lifecycle events summary
+## Summary
 
-Page lifecycle events:
+Page load events:
 
 - `DOMContentLoaded` event triggers on `document` when DOM is ready. We can apply JavaScript to elements at this stage.
-  - All inline scripts and scripts with `defer` are already executed.
-  - Async scripts may execute both before and after the event, depends on when they load.
+  - Script such as `<script>...</script>` or `<script src="..."></script>` block DOMContentLoaded, the browser waits for them to execute.
   - Images and other resources may also still continue loading.
 - `load` event on `window` triggers when the page and all resources are loaded. We rarely use it, because there's usually no need to wait for so long.
-- `beforeunload` event on `window` triggers when the user wants to leave the page. If it returns a string, the browser shows a question whether the user really wants to leave or not.
-- `unload` event on `window` triggers when the user is finally leaving, in the handler we can only do simple things that do not involve delays or asking a user. Because of that limitation, it's rarely used.
+- `beforeunload` event on `window` triggers when the user wants to leave the page. If we cancel the event, browser asks whether the user really wants to leave (e.g we have unsaved changes).
+- `unload` event on `window` triggers when the user is finally leaving, in the handler we can only do simple things that do not involve delays or asking a user. Because of that limitation, it's rarely used. We can send out a network request with `navigator.sendBeacon`.
 - `document.readyState` is the current state of the document, changes can be tracked in the `readystatechange` event:
   - `loading` -- the document is loading.
   - `interactive` -- the document is parsed, happens at about the same time as `DOMContentLoaded`, but before it.