Browser environment, specs
The JavaScript language was initially created for web browsers. Since then, it has evolved into a language with many uses and platforms. A platform may be a browser, or a web-server or another host, or even a "smart" coffee machine if it can run JavaScript. Each of these provides platform-specific functionality. The JavaScript specification calls that a host environment. A host environment provides its own objects and functions in addition to the language core. Web browsers give a means to control web pages. Node.js provides server-side features, and so on. Here's a bird's-eye view of what we have when JavaScript runs in a web browser: There's a "root" object called window. It has two roles: 1. First, it is a global object for JavaScript code, as described in the chapter <info:global-object>. 2. Second, it represents the "browser window" and provides methods to control it. For instance, we can use it as a global object: And we can use it as a browser window, to show the window height: There are more window-specific methods and properties, which we'll cover later. ## DOM (Document Object Model) The Document Object Model, or DOM for short, represents all page content as objects that can be modified. The document object is the main "entry point" to the page. We can change or create anything on the page using it. For instance: Here, we used document.body.style, but there's much, much more. Properties and methods are described in the specification: DOM Living Standard. ## BOM (Browser Object Model) The Browser Object Model (BOM) represents additional objects provided by the browser (host environment) for working with everything except the document. For instance: - The navigator object provides background information about the browser and the operating system. There are many properties, but the two most widely known are: navigator.userAgent -- about the current browser, and navigator.platform -- about the platform (can help to differentiate between Windows/Linux/Mac etc). - The location object allows us to read the current URL and can redirect the browser to a new one. Here's how we can use the location object: The functions alert/confirm/prompt are also a part of the BOM: they are not directly related to the document, but represent pure browser methods for communicating with the user. ## Summary Talking about standards, we have: DOM specification : Describes the document structure, manipulations, and events, see <https://dom.spec.whatwg.org>. CSSOM specification : Describes stylesheets and style rules, manipulations with them, and their binding to documents, see <https://www.w3.org/TR/cssom-1/>. HTML specification : Describes the HTML language (e.g. tags) and also the BOM (browser object model) -- various browser functions: setTimeout, alert, location and so on, see <https://html.spec.whatwg.org>. It takes the DOM specification and extends it with many additional properties and methods. Additionally, some classes are described separately at <https://spec.whatwg.org/>. Please note these links, as there's so much to learn that it's impossible to cover everything and remember it all. When you'd like to read about a property or a method, the Mozilla manual at <https://developer.mozilla.org/en-US/> is also a nice resource, but the corresponding spec may be better: it's more complex and longer to read, but will make your fundamental knowledge sound and complete. To find something, it's often convenient to use an internet search "WHATWG [term]" or "MDN [term]", e.g <https://google.com?q=whatwg+localstorage>, <https://google.com?q=mdn+localstorage>. Now, we'll get down to learning the DOM, because the document plays the central role in the UI.
DOM tree
The backbone of an HTML document is tags. According to the Document Object Model (DOM), every HTML tag is an object. Nested tags are "children" of the enclosing one. The text inside a tag is an object as well. All these objects are accessible using JavaScript, and we can use them to modify the page. For example, document.body is the object representing the <body> tag. Running this code will make the <body> red for 3 seconds: Here we used style.background to change the background color of document.body, but there are many other properties, such as: - innerHTML -- HTML contents of the node. - offsetWidth -- the node width (in pixels) - ...and so on. Soon we'll learn more ways to manipulate the DOM, but first we need to know about its structure. ## An example of the DOM Let's start with the following simple document: The DOM represents HTML as a tree structure of tags. Here's how it looks: <div class="domtree"></div> <script> let node1 = {"name":"HTML","nodeType":1,"children":[{"name":"HEAD","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"\ "},{"name":"TITLE","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"About elk"}]},{"name":"#text","nodeType":3,"content":"\ "}]},{"name":"#text","nodeType":3,"content":"\ "},{"name":"BODY","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"\ The truth about elk.\ "}]}]} drawHtmlTree(node1, 'div.domtree', 690, 320); </script> Every tree node is an object. Tags are element nodes (or just elements) and form the tree structure: <html> is at the root, then <head> and <body> are its children, etc. The text inside elements forms text nodes, labelled as #text. A text node contains only a string. It may not have children and is always a leaf of the tree. For instance, the <title> tag has the text "About elk". Please note the special characters in text nodes: - a newline: ↵ (in JavaScript known as \ ) - a space: ␣ Spaces and newlines are totally valid characters, like letters and digits. They form text nodes and become a part of the DOM. So, for instance, in the example above the <head> tag contains some spaces before <title>, and that text becomes a #text node (it contains a newline and some spaces only). There are only two top-level exclusions: 1. Spaces and newlines before <head> are ignored for historical reasons. 2. If we put something after </body>, then that is automatically moved inside the body, at the end, as the HTML spec requires that all content must be inside <body>. So there can't be any spaces after </body>. In other cases everything's straightforward -- if there are spaces (just like any character) in the document, then they become text nodes in the DOM, and if we remove them, then there won't be any. Here are no space-only text nodes: <div class="domtree"></div> <script> let node2 = {"name":"HTML","nodeType":1,"children":[{"name":"HEAD","nodeType":1,"children":[{"name":"TITLE","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"About elk"}]}]},{"name":"BODY","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"The truth about elk."}]}]} drawHtmlTree(node2, 'div.domtree', 690, 210); </script> ## Autocorrection If the browser encounters malformed HTML, it automatically corrects it when making the DOM. For instance, the top tag is always <html>. Even if it doesn't exist in the document, it will exist in the DOM, because the browser will create it. The same goes for <body>. As an example, if the HTML file is the single word "Hello", the browser will wrap it into <html> and <body>, and add the required <head>, and the DOM will be: <div class="domtree"></div> <script> let node3 = {"name":"HTML","nodeType":1,"children":[{"name":"HEAD","nodeType":1,"children":[]},{"name":"BODY","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"Hello"}]}]} drawHtmlTree(node3, 'div.domtree', 690, 150); </script> While generating the DOM, browsers automatically process errors in the document, close tags and so on. A document with unclosed tags: ...will become a normal DOM as the browser reads tags and restores the missing parts: <div class="domtree"></div> <script> let node4 = {"name":"HTML","nodeType":1,"children":[{"name":"HEAD","nodeType":1,"children":[]},{"name":"BODY","nodeType":1,"children":[{"name":"P","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"Hello"}]},{"name":"LI","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"Mom"}]},{"name":"LI","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"and"}]},{"name":"LI","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"Dad"}]}]}]} drawHtmlTree(node4, 'div.domtree', 690, 360); </script> <table id="table"><tr><td>1</td></tr></table> ## Other node types There are some other node types besides elements and text nodes. For example, comments: <div class="domtree"></div> <script> let node6 = {"name":"HTML","nodeType":1,"children":[{"name":"HEAD","nodeType":1,"children":[]},{"name":"BODY","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"\ The truth about elk.\ "},{"name":"OL","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"\ "},{"name":"LI","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"An elk is a smart"}]},{"name":"#text","nodeType":3,"content":"\ "},{"name":"#comment","nodeType":8,"content":"comment"},{"name":"#text","nodeType":3,"content":"\ "},{"name":"LI","nodeType":1,"children":[{"name":"#text","nodeType":3,"content":"...and cunning animal!"}]},{"name":"#text","nodeType":3,"content":"\ "}]},{"name":"#text","nodeType":3,"content":"\ \ \ "}]}]}; drawHtmlTree(node6, 'div.domtree', 690, 500); </script> We can see here a new tree node type -- comment node, labeled as #comment, between two text nodes. We may think -- why is a comment added to the DOM? It doesn't affect the visual representation in any way. But there's a rule -- if something's in HTML, then it also must be in the DOM tree. Everything in HTML, even comments, becomes a part of the DOM. Even the <!DOCTYPE...> directive at the very beginning of HTML is also a DOM node. It's in the DOM tree right before <html>. Few people know about that. We are not going to touch that node, we even don't draw it on diagrams, but it's there. The document object that represents the whole document is, formally, a DOM node as well. There are 12 node types. In practice we usually work with 4 of them: 1. document -- the "entry point" into DOM. 2. element nodes -- HTML-tags, the tree building blocks. 3. text nodes -- contain text. 4. comments -- sometimes we can put information there, it won't be shown, but JS can read it from the DOM. ## See it for yourself To see the DOM structure in real-time, try Live DOM Viewer. Just type in the document, and it will show up as a DOM at an instant. Another way to explore the DOM is to use the browser developer tools. Actually, that's what we use when developing. To do so, open the web page elk.html, turn on the browser developer tools and switch to the Elements tab. It should look like this: You can see the DOM, click on elements, see their details and so on. Please note that the DOM structure in developer tools is simplified. Text nodes are shown just as text. And there are no "blank" (space only) text nodes at all. That's fine, because most of the time we are interested in element nodes. Clicking the <span class="devtools" style="background-position:-328px -124px"></span> button in the left-upper corner allows us to choose a node from the webpage using a mouse (or other pointer devices) and "inspect" it (scroll to it in the Elements tab). This works great when we have a huge HTML page (and corresponding huge DOM) and would like to see the place of a particular element in it. Another way to do it would be just right-clicking on a webpage and selecting "Inspect" in the context menu. At the right part of the tools there are the following subtabs: - Styles -- we can see CSS applied to the current element rule by rule, including built-in rules (gray). Almost everything can be edited in-place, including the dimensions/margins/paddings of the box below. - Computed -- to see CSS applied to the element by property: for each property we can see a rule that gives it (including CSS inheritance and such). - Event Listeners -- to see event listeners attached to DOM elements (we'll cover them in the next part of the tutorial). - ...and so on. The best way to study them is to click around. Most values are editable in-place. ## Interaction with console As we work the DOM, we also may want to apply JavaScript to it. Like: get a node and run some code to modify it, to see the result. Here are few tips to travel between the Elements tab and the console. For the start: 1. Select the first <li> in the Elements tab. 2. Press key:Esc -- it will open console right below the Elements tab. Now the last selected element is available as $0, the previously selected is $1 etc. We can run commands on them. For instance, $0.style.background = 'red' makes the selected list item red, like this: That's how to get a node from Elements in Console. There's also a road back. If there's a variable referencing a DOM node, then we can use the command inspect(node) in Console to see it in the Elements pane. Or we can just output the DOM node in the console and explore "in-place", like document.body below: That's for debugging purposes of course. From the next chapter on we'll access and modify DOM using JavaScript. The browser developer tools are a great help in development: we can explore the DOM, try things and see what goes wrong. ## Summary An HTML/XML document is represented inside the browser as the DOM tree. - Tags become element nodes and form the structure. - Text becomes text nodes. - ...etc, everything in HTML has its place in DOM, even comments. We can use developer tools to inspect DOM and modify it manually. Here we covered the basics, the most used and important actions to start with. There's an extensive documentation about Chrome Developer Tools at <https://developers.google.com/web/tools/chrome-devtools>. The best way to learn the tools is to click here and there, read menus: most options are obvious. Later, when you know them in general, read the docs and pick up the rest. DOM nodes have properties and methods that allow us to travel between them, modify them, move around the page, and more. We'll get down to them in the next chapters.
Walking the DOM
The DOM allows us to do anything with elements and their contents, but first we need to reach the corresponding DOM object. All operations on the DOM start with the document object. That's the main "entry point" to DOM. From it we can access any node. Here's a picture of links that allow for travel between DOM nodes: Let's discuss them in more detail. ## On top: documentElement and body The topmost tree nodes are available directly as document properties: <html> = document.documentElement : The topmost document node is document.documentElement. That's the DOM node of the <html> tag. <body> = document.body : Another widely used DOM node is the <body> element -- document.body. <head> = document.head : The <head> tag is available as document.head. <html> <head> <script> alert( "From HEAD: " + document.body ); // null, there's no <body> yet </script> </head> <body> <script> alert( "From BODY: " + document.body ); // HTMLBodyElement, now it exists </script> </body> </html> ## Children: childNodes, firstChild, lastChild There are two terms that we'll use from now on: - Child nodes (or children) -- elements that are direct children. In other words, they are nested exactly in the given one. For instance, <head> and <body> are children of <html> element. - Descendants -- all elements that are nested in the given one, including children, their children and so on. For instance, here <body> has children <div> and <ul> (and few blank text nodes): ...And descendants of <body> are not only direct children <div>, <ul> but also more deeply nested elements, such as <li> (a child of <ul>) and <b> (a child of <li>) -- the entire subtree. The childNodes collection lists all child nodes, including text nodes. The example below shows children of document.body: Please note an interesting detail here. If we run the example above, the last element shown is <script>. In fact, the document has more stuff below, but at the moment of the script execution the browser did not read it yet, so the script doesn't see it. Properties firstChild and lastChild give fast access to the first and last children. They are just shorthands. If there exist child nodes, then the following is always true: There's also a special function elem.hasChildNodes() to check whether there are any child nodes. ### DOM collections As we can see, childNodes looks like an array. But actually it's not an array, but rather a collection -- a special array-like iterable object. There are two important consequences: 1. We can use for..of to iterate over it: ```js for (let node of document.body.childNodes) { alert(node); // shows all nodes from the collection ``` That's because it's iterable (provides the Symbol.iterator property, as required). 2. Array methods won't work, because it's not an array: ```js run alert(document.body.childNodes.filter); // undefined (there's no filter method!) ``` The first thing is nice. The second is tolerable, because we can use Array.from to create a "real" array from the collection, if we want array methods: ```js run alert( Array.from(document.body.childNodes).filter ); // function ``` <body> <script> // shows 0, 1, length, item, values and more. for (let prop in document.body.childNodes) alert(prop); </script> </body> <html> <head>...</head><body>...</body> </html> // parent of <body> is <html> alert( document.body.parentNode === document.documentElement ); // true // after <head> goes <body> alert( document.head.nextSibling ); // HTMLBodyElement // before <body> goes <head> alert( document.body.previousSibling ); // HTMLHeadElement The parentElement property returns the "element" parent, while parentNode returns "any node" parent. These properties are usually the same: they both get the parent. With the one exception of document.documentElement: The reason is that the root node document.documentElement (<html>) has document as its parent. But document is not an element node, so parentNode returns it and parentElement does not. This detail may be useful when we want to travel up from an arbitrary element elem to <html>, but not to the document: <html> <body> <div>Begin</div> <ul> <li>Information</li> </ul> <div>End</div> <script> for (let elem of document.body.children) { alert(elem); // DIV, UL, DIV, SCRIPT </script> ... </body> </html> <table id="table"> <tr> <td>one</td><td>two</td> </tr> <tr> <td>three</td><td>four</td> </tr> </table> <script> // get td with "two" (first row, second column) let td = table.!rows[0].cells[1]/!; td.style.backgroundColor = "red"; // highlight it </script>
Searching: getElement*, querySelector*
DOM navigation properties are great when elements are close to each other. What if they are not? How to get an arbitrary element of the page? There are additional searching methods for that. ## document.getElementById or just id If an element has the id attribute, we can get the element using the method document.getElementById(id), no matter where it is. For instance: Also, there's a global variable named by id that references the element: ...That's unless we declare a JavaScript variable with the same name, then it takes precedence: ## querySelectorAll [#querySelectorAll] By far, the most versatile method, elem.querySelectorAll(css) returns all elements inside elem matching the given CSS selector. Here we look for all <li> elements that are last children: This method is indeed powerful, because any CSS selector can be used. ## querySelector [#querySelector] The call to elem.querySelector(css) returns the first element for the given CSS selector. In other words, the result is the same as elem.querySelectorAll(css)[0], but the latter is looking for all elements and picking one, while elem.querySelector just looks for one. So it's faster and also shorter to write. ## matches Previous methods were searching the DOM. The elem.matches(css) does not look for anything, it merely checks if elem matches the given CSS-selector. It returns true or false. The method comes in handy when we are iterating over elements (like in an array or something) and trying to filter out those that interest us. For instance: ## closest Ancestors of an element are: parent, the parent of parent, its parent and so on. The ancestors together form the chain of parents from the element to the top. The method elem.closest(css) looks for the nearest ancestor that matches the CSS-selector. The elem itself is also included in the search. In other words, the method closest goes up from the element and checks each of parents. If it matches the selector, then the search stops, and the ancestor is returned. For instance: ## getElementsBy* There are also other methods to look for nodes by a tag, class, etc. Today, they are mostly history, as querySelector is more powerful and shorter to write. So here we cover them mainly for completeness, while you can still find them in the old scripts. - elem.getElementsByTagName(tag) looks for elements with the given tag and returns the collection of them. The tag parameter can also be a star "*" for "any tags". - elem.getElementsByClassName(className) returns elements that have the given CSS class. - document.getElementsByName(name) returns elements with the given name attribute, document-wide. Very rarely used. For instance: Let's find all input tags inside the table: // doesn't work document.getElementsByTagName('input').value = 5; // should work (if there's an input) document.getElementsByTagName('input')[0].value = 5; Looking for .article elements: ## Live collections All methods "getElementsBy" return a live* collection. Such collections always reflect the current state of the document and "auto-update" when it changes. In the example below, there are two scripts. 1. The first one creates a reference to the collection of <div>. As of now, its length is 1. 2. The second scripts runs after the browser meets one more <div>, so its length is 2. In contrast, querySelectorAll returns a static collection. It's like a fixed array of elements. If we use it instead, then both scripts output 1: Now we can easily see the difference. The static collection did not increase after the appearance of a new div in the document. ## Summary There are 6 main methods to search for nodes in DOM: <table> <thead> <tr> <td>Method</td> <td>Searches by...</td> <td>Can call on an element?</td> <td>Live?</td> </tr> </thead> <tbody> <tr> <td><code>querySelector</code></td> <td>CSS-selector</td> <td>✔</td> <td>-</td> </tr> <tr> <td><code>querySelectorAll</code></td> <td>CSS-selector</td> <td>✔</td> <td>-</td> </tr> <tr> <td><code>getElementById</code></td> <td><code>id</code></td> <td>-</td> <td>-</td> </tr> <tr> <td><code>getElementsByName</code></td> <td><code>name</code></td> <td>-</td> <td>✔</td> </tr> <tr> <td><code>getElementsByTagName</code></td> <td>tag or <code>'*'</code></td> <td>✔</td> <td>✔</td> </tr> <tr> <td><code>getElementsByClassName</code></td> <td>class</td> <td>✔</td> <td>✔</td> </tr> </tbody> </table> By far the most used are querySelector and querySelectorAll, but getElement(s)By* can be sporadically helpful or found in the old scripts. Besides that: - There is elem.matches(css) to check if elem matches the given CSS selector. - There is elem.closest(css) to look for the nearest ancestor that matches the given CSS-selector. The elem itself is also checked. And let's mention one more method here to check for the child-parent relationship, as it's sometimes useful: - elemA.contains(elemB) returns true if elemB is inside elemA (a descendant of elemA) or when elemA==elemB.
Node properties: type, tag and contents
Let's get a more in-depth look at DOM nodes. In this chapter we'll see more into what they are and learn their most used properties. ## DOM node classes Different DOM nodes may have different properties. For instance, an element node corresponding to tag <a> has link-related properties, and the one corresponding to <input> has input-related properties and so on. Text nodes are not the same as element nodes. But there are also common properties and methods between all of them, because all classes of DOM nodes form a single hierarchy. Each DOM node belongs to the corresponding built-in class. The root of the hierarchy is EventTarget, that is inherited by Node, and other DOM nodes inherit from it. Here's the picture, explanations to follow: The classes are: - EventTarget -- is the root "abstract" class for everything. Objects of that class are never created. It serves as a base, so that all DOM nodes support so-called "events", we'll study them later. - Node -- is also an "abstract" class, serving as a base for DOM nodes. It provides the core tree functionality: parentNode, nextSibling, childNodes and so on (they are getters). Objects of Node class are never created. But there are other classes that inherit from it (and so inherit the Node functionality). - Document, for historical reasons often inherited by HTMLDocument (though the latest spec doesn't dictate it) -- is a document as a whole. The document global object belongs exactly to this class. It serves as an entry point to the DOM. - CharacterData -- an "abstract" class, inherited by: - Text -- the class corresponding to a text inside elements, e.g. Hello in <p>Hello</p>. - Comment -- the class for comments. They are not shown, but each comment becomes a member of DOM. - Element -- is the base class for DOM elements. It provides element-level navigation like nextElementSibling, children and searching methods like getElementsByTagName, querySelector. A browser supports not only HTML, but also XML and SVG. So the Element class serves as a base for more specific classes: SVGElement, XMLElement (we don't need them here) and HTMLElement. - Finally, HTMLElement is the basic class for all HTML elements. We'll work with it most of the time. It is inherited by concrete HTML elements: - HTMLInputElement -- the class for <input> elements, - HTMLBodyElement -- the class for <body> elements, - HTMLAnchorElement -- the class for <a> elements, - ...and so on. There are many other tags with their own classes that may have specific properties and methods, while some elements, such as <span>, <section>, <article> do not have any specific properties, so they are instances of HTMLElement class. So, the full set of properties and methods of a given node comes as the result of the chain of inheritance. For example, let's consider the DOM object for an <input> element. It belongs to HTMLInputElement class. It gets properties and methods as a superposition of (listed in inheritance order): - HTMLInputElement -- this class provides input-specific properties, - HTMLElement -- it provides common HTML element methods (and getters/setters), - Element -- provides generic element methods, - Node -- provides common DOM node properties, - EventTarget -- gives the support for events (to be covered), - ...and finally it inherits from Object, so "plain object" methods like hasOwnProperty are also available. To see the DOM node class name, we can recall that an object usually has the constructor property. It references the class constructor, and constructor.name is its name: ...Or we can just toString it: We also can use instanceof to check the inheritance: As we can see, DOM nodes are regular JavaScript objects. They use prototype-based classes for inheritance. That's also easy to see by outputting an element with console.dir(elem) in a browser. There in the console you can see HTMLElement.prototype, Element.prototype and so on. // Define HTMLInputElement // The colon ":" means that HTMLInputElement inherits from HTMLElement interface HTMLInputElement: HTMLElement { // here go properties and methods of <input> elements // "DOMString" means that the value of a property is a string attribute DOMString accept; attribute DOMString alt; attribute DOMString autocomplete; attribute DOMString value; // boolean value property (true/false) attribute boolean autofocus; ... // now the method: "void" means that the method returns no value void select(); ... ## The "nodeType" property The nodeType property provides one more, "old-fashioned" way to get the "type" of a DOM node. It has a numeric value: - elem.nodeType == 1 for element nodes, - elem.nodeType == 3 for text nodes, - elem.nodeType == 9 for the document object, - there are few other values in the specification. For instance: In modern scripts, we can use instanceof and other class-based tests to see the node type, but sometimes nodeType may be simpler. We can only read nodeType, not change it. ## Tag: nodeName and tagName Given a DOM node, we can read its tag name from nodeName or tagName properties: For instance: Is there any difference between tagName and nodeName? Sure, the difference is reflected in their names, but is indeed a bit subtle. - The tagName property exists only for Element nodes. - The nodeName is defined for any Node: - for elements it means the same as tagName. - for other node types (text, comment, etc.) it has a string with the node type. In other words, tagName is only supported by element nodes (as it originates from Element class), while nodeName can say something about other node types. For instance, let's compare tagName and nodeName for the document and a comment node: If we only deal with elements, then we can use both tagName and nodeName - there's no difference. ## innerHTML: the contents The innerHTML property allows to get the HTML inside the element as a string. We can also modify it. So it's one of the most powerful ways to change the page. The example shows the contents of document.body and then replaces it completely: We can try to insert invalid HTML, the browser will fix our errors: ### Beware: "innerHTML+=" does a full overwrite We can append HTML to an element by using elem.innerHTML+="more html". Like this: But we should be very careful about doing it, because what's going on is not an addition, but a full overwrite. Technically, these two lines do the same: In other words, innerHTML+= does this: 1. The old contents is removed. 2. The new innerHTML is written instead (a concatenation of the old and the new one). As the content is "zeroed-out" and rewritten from the scratch, all images and other resources will be reloaded. In the chatDiv example above the line chatDiv.innerHTML+="How goes?" re-creates the HTML content and reloads smile.gif (hope it's cached). If chatDiv has a lot of other text and images, then the reload becomes clearly visible. There are other side-effects as well. For instance, if the existing text was selected with the mouse, then most browsers will remove the selection upon rewriting innerHTML. And if there was an <input> with a text entered by the visitor, then the text will be removed. And so on. Luckily, there are other ways to add HTML besides innerHTML, and we'll study them soon. ## outerHTML: full HTML of the element The outerHTML property contains the full HTML of the element. That's like innerHTML plus the element itself. Here's an example: Beware: unlike innerHTML, writing to outerHTML does not change the element. Instead, it replaces it in the DOM. Yeah, sounds strange, and strange it is, that's why we make a separate note about it here. Take a look. Consider the example: Looks really odd, right? In the line () we replaced div with <p>A new element</p>. In the outer document (the DOM) we can see the new content instead of the <div>. But, as we can see in line (*), the value of the old div variable hasn't changed! The outerHTML assignment does not modify the DOM element (the object referenced by, in this case, the variable 'div'), but removes it from the DOM and inserts the new HTML in its place. So what happened in div.outerHTML=... is: - div was removed from the document. - Another piece of HTML <p>A new element</p> was inserted in its place. - div still has its old value. The new HTML wasn't saved to any variable. It's so easy to make an error here: modify div.outerHTML and then continue to work with div as if it had the new content in it. But it doesn't. Such thing is correct for innerHTML, but not for outerHTML. We can write to elem.outerHTML, but should keep in mind that it doesn't change the element we're writing to ('elem'). It puts the new HTML in its place instead. We can get references to the new elements by querying the DOM. ## nodeValue/data: text node content The innerHTML property is only valid for element nodes. Other node types, such as text nodes, have their counterpart: nodeValue and data properties. These two are almost the same for practical use, there are only minor specification differences. So we'll use data, because it's shorter. An example of reading the content of a text node and a comment: For text nodes we can imagine a reason to read or modify them, but why comments? Sometimes developers embed information or template instructions into HTML in them, like this: ...Then JavaScript can read it from data property and process embedded instructions. ## textContent: pure text The textContent provides access to the text inside the element: only text, minus all <tags>. For instance: As we can see, only text is returned, as if all <tags> were cut out, but the text in them remained. In practice, reading such text is rarely needed. Writing to textContent is much more useful, because it allows to write text the "safe way". Let's say we have an arbitrary string, for instance entered by a user, and want to show it. - With innerHTML we'll have it inserted "as HTML", with all HTML tags. - With textContent we'll have it inserted "as text", all symbols are treated literally. Compare the two: 1. The first <div> gets the name "as HTML": all tags become tags, so we see the bold name. 2. The second <div> gets the name "as text", so we literally see <b>Winnie-the-Pooh!</b>. In most cases, we expect the text from a user, and want to treat it as text. We don't want unexpected HTML in our site. An assignment to textContent does exactly that. ## The "hidden" property The "hidden" attribute and the DOM property specifies whether the element is visible or not. We can use it in HTML or assign it using JavaScript, like this: Technically, hidden works the same as style="display:none". But it's shorter to write. Here's a blinking element: ## More properties DOM elements also have additional properties, in particular those that depend on the class: - value -- the value for <input>, <select> and <textarea> (HTMLInputElement, HTMLSelectElement...). - href -- the "href" for <a href="..."> (HTMLAnchorElement). - id -- the value of "id" attribute, for all elements (HTMLElement). - ...and much more... For instance: Most standard HTML attributes have the corresponding DOM property, and we can access it like that. If we want to know the full list of supported properties for a given class, we can find them in the specification. For instance, HTMLInputElement is documented at <https://html.spec.whatwg.org/#htmlinputelement>. Or if we'd like to get them fast or are interested in a concrete browser specification -- we can always output the element using console.dir(elem) and read the properties. Or explore "DOM properties" in the Elements tab of the browser developer tools. ## Summary Each DOM node belongs to a certain class. The classes form a hierarchy. The full set of properties and methods come as the result of inheritance. Main DOM node properties are: nodeType : We can use it to see if a node is a text or an element node. It has a numeric value: 1 for elements,3 for text nodes, and a few others for other node types. Read-only. nodeName/tagName : For elements, tag name (uppercased unless XML-mode). For non-element nodes nodeName describes what it is. Read-only. innerHTML : The HTML content of the element. Can be modified. outerHTML : The full HTML of the element. A write operation into elem.outerHTML does not touch elem itself. Instead it gets replaced with the new HTML in the outer context. nodeValue/data : The content of a non-element node (text, comment). These two are almost the same, usually we use data. Can be modified. textContent : The text inside the element: HTML minus all <tags>. Writing into it puts the text inside the element, with all special characters and tags treated exactly as text. Can safely insert user-generated text and protect from unwanted HTML insertions. hidden : When set to true, does the same as CSS display:none. DOM nodes also have other properties depending on their class. For instance, <input> elements (HTMLInputElement) support value, type, while <a> elements (HTMLAnchorElement) support href etc. Most standard HTML attributes have a corresponding DOM property. However, HTML attributes and DOM properties are not always the same, as we'll see in the next chapter.
Attributes and properties
When the browser loads the page, it "reads" (another word: "parses") the HTML and generates DOM objects from it. For element nodes, most standard HTML attributes automatically become properties of DOM objects. For instance, if the tag is <body id="page">, then the DOM object has body.id="page". But the attribute-property mapping is not one-to-one! In this chapter we'll pay attention to separate these two notions, to see how to work with them, when they are the same, and when they are different. ## DOM properties We've already seen built-in DOM properties. There are a lot. But technically no one limits us, and if there aren't enough, we can add our own. DOM nodes are regular JavaScript objects. We can alter them. For instance, let's create a new property in document.body: We can add a method as well: We can also modify built-in prototypes like Element.prototype and add new methods to all elements: So, DOM properties and methods behave just like those of regular JavaScript objects: - They can have any value. - They are case-sensitive (write elem.nodeType, not elem.NoDeTyPe). ## HTML attributes In HTML, tags may have attributes. When the browser parses the HTML to create DOM objects for tags, it recognizes standard attributes and creates DOM properties from them. So when an element has id or another standard attribute, the corresponding property gets created. But that doesn't happen if the attribute is non-standard. For instance: Please note that a standard attribute for one element can be unknown for another one. For instance, "type" is standard for <input> (HTMLInputElement), but not for <body> (HTMLBodyElement). Standard attributes are described in the specification for the corresponding element class. Here we can see it: So, if an attribute is non-standard, there won't be a DOM-property for it. Is there a way to access such attributes? Sure. All attributes are accessible by using the following methods: - elem.hasAttribute(name) -- checks for existence. - elem.getAttribute(name) -- gets the value. - elem.setAttribute(name, value) -- sets the value. - elem.removeAttribute(name) -- removes the attribute. These methods operate exactly with what's written in HTML. Also one can read all attributes using elem.attributes: a collection of objects that belong to a built-in Attr class, with name and value properties. Here's a demo of reading a non-standard property: HTML attributes have the following features: - Their name is case-insensitive (id is same as ID). - Their values are always strings. Here's an extended demo of working with attributes: Please note: 1. getAttribute('About') -- the first letter is uppercase here, and in HTML it's all lowercase. But that doesn't matter: attribute names are case-insensitive. 2. We can assign anything to an attribute, but it becomes a string. So here we have "123" as the value. 3. All attributes including ones that we set are visible in outerHTML. 4. The attributes collection is iterable and has all the attributes of the element (standard and non-standard) as objects with name and value properties. ## Property-attribute synchronization When a standard attribute changes, the corresponding property is auto-updated, and (with some exceptions) vice versa. In the example below id is modified as an attribute, and we can see the property changed too. And then the same backwards: But there are exclusions, for instance input.value synchronizes only from attribute -> property, but not back: In the example above: - Changing the attribute value updates the property. - But the property change does not affect the attribute. That "feature" may actually come in handy, because the user actions may lead to value changes, and then after them, if we want to recover the "original" value from HTML, it's in the attribute. ## DOM properties are typed DOM properties are not always strings. For instance, the input.checked property (for checkboxes) is a boolean: There are other examples. The style attribute is a string, but the style property is an object: Most properties are strings though. Quite rarely, even if a DOM property type is a string, it may differ from the attribute. For instance, the href DOM property is always a full URL, even if the attribute contains a relative URL or just a #hash. Here's an example: If we need the value of href or any other attribute exactly as written in the HTML, we can use getAttribute. ## Non-standard attributes, dataset When writing HTML, we use a lot of standard attributes. But what about non-standard, custom ones? First, let's see whether they are useful or not? What for? Sometimes non-standard attributes are used to pass custom data from HTML to JavaScript, or to "mark" HTML-elements for JavaScript. Like this: Also they can be used to style an element. For instance, here for the order state the attribute order-state is used: Why would using an attribute be preferable to having classes like .order-state-new, .order-state-pending, .order-state-canceled? Because an attribute is more convenient to manage. The state can be changed as easy as: But there may be a possible problem with custom attributes. What if we use a non-standard attribute for our purposes and later the standard introduces it and makes it do something? The HTML language is alive, it grows, and more attributes appear to suit the needs of developers. There may be unexpected effects in such case. To avoid conflicts, there exist data-* attributes. All attributes starting with "data-" are reserved for programmers' use. They are available in the dataset property. For instance, if an elem has an attribute named "data-about", it's available as elem.dataset.about. Like this: Multiword attributes like data-order-state become camel-cased: dataset.orderState. Here's a rewritten "order state" example: Using data-* attributes is a valid, safe way to pass custom data. Please note that we can not only read, but also modify data-attributes. Then CSS updates the view accordingly: in the example above the last line (*) changes the color to blue. ## Summary - Attributes -- is what's written in HTML. - Properties -- is what's in DOM objects. A small comparison: Methods to work with attributes are: - elem.hasAttribute(name) -- to check for existence. - elem.getAttribute(name) -- to get the value. - elem.setAttribute(name, value) -- to set the value. - elem.removeAttribute(name) -- to remove the attribute. - elem.attributes is a collection of all attributes. For most situations using DOM properties is preferable. We should refer to attributes only when DOM properties do not suit us, when we need exactly attributes, for instance: - We need a non-standard attribute. But if it starts with data-, then we should use dataset. - We want to read the value "as written" in HTML. The value of the DOM property may be different, for instance the href property is always a full URL, and we may want to get the "original" value.
Modifying the document
DOM modification is the key to creating "live" pages. Here we'll see how to create new elements "on the fly" and modify the existing page content. ## Example: show a message Let's demonstrate using an example. We'll add a message on the page that looks nicer than alert. Here's how it will look: That was the HTML example. Now let's create the same div with JavaScript (assuming that the styles are in the HTML/CSS already). ## Creating an element To create DOM nodes, there are two methods: document.createElement(tag) : Creates a new element node with the given tag: ```js let div = document.createElement('div'); ``` document.createTextNode(text) : Creates a new text node with the given text: ```js let textNode = document.createTextNode('Here I am'); ``` Most of the time we need to create element nodes, such as the div for the message. ### Creating the message Creating the message div takes 3 steps: We've created the element. But as of now it's only in a variable named div, not in the page yet. So we can't see it. ## Insertion methods To make the div show up, we need to insert it somewhere into document. For instance, into <body> element, referenced by document.body. There's a special method append for that: document.body.append(div). Here's the full code: Here we called append on document.body, but we can call append method on any other element, to put another element into it. For instance, we can append something to <div> by calling div.append(anotherElement). Here are more insertion methods, they specify different places where to insert: - node.append(...nodes or strings) -- append nodes or strings at the end of node, - node.prepend(...nodes or strings) -- insert nodes or strings at the beginning of node, - node.before(...nodes or strings) –- insert nodes or strings before node, - node.after(...nodes or strings) –- insert nodes or strings after node, - node.replaceWith(...nodes or strings) –- replaces node with the given nodes or strings. Arguments of these methods are an arbitrary list of DOM nodes to insert, or text strings (that become text nodes automatically). Let's see them in action. Here's an example of using these methods to add items to a list and the text before/after it: Here's a visual picture of what the methods do: So the final list will be: As said, these methods can insert multiple nodes and text pieces in a single call. For instance, here a string and an element are inserted: Please note: the text is inserted "as text", not "as HTML", with proper escaping of characters such as <, >. So the final HTML is: In other words, strings are inserted in a safe way, like elem.textContent does it. So, these methods can only be used to insert DOM nodes or text pieces. But what if we'd like to insert an HTML string "as html", with all tags and stuff working, in the same manner as elem.innerHTML does it? ## insertAdjacentHTML/Text/Element For that we can use another, pretty versatile method: elem.insertAdjacentHTML(where, html). The first parameter is a code word, specifying where to insert relative to elem. Must be one of the following: - "beforebegin" -- insert html immediately before elem, - "afterbegin" -- insert html into elem, at the beginning, - "beforeend" -- insert html into elem, at the end, - "afterend" -- insert html immediately after elem. The second parameter is an HTML string, that is inserted "as HTML". For instance: ...Would lead to: That's how we can append arbitrary HTML to the page. Here's the picture of insertion variants: We can easily notice similarities between this and the previous picture. The insertion points are actually the same, but this method inserts HTML. The method has two brothers: - elem.insertAdjacentText(where, text) -- the same syntax, but a string of text is inserted "as text" instead of HTML, - elem.insertAdjacentElement(where, elem) -- the same syntax, but inserts an element. They exist mainly to make the syntax "uniform". In practice, only insertAdjacentHTML is used most of the time. Because for elements and text, we have methods append/prepend/before/after -- they are shorter to write and can insert nodes/text pieces. So here's an alternative variant of showing a message: ## Node removal To remove a node, there's a method node.remove(). Let's make our message disappear after a second: Please note: if we want to move an element to another place -- there's no need to remove it from the old one. All insertion methods automatically remove the node from the old place. For instance, let's swap elements: ## Cloning nodes: cloneNode How to insert one more similar message? We could make a function and put the code there. But the alternative way would be to clone the existing div and modify the text inside it (if needed). Sometimes when we have a big element, that may be faster and simpler. - The call elem.cloneNode(true) creates a "deep" clone of the element -- with all attributes and subelements. If we call elem.cloneNode(false), then the clone is made without child elements. An example of copying the message: ## DocumentFragment [#document-fragment] DocumentFragment is a special DOM node that serves as a wrapper to pass around lists of nodes. We can append other nodes to it, but when we insert it somewhere, then its content is inserted instead. For example, getListContent below generates a fragment with <li> items, that are later inserted into <ul>: Please note, at the last line (*) we append DocumentFragment, but it "blends in", so the resulting structure will be: DocumentFragment is rarely used explicitly. Why append to a special kind of node, if we can return an array of nodes instead? Rewritten example: We mention DocumentFragment mainly because there are some concepts on top of it, like template element, that we'll cover much later. ## Old-school insert/remove methods [old] There are also "old school" DOM manipulation methods, existing for historical reasons. These methods come from really ancient times. Nowadays, there's no reason to use them, as modern methods, such as append, prepend, before, after, remove, replaceWith, are more flexible. The only reason we list these methods here is that you can find them in many old scripts: parentElem.appendChild(node) : Appends node as the last child of parentElem. The following example adds a new <li> to the end of <ol>: ```html run height=100 <ol id="list"> <li>0</li> <li>1</li> <li>2</li> </ol> <script> let newLi = document.createElement('li'); newLi.innerHTML = 'Hello, world!'; list.appendChild(newLi); </script> ``` parentElem.insertBefore(node, nextSibling) : Inserts node before nextSibling into parentElem. The following code inserts a new list item before the second <li>: ```html run height=100 <ol id="list"> <li>0</li> <li>1</li> <li>2</li> </ol> <script> let newLi = document.createElement('li'); newLi.innerHTML = 'Hello, world!'; list.insertBefore(newLi, list.children[1]); </script> ``` To insert newLi as the first element, we can do it like this: ```js list.insertBefore(newLi, list.firstChild); ``` parentElem.replaceChild(node, oldChild) : Replaces oldChild with node among children of parentElem. parentElem.removeChild(node) : Removes node from parentElem (assuming node is its child). The following example removes first <li> from <ol>: ```html run height=100 <ol id="list"> <li>0</li> <li>1</li> <li>2</li> </ol> <script> let li = list.firstElementChild; list.removeChild(li); </script> ``` All these methods return the inserted/removed node. In other words, parentElem.appendChild(node) returns node. But usually the returned value is not used, we just run the method. ## A word about "document.write" There's one more, very ancient method of adding something to a web-page: document.write. The syntax: The call to document.write(html) writes the html into page "right here and now". The html string can be dynamically generated, so it's kind of flexible. We can use JavaScript to create a full-fledged webpage and write it. The method comes from times when there was no DOM, no standards... Really old times. It still lives, because there are scripts using it. In modern scripts we can rarely see it, because of the following important limitation: The call to document.write only works while the page is loading. If we call it afterwards, the existing document content is erased. For instance: So it's kind of unusable at "after loaded" stage, unlike other DOM methods we covered above. That's the downside. There's an upside also. Technically, when document.write is called while the browser is reading ("parsing") incoming HTML, and it writes something, the browser consumes it just as if it were initially there, in the HTML text. So it works blazingly fast, because there's no DOM modification involved. It writes directly into the page text, while the DOM is not yet built. So if we need to add a lot of text into HTML dynamically, and we're at page loading phase, and the speed matters, it may help. But in practice these requirements rarely come together. And usually we can see this method in scripts just because they are old. ## Summary - Methods to create new nodes: - document.createElement(tag) -- creates an element with the given tag, - document.createTextNode(value) -- creates a text node (rarely used), - elem.cloneNode(deep) -- clones the element, if deep==true then with all descendants. - Insertion and removal: - node.append(...nodes or strings) -- insert into node, at the end, - node.prepend(...nodes or strings) -- insert into node, at the beginning, - node.before(...nodes or strings) –- insert right before node, - node.after(...nodes or strings) –- insert right after node, - node.replaceWith(...nodes or strings) –- replace node. - node.remove() –- remove the node. Text strings are inserted "as text". - There are also "old school" methods: - parent.appendChild(node) - parent.insertBefore(node, nextSibling) - parent.removeChild(node) - parent.replaceChild(newElem, node) All these methods return node. - Given some HTML in html, elem.insertAdjacentHTML(where, html) inserts it depending on the value of where: - "beforebegin" -- insert html right before elem, - "afterbegin" -- insert html into elem, at the beginning, - "beforeend" -- insert html into elem, at the end, - "afterend" -- insert html right after elem. Also there are similar methods, elem.insertAdjacentText and elem.insertAdjacentElement, that insert text strings and elements, but they are rarely used. - To append HTML to the page before it has finished loading: - document.write(html) After the page is loaded such a call erases the document. Mostly seen in old scripts.
Styles and classes
Before we get into JavaScript's ways of dealing with styles and classes -- here's an important rule. Hopefully it's obvious enough, but we still have to mention it. There are generally two ways to style an element: 1. Create a class in CSS and add it: <div class="..."> 2. Write properties directly into style: <div style="...">. JavaScript can modify both classes and style properties. We should always prefer CSS classes to style. The latter should only be used if classes "can't handle it". For example, style is acceptable if we calculate coordinates of an element dynamically and want to set them from JavaScript, like this: For other cases, like making the text red, adding a background icon -- describe that in CSS and then add the class (JavaScript can do that). That's more flexible and easier to support. ## className and classList Changing a class is one of the most often used actions in scripts. In the ancient time, there was a limitation in JavaScript: a reserved word like "class" could not be an object property. That limitation does not exist now, but at that time it was impossible to have a "class" property, like elem.class. So for classes the similar-looking property "className" was introduced: the elem.className corresponds to the "class" attribute. For instance: If we assign something to elem.className, it replaces the whole string of classes. Sometimes that's what we need, but often we want to add/remove a single class. There's another property for that: elem.classList. The elem.classList is a special object with methods to add/remove/toggle a single class. For instance: So we can operate both on the full class string using className or on individual classes using classList. What we choose depends on our needs. Methods of classList: - elem.classList.add/remove("class") -- adds/removes the class. - elem.classList.toggle("class") -- adds the class if it doesn't exist, otherwise removes it. - elem.classList.contains("class") -- checks for the given class, returns true/false. Besides, classList is iterable, so we can list all classes with for..of, like this: ## Element style The property elem.style is an object that corresponds to what's written in the "style" attribute. Setting elem.style.width="100px" works the same as if we had in the attribute style a string width:100px. For multi-word property the camelCase is used: For instance: button.style.MozBorderRadius = '5px'; button.style.WebkitBorderRadius = '5px'; ## Resetting the style property Sometimes we want to assign a style property, and later remove it. For instance, to hide an element, we can set elem.style.display = "none". Then later we may want to remove the style.display as if it were not set. Instead of delete elem.style.display we should assign an empty string to it: elem.style.display = "". If we set style.display to an empty string, then the browser applies CSS classes and its built-in styles normally, as if there were no such style.display property at all. Also there is a special method for that, elem.style.removeProperty('style property'). So, We can remove a property like this: <div id="div">Button</div> <script> // we can set special style flags like "important" here div.style.cssText=`color: red !important; background-color: yellow; width: 100px; text-align: center; alert(div.style.cssText); </script> ## Mind the units Don't forget to add CSS units to values. For instance, we should not set elem.style.top to 10, but rather to 10px. Otherwise it wouldn't work: Please note: the browser "unpacks" the property style.margin in the last lines and infers style.marginLeft and style.marginTop from it. ## Computed styles: getComputedStyle So, modifying a style is easy. But how to read it? For instance, we want to know the size, margins, the color of an element. How to do it? The style property operates only on the value of the "style" attribute, without any CSS cascade. So we can't read anything that comes from CSS classes using elem.style. For instance, here style doesn't see the margin: ...But what if we need, say, to increase the margin by 20px? We would want the current value of it. There's another method for that: getComputedStyle. The syntax is: element : Element to read the value for. pseudo : A pseudo-element if required, for instance ::before. An empty string or no argument means the element itself. The result is an object with styles, like elem.style, but now with respect to all CSS classes. For instance: ## Summary To manage classes, there are two DOM properties: - className -- the string value, good to manage the whole set of classes. - classList -- the object with methods add/remove/toggle/contains, good for individual classes. To change the styles: - The style property is an object with camelCased styles. Reading and writing to it has the same meaning as modifying individual properties in the "style" attribute. To see how to apply important and other rare stuff -- there's a list of methods at MDN. - The style.cssText property corresponds to the whole "style" attribute, the full string of styles. To read the resolved styles (with respect to all classes, after all CSS is applied and final values are calculated): - The getComputedStyle(elem, [pseudo]) returns the style-like object with them. Read-only.
Element size and scrolling
There are many JavaScript properties that allow us to read information about element width, height and other geometry features. We often need them when moving or positioning elements in JavaScript. ## Sample element As a sample element to demonstrate properties we'll use the one given below: It has the border, padding and scrolling. The full set of features. There are no margins, as they are not the part of the element itself, and there are no special properties for them. The element looks like this: You can open the document in the sandbox. ## Geometry Here's the overall picture with geometry properties: Values of these properties are technically numbers, but these numbers are "of pixels", so these are pixel measurements. Let's start exploring the properties starting from the outside of the element. ## offsetParent, offsetLeft/Top These properties are rarely needed, but still they are the "most outer" geometry properties, so we'll start with them. The offsetParent is the nearest ancestor that the browser uses for calculating coordinates during rendering. That's the nearest ancestor that is one of the following: 1. CSS-positioned (position is absolute, relative, fixed or sticky), or 2. <td>, <th>, or <table>, or 3. <body>. Properties offsetLeft/offsetTop provide x/y coordinates relative to offsetParent upper-left corner. In the example below the inner <div> has <main> as offsetParent and offsetLeft/offsetTop shifts from its upper-left corner (180): There are several occasions when offsetParent is null: 1. For not shown elements (display:none or not in the document). 2. For <body> and <html>. 3. For elements with position:fixed. ## offsetWidth/Height Now let's move on to the element itself. These two properties are the simplest ones. They provide the "outer" width/height of the element. Or, in other words, its full size including borders. For our sample element: - offsetWidth = 390 -- the outer width, can be calculated as inner CSS-width (300px) plus paddings (2 20px) and borders (2 25px). - offsetHeight = 290 -- the outer height. function isHidden(elem) { return !elem.offsetWidth && !elem.offsetHeight; ## clientTop/Left Inside the element we have the borders. To measure them, there are properties clientTop and clientLeft. In our example: - clientLeft = 25 -- left border width - clientTop = 25 -- top border width ...But to be precise -- these properties are not border width/height, but rather relative coordinates of the inner side from the outer side. What's the difference? It becomes visible when the document is right-to-left (the operating system is in Arabic or Hebrew languages). The scrollbar is then not on the right, but on the left, and then clientLeft also includes the scrollbar width. In that case, clientLeft would be not 25, but with the scrollbar width 25 + 16 = 41. Here's the example in hebrew: ## clientWidth/Height These properties provide the size of the area inside the element borders. They include the content width together with paddings, but without the scrollbar: On the picture above let's first consider clientHeight. There's no horizontal scrollbar, so it's exactly the sum of what's inside the borders: CSS-height 200px plus top and bottom paddings (2 * 20px) total 240px. Now clientWidth -- here the content width is not 300px, but 284px, because 16px are occupied by the scrollbar. So the sum is 284px plus left and right paddings, total 324px. If there are no paddings, then clientWidth/Height is exactly the content area, inside the borders and the scrollbar (if any). So when there's no padding we can use clientWidth/clientHeight to get the content area size. ## scrollWidth/Height These properties are like clientWidth/clientHeight, but they also include the scrolled out (hidden) parts: On the picture above: - scrollHeight = 723 -- is the full inner height of the content area including the scrolled out parts. - scrollWidth = 324 -- is the full inner width, here we have no horizontal scroll, so it equals clientWidth. We can use these properties to expand the element wide to its full width/height. Like this: ## scrollLeft/scrollTop Properties scrollLeft/scrollTop are the width/height of the hidden, scrolled out part of the element. On the picture below we can see scrollHeight and scrollTop for a block with a vertical scroll. In other words, scrollTop is "how much is scrolled up". If you click the element below, the code elem.scrollTop += 10 executes. That makes the element content scroll 10px down. <div onclick="this.scrollTop+=10" style="cursor:pointer;border:1px solid black;width:100px;height:80px;overflow:auto">Click<br>Me<br>1<br>2<br>3<br>4<br>5<br>6<br>7<br>8<br>9</div> ## Don't take width/height from CSS We've just covered geometry properties of DOM elements, that can be used to get widths, heights and calculate distances. But as we know from the chapter <info:styles-and-classes>, we can read CSS-height and width using getComputedStyle. So why not to read the width of an element with getComputedStyle, like this? Why should we use geometry properties instead? There are two reasons: 1. First, CSS width/height depend on another property: box-sizing that defines "what is" CSS width and height. A change in box-sizing for CSS purposes may break such JavaScript. 2. Second, CSS width/height may be auto, for instance for an inline element: ```html run <span id="elem">Hello!</span> <script> alert( getComputedStyle(elem).width ); // auto </script> ``` From the CSS standpoint, width:auto is perfectly normal, but in JavaScript we need an exact size in px that we can use in calculations. So here CSS width is useless. And there's one more reason: a scrollbar. Sometimes the code that works fine without a scrollbar becomes buggy with it, because a scrollbar takes the space from the content in some browsers. So the real width available for the content is less than CSS width. And clientWidth/clientHeight take that into account. ...But with getComputedStyle(elem).width the situation is different. Some browsers (e.g. Chrome) return the real inner width, minus the scrollbar, and some of them (e.g. Firefox) -- CSS width (ignore the scrollbar). Such cross-browser differences is the reason not to use getComputedStyle, but rather rely on geometry properties. Please note that the described difference is only about reading getComputedStyle(...).width from JavaScript, visually everything is correct. ## Summary Elements have the following geometry properties: - offsetParent -- is the nearest positioned ancestor or td, th, table, body. - offsetLeft/offsetTop -- coordinates relative to the upper-left edge of offsetParent. - offsetWidth/offsetHeight -- "outer" width/height of an element including borders. - clientLeft/clientTop -- the distances from the upper-left outer corner to the upper-left inner (content + padding) corner. For left-to-right OS they are always the widths of left/top borders. For right-to-left OS the vertical scrollbar is on the left so clientLeft includes its width too. - clientWidth/clientHeight -- the width/height of the content including paddings, but without the scrollbar. - scrollWidth/scrollHeight -- the width/height of the content, just like clientWidth/clientHeight, but also include scrolled-out, invisible part of the element. - scrollLeft/scrollTop -- width/height of the scrolled out upper part of the element, starting from its upper-left corner. All properties are read-only except scrollLeft/scrollTop that make the browser scroll the element if changed.
Window sizes and scrolling
How do we find the width and height of the browser window? How do we get the full width and height of the document, including the scrolled out part? How do we scroll the page using JavaScript? For this type of information, we can use the root document element document.documentElement, that corresponds to the <html> tag. But there are additional methods and peculiarities to consider. ## Width/height of the window To get window width and height, we can use the clientWidth/clientHeight of document.documentElement: alert( window.innerWidth ); // full window width alert( document.documentElement.clientWidth ); // window width minus the scrollbar ## Width/height of the document Theoretically, as the root document element is document.documentElement, and it encloses all the content, we could measure the document's full size as document.documentElement.scrollWidth/scrollHeight. But on that element, for the whole page, these properties do not work as intended. In Chrome/Safari/Opera, if there's no scroll, then documentElement.scrollHeight may be even less than documentElement.clientHeight! Weird, right? To reliably obtain the full document height, we should take the maximum of these properties: Why so? Better don't ask. These inconsistencies come from ancient times, not a "smart" logic. ## Get the current scroll [#page-scroll] DOM elements have their current scroll state in their scrollLeft/scrollTop properties. For document scroll, document.documentElement.scrollLeft/scrollTop works in most browsers, except older WebKit-based ones, like Safari (bug 5991), where we should use document.body instead of document.documentElement. Luckily, we don't have to remember these peculiarities at all, because the scroll is available in the special properties, window.pageXOffset/pageYOffset: These properties are read-only. ## Scrolling: scrollTo, scrollBy, scrollIntoView [#window-scroll] Regular elements can be scrolled by changing scrollTop/scrollLeft. We can do the same for the page using document.documentElement.scrollTop/scrollLeft (except Safari, where document.body.scrollTop/Left should be used instead). Alternatively, there's a simpler, universal solution: special methods window.scrollBy(x,y) and window.scrollTo(pageX,pageY). - The method scrollBy(x,y) scrolls the page relative to its current position. For instance, scrollBy(0,10) scrolls the page 10px down. ```online The button below demonstrates this: <button onclick="window.scrollBy(0,10)">window.scrollBy(0,10)</button> ``` - The method scrollTo(pageX,pageY) scrolls the page to absolute coordinates, so that the top-left corner of the visible part has coordinates (pageX, pageY) relative to the document's top-left corner. It's like setting scrollLeft/scrollTop. To scroll to the very beginning, we can use scrollTo(0,0). ```online <button onclick="window.scrollTo(0,0)">window.scrollTo(0,0)</button> ``` These methods work for all browsers the same way. ## scrollIntoView For completeness, let's cover one more method: elem.scrollIntoView(top). The call to elem.scrollIntoView(top) scrolls the page to make elem visible. It has one argument: - If top=true (that's the default), then the page will be scrolled to make elem appear on the top of the window. The upper edge of the element will be aligned with the window top. - If top=false, then the page scrolls to make elem appear at the bottom. The bottom edge of the element will be aligned with the window bottom. ## Forbid the scrolling Sometimes we need to make the document "unscrollable". For instance, when we need to cover the page with a large message requiring immediate attention, and we want the visitor to interact with that message, not with the document. To make the document unscrollable, it's enough to set document.body.style.overflow = "hidden". The page will "freeze" at its current scroll position. We can use the same technique to freeze the scroll for other elements, not just for document.body. The drawback of the method is that the scrollbar disappears. If it occupied some space, then that space is now free and the content "jumps" to fill it. That looks a bit odd, but can be worked around if we compare clientWidth before and after the freeze. If it increased (the scrollbar disappeared), then add padding to document.body in place of the scrollbar to keep the content width the same. ## Summary Geometry: - Width/height of the visible part of the document (content area width/height): document.documentElement.clientWidth/clientHeight - Width/height of the whole document, with the scrolled out part: ```js let scrollHeight = Math.max( document.body.scrollHeight, document.documentElement.scrollHeight, document.body.offsetHeight, document.documentElement.offsetHeight, document.body.clientHeight, document.documentElement.clientHeight ``` Scrolling: - Read the current scroll: window.pageYOffset/pageXOffset. - Change the current scroll: - window.scrollTo(pageX,pageY) -- absolute coordinates, - window.scrollBy(x,y) -- scroll relative the current place, - elem.scrollIntoView(top) -- scroll to make elem visible (align with the top/bottom of the window).
Coordinates
To move elements around we should be familiar with coordinates. Most JavaScript methods deal with one of two coordinate systems: 1. Relative to the window - similar to position:fixed, calculated from the window top/left edge. - we'll denote these coordinates as clientX/clientY, the reasoning for such name will become clear later, when we study event properties. 2. Relative to the document - similar to position:absolute in the document root, calculated from the document top/left edge. - we'll denote them pageX/pageY. When the page is scrolled to the very beginning, so that the top/left corner of the window is exactly the document top/left corner, these coordinates equal each other. But after the document shifts, window-relative coordinates of elements change, as elements move across the window, while document-relative coordinates remain the same. On this picture we take a point in the document and demonstrate its coordinates before the scroll (left) and after it (right): When the document scrolled: - pageY - document-relative coordinate stayed the same, it's counted from the document top (now scrolled out). - clientY - window-relative coordinate did change (the arrow became shorter), as the same point became closer to window top. ## Element coordinates: getBoundingClientRect The method elem.getBoundingClientRect() returns window coordinates for a minimal rectangle that encloses elem as an object of built-in DOMRect class. Main DOMRect properties: - x/y -- X/Y-coordinates of the rectangle origin relative to window, - width/height -- width/height of the rectangle (can be negative). Additionally, there are derived properties: - top/bottom -- Y-coordinate for the top/bottom rectangle edge, - left/right -- X-coordinate for the left/right rectangle edge. Here's the picture of elem.getBoundingClientRect() output: As you can see, x/y and width/height fully describe the rectangle. Derived properties can be easily calculated from them: - left = x - top = y - right = x + width - bottom = y + height Please note: - Coordinates may be decimal fractions, such as 10.5. That's normal, internally browser uses fractions in calculations. We don't have to round them when setting to style.left/top. - Coordinates may be negative. For instance, if the page is scrolled so that elem is now above the window, then elem.getBoundingClientRect().top is negative. ## elementFromPoint(x, y) [#elementFromPoint] The call to document.elementFromPoint(x, y) returns the most nested element at window coordinates (x, y). The syntax is: For instance, the code below highlights and outputs the tag of the element that is now in the middle of the window: As it uses window coordinates, the element may be different depending on the current scroll position. let elem = document.elementFromPoint(x, y); // if the coordinates happen to be out of the window, then elem = null elem.style.background = ''; // Error! ## Using for "fixed" positioning Most of time we need coordinates in order to position something. To show something near an element, we can use getBoundingClientRect to get its coordinates, and then CSS position together with left/top (or right/bottom). For instance, the function createMessageUnder(elem, html) below shows the message under elem: The code can be modified to show the message at the left, right, below, apply CSS animations to "fade it in" and so on. That's easy, as we have all the coordinates and sizes of the element. But note the important detail: when the page is scrolled, the message flows away from the button. The reason is obvious: the message element relies on position:fixed, so it remains at the same place of the window while the page scrolls away. To change that, we need to use document-based coordinates and position:absolute. ## Document coordinates [#getCoords] Document-relative coordinates start from the upper-left corner of the document, not the window. In CSS, window coordinates correspond to position:fixed, while document coordinates are similar to position:absolute on top. We can use position:absolute and top/left to put something at a certain place of the document, so that it remains there during a page scroll. But we need the right coordinates first. There's no standard method to get the document coordinates of an element. But it's easy to write it. The two coordinate systems are connected by the formula: - pageY = clientY + height of the scrolled-out vertical part of the document. - pageX = clientX + width of the scrolled-out horizontal part of the document. The function getCoords(elem) will take window coordinates from elem.getBoundingClientRect() and add the current scroll to them: If in the example above we used it with position:absolute, then the message would stay near the element on scroll. The modified createMessageUnder function: ## Summary Any point on the page has coordinates: 1. Relative to the window -- elem.getBoundingClientRect(). 2. Relative to the document -- elem.getBoundingClientRect() plus the current page scroll. Window coordinates are great to use with position:fixed, and document coordinates do well with position:absolute. Both coordinate systems have their pros and cons; there are times we need one or the other one, just like CSS position absolute and fixed.
Introduction to browser events
An event is a signal that something has happened. All DOM nodes generate such signals (but events are not limited to DOM). Here's a list of the most useful DOM events, just to take a look at: Mouse events: - click -- when the mouse clicks on an element (touchscreen devices generate it on a tap). - contextmenu -- when the mouse right-clicks on an element. - mouseover / mouseout -- when the mouse cursor comes over / leaves an element. - mousedown / mouseup -- when the mouse button is pressed / released over an element. - mousemove -- when the mouse is moved. Keyboard events: - keydown and keyup -- when a keyboard key is pressed and released. Form element events: - submit -- when the visitor submits a <form>. - focus -- when the visitor focuses on an element, e.g. on an <input>. Document events: - DOMContentLoaded -- when the HTML is loaded and processed, DOM is fully built. CSS events: - transitionend -- when a CSS-animation finishes. There are many other events. We'll get into more details of particular events in upcoming chapters. ## Event handlers To react on events we can assign a handler -- a function that runs in case of an event. Handlers are a way to run JavaScript code in case of user actions. There are several ways to assign a handler. Let's see them, starting from the simplest one. ### HTML-attribute A handler can be set in HTML with an attribute named on<event>. For instance, to assign a click handler for an input, we can use onclick, like here: On mouse click, the code inside onclick runs. Please note that inside onclick we use single quotes, because the attribute itself is in double quotes. If we forget that the code is inside the attribute and use double quotes inside, like this: onclick="alert("Click!")", then it won't work right. An HTML-attribute is not a convenient place to write a lot of code, so we'd better create a JavaScript function and call it there. Here a click runs the function countRabbits(): As we know, HTML attribute names are not case-sensitive, so ONCLICK works as well as onClick and onCLICK... But usually attributes are lowercased: onclick. ### DOM property We can assign a handler using a DOM property on<event>. For instance, elem.onclick: If the handler is assigned using an HTML-attribute then the browser reads it, creates a new function from the attribute content and writes it to the DOM property. So this way is actually the same as the previous one. These two code pieces work the same: 1. Only HTML: ```html autorun height=50 <input type="button" !onclick="alert('Click!')"/! value="Button"> ``` 2. HTML + JS: ```html autorun height=50 <input type="button" id="button" value="Button"> <script> button.onclick = function() { alert('Click!'); </script> ``` In the first example, the HTML attribute is used to initialize the button.onclick, while in the second example -- the script, that's all the difference. As there's only one onclick property, we can't assign more than one event handler. In the example below adding a handler with JavaScript overwrites the existing handler: To remove a handler -- assign elem.onclick = null. ## Accessing the element: this The value of this inside a handler is the element. The one which has the handler on it. In the code below button shows its contents using this.innerHTML: ## Possible mistakes If you're starting to work with events -- please note some subtleties. We can set an existing function as a handler: But be careful: the function should be assigned as sayThanks, not sayThanks(). If we add parentheses, then sayThanks() becomes a function call. So the last line actually takes the result of the function execution, that is undefined (as the function returns nothing), and assigns it to onclick. That doesn't work. ...On the other hand, in the markup we do need the parentheses: The difference is easy to explain. When the browser reads the attribute, it creates a handler function with body from the attribute content. So the markup generates this property: Don't use setAttribute for handlers. Such a call won't work: DOM-property case matters. Assign a handler to elem.onclick, not elem.ONCLICK, because DOM properties are case-sensitive. ## addEventListener The fundamental problem of the aforementioned ways to assign handlers is that we can't assign multiple handlers to one event. Let's say, one part of our code wants to highlight a button on click, and another one wants to show a message on the same click. We'd like to assign two event handlers for that. But a new DOM property will overwrite the existing one: Developers of web standards understood that long ago and suggested an alternative way of managing handlers using the special methods addEventListener and removeEventListener which aren't bound by such constraint. The syntax to add a handler: event : Event name, e.g. "click". handler : The handler function. options : An additional optional object with properties: - once: if true, then the listener is automatically removed after it triggers. - capture: the phase where to handle the event, to be covered later in the chapter <info:bubbling-and-capturing>. For historical reasons, options can also be false/true, that's the same as {capture: false/true}. - passive: if true, then the handler will not call preventDefault(), we'll explain that later in <info:default-browser-action>. To remove the handler, use removeEventListener: elem.addEventListener( "click" , () => alert('Thanks!')); // .... elem.removeEventListener( "click", () => alert('Thanks!')); function handler() { alert( 'Thanks!' ); input.addEventListener("click", handler); // .... input.removeEventListener("click", handler); Multiple calls to addEventListener allow it to add multiple handlers, like this: As we can see in the example above, we can set handlers both using a DOM-property and addEventListener. But generally we use only one of these ways. // will never run document.onDOMContentLoaded = function() { alert("DOM built"); // this way it works document.addEventListener("DOMContentLoaded", function() { alert("DOM built"); }); ## Event object To properly handle an event we'd want to know more about what's happened. Not just a "click" or a "keydown", but what were the pointer coordinates? Which key was pressed? And so on. When an event happens, the browser creates an event object, puts details into it and passes it as an argument to the handler. Here's an example of getting pointer coordinates from the event object: Some properties of event object: event.type : Event type, here it's "click". event.currentTarget : Element that handled the event. That's exactly the same as this, unless the handler is an arrow function, or its this is bound to something else, then we can get the element from event.currentTarget. event.clientX / event.clientY : Window-relative coordinates of the cursor, for pointer events. There are more properties. Many of them depend on the event type: keyboard events have one set of properties, pointer events - another one, we'll study them later when as we move on to the details of different events. <input type="button" onclick="!alert(event.type)/!" value="Event type"> ## Object handlers: handleEvent We can assign not just a function, but an object as an event handler using addEventListener. When an event occurs, its handleEvent method is called. For instance: As we can see, when addEventListener receives an object as the handler, it calls obj.handleEvent(event) in case of an event. We could also use objects of a custom class, like this: Here the same object handles both events. Please note that we need to explicitly setup the events to listen using addEventListener. The menu object only gets mousedown and mouseup here, not any other types of events. The method handleEvent does not have to do all the job by itself. It can call other event-specific methods instead, like this: Now event handlers are clearly separated, that may be easier to support. ## Summary There are 3 ways to assign event handlers: 1. HTML attribute: onclick="...". 2. DOM property: elem.onclick = function. 3. Methods: elem.addEventListener(event, handler[, phase]) to add, removeEventListener to remove. HTML attributes are used sparingly, because JavaScript in the middle of an HTML tag looks a little bit odd and alien. Also can't write lots of code in there. DOM properties are ok to use, but we can't assign more than one handler of the particular event. In many cases that limitation is not pressing. The last way is the most flexible, but it is also the longest to write. There are few events that only work with it, for instance transitionend and DOMContentLoaded (to be covered). Also addEventListener supports objects as event handlers. In that case the method handleEvent is called in case of the event. No matter how you assign the handler -- it gets an event object as the first argument. That object contains the details about what's happened. We'll learn more about events in general and about different types of events in the next chapters.
Bubbling and capturing
Let's start with an example. This handler is assigned to <div>, but also runs if you click any nested tag like <em> or <code>: Isn't it a bit strange? Why does the handler on <div> run if the actual click was on <em>? ## Bubbling The bubbling principle is simple. When an event happens on an element, it first runs the handlers on it, then on its parent, then all the way up on other ancestors. Let's say we have 3 nested elements FORM > DIV > P with a handler on each of them: A click on the inner <p> first runs onclick: 1. On that <p>. 2. Then on the outer <div>. 3. Then on the outer <form>. 4. And so on upwards till the document object. So if we click on <p>, then we'll see 3 alerts: p -> div -> form. The process is called "bubbling", because events "bubble" from the inner element up through parents like a bubble in the water. ## event.target A handler on a parent element can always get the details about where it actually happened. *The most deeply nested element that caused the event is called a target element, accessible as event.target.* Note the differences from this (=event.currentTarget): - event.target -- is the "target" element that initiated the event, it doesn't change through the bubbling process. - this -- is the "current" element, the one that has a currently running handler on it. For instance, if we have a single handler form.onclick, then it can "catch" all clicks inside the form. No matter where the click happened, it bubbles up to <form> and runs the handler. In form.onclick handler: - this (=event.currentTarget) is the <form> element, because the handler runs on it. - event.target is the actual element inside the form that was clicked. Check it out: [codetabs height=220 src="bubble-target"] It's possible that event.target could equal this -- it happens when the click is made directly on the <form> element. ## Stopping bubbling A bubbling event goes from the target element straight up. Normally it goes upwards till <html>, and then to document object, and some events even reach window, calling all handlers on the path. But any handler may decide that the event has been fully processed and stop the bubbling. The method for it is event.stopPropagation(). For instance, here body.onclick doesn't work if you click on <button>: ## Capturing There's another phase of event processing called "capturing". It is rarely used in real code, but sometimes can be useful. The standard DOM Events describes 3 phases of event propagation: 1. Capturing phase -- the event goes down to the element. 2. Target phase -- the event reached the target element. 3. Bubbling phase -- the event bubbles up from the element. Here's the picture, taken from the specification, of the capturing (1), target (2) and bubbling (3) phases for a click event on a <td> inside a table: That is: for a click on <td> the event first goes through the ancestors chain down to the element (capturing phase), then it reaches the target and triggers there (target phase), and then it goes up (bubbling phase), calling handlers on its way. Until now, we only talked about bubbling, because the capturing phase is rarely used. In fact, the capturing phase was invisible for us, because handlers added using on<event>-property or using HTML attributes or using two-argument addEventListener(event, handler) don't know anything about capturing, they only run on the 2nd and 3rd phases. To catch an event on the capturing phase, we need to set the handler capture option to true: There are two possible values of the capture option: - If it's false (default), then the handler is set on the bubbling phase. - If it's true, then the handler is set on the capturing phase. Note that while formally there are 3 phases, the 2nd phase ("target phase": the event reached the element) is not handled separately: handlers on both capturing and bubbling phases trigger at that phase. Let's see both capturing and bubbling in action: The code sets click handlers on every element in the document to see which ones are working. If you click on <p>, then the sequence is: 1. HTML -> BODY -> FORM -> DIV -> P (capturing phase, the first listener): 2. P -> DIV -> FORM -> BODY -> HTML (bubbling phase, the second listener). Please note, the P shows up twice, because we've set two listeners: capturing and bubbling. The target triggers at the end of the first and at the beginning of the second phase. There's a property event.eventPhase that tells us the number of the phase on which the event was caught. But it's rarely used, because we usually know it in the handler. elem.addEventListener("click", e => alert(1)); // guaranteed to trigger first elem.addEventListener("click", e => alert(2)); ## Summary When an event happens -- the most nested element where it happens gets labeled as the "target element" (event.target). - Then the event moves down from the document root to event.target, calling handlers assigned with addEventListener(..., true) on the way (true is a shorthand for {capture: true}). - Then handlers are called on the target element itself. - Then the event bubbles up from event.target to the root, calling handlers assigned using on<event>, HTML attributes and addEventListener without the 3rd argument or with the 3rd argument false/{capture:false}. Each handler can access event object properties: - event.target -- the deepest element that originated the event. - event.currentTarget (=this) -- the current element that handles the event (the one that has the handler on it) - event.eventPhase -- the current phase (capturing=1, target=2, bubbling=3). Any event handler can stop the event by calling event.stopPropagation(), but that's not recommended, because we can't really be sure we won't need it above, maybe for completely different things. The capturing phase is used very rarely, usually we handle events on bubbling. And there's a logical explanation for that. In real world, when an accident happens, local authorities react first. They know best the area where it happened. Then higher-level authorities if needed. The same for event handlers. The code that set the handler on a particular element knows maximum details about the element and what it does. A handler on a particular <td> may be suited for that exactly <td>, it knows everything about it, so it should get the chance first. Then its immediate parent also knows about the context, but a little bit less, and so on till the very top element that handles general concepts and runs the last one. Bubbling and capturing lay the foundation for "event delegation" -- an extremely powerful event handling pattern that we study in the next chapter.
Event delegation
Capturing and bubbling allow us to implement one of the most powerful event handling patterns called event delegation. The idea is that if we have a lot of elements handled in a similar way, then instead of assigning a handler to each of them -- we put a single handler on their common ancestor. In the handler we get event.target to see where the event actually happened and handle it. Let's see an example -- the Ba-Gua diagram reflecting the ancient Chinese philosophy. Here it is: [iframe height=350 src="bagua" edit link] The HTML is like this: The table has 9 cells, but there could be 99 or 9999, doesn't matter. Our task is to highlight a cell <td> on click. Instead of assign an onclick handler to each <td> (can be many) -- we'll setup the "catch-all" handler on <table> element. It will use event.target to get the clicked element and highlight it. The code: Such a code doesn't care how many cells there are in the table. We can add/remove <td> dynamically at any time and the highlighting will still work. Still, there's a drawback. The click may occur not on the <td>, but inside it. In our case if we take a look inside the HTML, we can see nested tags inside <td>, like <strong>: Naturally, if a click happens on that <strong> then it becomes the value of event.target. In the handler table.onclick we should take such event.target and find out whether the click was inside <td> or not. Here's the improved code: Explanations: 1. The method elem.closest(selector) returns the nearest ancestor that matches the selector. In our case we look for <td> on the way up from the source element. 2. If event.target is not inside any <td>, then the call returns immediately, as there's nothing to do. 3. In case of nested tables, event.target may be a <td>, but lying outside of the current table. So we check if that's actually our table's <td>. 4. And, if it's so, then highlight it. As the result, we have a fast, efficient highlighting code, that doesn't care about the total number of <td> in the table. ## Delegation example: actions in markup There are other uses for event delegation. Let's say, we want to make a menu with buttons "Save", "Load", "Search" and so on. And there's an object with methods save, load, search... How to match them? The first idea may be to assign a separate handler to each button. But there's a more elegant solution. We can add a handler for the whole menu and data-action attributes for buttons that has the method to call: The handler reads the attribute and executes the method. Take a look at the working example: Please note that this.onClick is bound to this in (*). That's important, because otherwise this inside it would reference the DOM element (elem), not the Menu object, and this[action] would not be what we need. So, what advantages does delegation give us here? We could also use classes .action-save, .action-load, but an attribute data-action is better semantically. And we can use it in CSS rules too. ## The "behavior" pattern We can also use event delegation to add "behaviors" to elements declaratively, with special attributes and classes. The pattern has two parts: 1. We add a custom attribute to an element that describes its behavior. 2. A document-wide handler tracks events, and if an event happens on an attributed element -- performs the action. ### Behavior: Counter For instance, here the attribute data-counter adds a behavior: "increase value on click" to buttons: If we click a button -- its value is increased. Not buttons, but the general approach is important here. There can be as many attributes with data-counter as we want. We can add new ones to HTML at any moment. Using the event delegation we "extended" HTML, added an attribute that describes a new behavior. ### Behavior: Toggler One more example of behavior. A click on an element with the attribute data-toggle-id will show/hide the element with the given id: Let's note once again what we did. Now, to add toggling functionality to an element -- there's no need to know JavaScript, just use the attribute data-toggle-id. That may become really convenient -- no need to write JavaScript for every such element. Just use the behavior. The document-level handler makes it work for any element of the page. We can combine multiple behaviors on a single element as well. The "behavior" pattern can be an alternative to mini-fragments of JavaScript. ## Summary Event delegation is really cool! It's one of the most helpful patterns for DOM events. It's often used to add the same handling for many similar elements, but not only for that. The algorithm: 1. Put a single handler on the container. 2. In the handler -- check the source element event.target. 3. If the event happened inside an element that interests us, then handle the event. Benefits: The delegation has its limitations of course:
Browser default actions
Many events automatically lead to certain actions performed by the browser. For instance: - A click on a link - initiates navigation to its URL. - A click on a form submit button - initiates its submission to the server. - Pressing a mouse button over a text and moving it - selects the text. If we handle an event in JavaScript, we may not want the corresponding browser action to happen, and want to implement another behavior instead. ## Preventing browser actions There are two ways to tell the browser we don't want it to act: - The main way is to use the event object. There's a method event.preventDefault(). - If the handler is assigned using on<event> (not by addEventListener), then returning false also works the same. In this HTML, a click on a link doesn't lead to navigation; the browser doesn't do anything: In the next example we'll use this technique to create a JavaScript-powered menu. ### Example: the menu Consider a site menu, like this: Here's how it looks with some CSS: [iframe height=70 src="menu" link edit] Menu items are implemented as HTML-links <a>, not buttons <button>. There are several reasons to do so, for instance: - Many people like to use "right click" -- "open in a new window". If we use <button> or <span>, that doesn't work. - Search engines follow <a href="..."> links while indexing. So we use <a> in the markup. But normally we intend to handle clicks in JavaScript. So we should prevent the default browser action. Like here: If we omit return false, then after our code executes the browser will do its "default action" -- navigating to the URL in href. And we don't need that here, as we're handling the click by ourselves. By the way, using event delegation here makes our menu very flexible. We can add nested lists and style them using CSS to "slide down". <input value="Focus works" onfocus="this.value=''"> <input !onmousedown="return false"/! onfocus="this.value=''" value="Click me"> ## The "passive" handler option The optional passive: true option of addEventListener signals the browser that the handler is not going to call preventDefault(). Why might that be needed? There are some events like touchmove on mobile devices (when the user moves their finger across the screen), that cause scrolling by default, but that scrolling can be prevented using preventDefault() in the handler. So when the browser detects such event, it has first to process all handlers, and then if preventDefault is not called anywhere, it can proceed with scrolling. That may cause unnecessary delays and "jitters" in the UI. The passive: true options tells the browser that the handler is not going to cancel scrolling. Then browser scrolls immediately providing a maximally fluent experience, and the event is handled by the way. For some browsers (Firefox, Chrome), passive is true by default for touchstart and touchmove events. ## event.defaultPrevented The property event.defaultPrevented is true if the default action was prevented, and false otherwise. There's an interesting use case for it. You remember in the chapter <info:bubbling-and-capturing> we talked about event.stopPropagation() and why stopping bubbling is bad? Sometimes we can use event.defaultPrevented instead, to signal other event handlers that the event was handled. Let's see a practical example. By default the browser on contextmenu event (right mouse click) shows a context menu with standard options. We can prevent it and show our own, like this: Now, in addition to that context menu we'd like to implement document-wide context menu. Upon right click, the closest context menu should show up. The problem is that when we click on elem, we get two menus: the button-level and (the event bubbles up) the document-level menu. How to fix it? One of solutions is to think like: "When we handle right-click in the button handler, let's stop its bubbling" and use event.stopPropagation(): Now the button-level menu works as intended. But the price is high. We forever deny access to information about right-clicks for any outer code, including counters that gather statistics and so on. That's quite unwise. An alternative solution would be to check in the document handler if the default action was prevented? If it is so, then the event was handled, and we don't need to react on it. Now everything also works correctly. If we have nested elements, and each of them has a context menu of its own, that would also work. Just make sure to check for event.defaultPrevented in each contextmenu handler. ## Summary There are many default browser actions: - mousedown -- starts the selection (move the mouse to select). - click on <input type="checkbox"> -- checks/unchecks the input. - submit -- clicking an <input type="submit"> or hitting key:Enter inside a form field causes this event to happen, and the browser submits the form after it. - keydown -- pressing a key may lead to adding a character into a field, or other actions. - contextmenu -- the event happens on a right-click, the action is to show the browser context menu. - ...there are more... All the default actions can be prevented if we want to handle the event exclusively by JavaScript. To prevent a default action -- use either event.preventDefault() or return false. The second method works only for handlers assigned with on<event>. The passive: true option of addEventListener tells the browser that the action is not going to be prevented. That's useful for some mobile events, like touchstart and touchmove, to tell the browser that it should not wait for all handlers to finish before scrolling. If the default action was prevented, the value of event.defaultPrevented becomes true, otherwise it's false.
Dispatching custom events
We can not only assign handlers, but also generate events from JavaScript. Custom events can be used to create "graphical components". For instance, a root element of our own JS-based menu may trigger events telling what happens with the menu: open (menu open), select (an item is selected) and so on. Another code may listen for the events and observe what's happening with the menu. We can generate not only completely new events, that we invent for our own purposes, but also built-in ones, such as click, mousedown etc. That may be helpful for automated testing. ## Event constructor Built-in event classes form a hierarchy, similar to DOM element classes. The root is the built-in Event class. We can create Event objects like this: Arguments: - type -- event type, a string like "click" or our own like "my-event". - options -- the object with two optional properties: - bubbles: true/false -- if true, then the event bubbles. - cancelable: true/false -- if true, then the "default action" may be prevented. Later we'll see what it means for custom events. By default both are false: {bubbles: false, cancelable: false}. ## dispatchEvent After an event object is created, we should "run" it on an element using the call elem.dispatchEvent(event). Then handlers react on it as if it were a regular browser event. If the event was created with the bubbles flag, then it bubbles. In the example below the click event is initiated in JavaScript. The handler works same way as if the button was clicked: ## Bubbling example We can create a bubbling event with the name "hello" and catch it on document. All we need is to set bubbles to true: Notes: 1. We should use addEventListener for our custom events, because on<event> only exists for built-in events, document.onhello doesn't work. 2. Must set bubbles:true, otherwise the event won't bubble up. The bubbling mechanics is the same for built-in (click) and custom (hello) events. There are also capturing and bubbling stages. ## MouseEvent, KeyboardEvent and others Here's a short list of classes for UI Events from the UI Event specification: - UIEvent - FocusEvent - MouseEvent - WheelEvent - KeyboardEvent - ... We should use them instead of new Event if we want to create such events. For instance, new MouseEvent("click"). The right constructor allows to specify standard properties for that type of event. Like clientX/clientY for a mouse event: Please note: the generic Event constructor does not allow that. Let's try: Technically, we can work around that by assigning directly event.clientX=100 after creation. So that's a matter of convenience and following the rules. Browser-generated events always have the right type. The full list of properties for different UI events is in the specification, for instance, MouseEvent. ## Custom events For our own, completely new events types like "hello" we should use new CustomEvent. Technically CustomEvent is the same as Event, with one exception. In the second argument (object) we can add an additional property detail for any custom information that we want to pass with the event. For instance: The detail property can have any data. Technically we could live without, because we can assign any properties into a regular new Event object after its creation. But CustomEvent provides the special detail field for it to evade conflicts with other event properties. Besides, the event class describes "what kind of event" it is, and if the event is custom, then we should use CustomEvent just to be clear about what it is. ## event.preventDefault() Many browser events have a "default action", such as navigating to a link, starting a selection, and so on. For new, custom events, there are definitely no default browser actions, but a code that dispatches such event may have its own plans what to do after triggering the event. By calling event.preventDefault(), an event handler may send a signal that those actions should be canceled. In that case the call to elem.dispatchEvent(event) returns false. And the code that dispatched it knows that it shouldn't continue. Let's see a practical example - a hiding rabbit (could be a closing menu or something else). Below you can see a #rabbit and hide() function that dispatches "hide" event on it, to let all interested parties know that the rabbit is going to hide. Any handler can listen for that event with rabbit.addEventListener('hide',...) and, if needed, cancel the action using event.preventDefault(). Then the rabbit won't disappear: Please note: the event must have the flag cancelable: true, otherwise the call event.preventDefault() is ignored. ## Events-in-events are synchronous Usually events are processed in a queue. That is: if the browser is processing onclick and a new event occurs, e.g. mouse moved, then its handling is queued up, corresponding mousemove handlers will be called after onclick processing is finished. The notable exception is when one event is initiated from within another one, e.g. using dispatchEvent. Such events are processed immediately: the new event handlers are called, and then the current event handling is resumed. For instance, in the code below the menu-open event is triggered during the onclick. It's processed immediately, without waiting for onclick handler to end: The output order is: 1 -> nested -> 2. Please note that the nested event menu-open is caught on the document. The propagation and handling of the nested event is finished before the processing gets back to the outer code (onclick). That's not only about dispatchEvent, there are other cases. If an event handler calls methods that trigger other events -- they are processed synchronously too, in a nested fashion. Let's say we don't like it. We'd want onclick to be fully processed first, independently from menu-open or any other nested events. Then we can either put the dispatchEvent (or another event-triggering call) at the end of onclick or, maybe better, wrap it in the zero-delay setTimeout: Now dispatchEvent runs asynchronously after the current code execution is finished, including menu.onclick, so event handlers are totally separate. The output order becomes: 1 -> 2 -> nested. ## Summary To generate an event from code, we first need to create an event object. The generic Event(name, options) constructor accepts an arbitrary event name and the options object with two properties: - bubbles: true if the event should bubble. - cancelable: true if the event.preventDefault() should work. Other constructors of native events like MouseEvent, KeyboardEvent and so on accept properties specific to that event type. For instance, clientX for mouse events. For custom events we should use CustomEvent constructor. It has an additional option named detail, we should assign the event-specific data to it. Then all handlers can access it as event.detail. Despite the technical possibility of generating browser events like click or keydown, we should use them with great care. We shouldn't generate browser events as it's a hacky way to run handlers. That's bad architecture most of the time. Native events might be generated: - As a dirty hack to make 3rd-party libraries work the needed way, if they don't provide other means of interaction. - For automated testing, to "click the button" in the script and see if the interface reacts correctly. Custom events with our own names are often generated for architectural purposes, to signal what happens inside our menus, sliders, carousels etc.
Mouse events
In this chapter we'll get into more details about mouse events and their properties. Please note: such events may come not only from "mouse devices", but are also from other devices, such as phones and tablets, where they are emulated for compatibility. ## Mouse event types We've already seen some of these events: mousedown/mouseup : Mouse button is clicked/released over an element. mouseover/mouseout : Mouse pointer comes over/out from an element. mousemove : Every mouse move over an element triggers that event. click : Triggers after mousedown and then mouseup over the same element if the left mouse button was used. dblclick : Triggers after two clicks on the same element within a short timeframe. Rarely used nowadays. contextmenu : Triggers when the right mouse button is pressed. There are other ways to open a context menu, e.g. using a special keyboard key, it triggers in that case also, so it's not exactly the mouse event. ...There are several other events too, we'll cover them later. ## Events order As you can see from the list above, a user action may trigger multiple events. For instance, a left-button click first triggers mousedown, when the button is pressed, then mouseup and click when it's released. In cases when a single action initiates multiple events, their order is fixed. That is, the handlers are called in the order mousedown -> mouseup -> click. ## Mouse button Click-related events always have the button property, which allows to get the exact mouse button. We usually don't use it for click and contextmenu events, because the former happens only on left-click, and the latter -- only on right-click. On the other hand, mousedown and mouseup handlers may need event.button, because these events trigger on any button, so button allows to distinguish between "right-mousedown" and "left-mousedown". The possible values of event.button are: Most mouse devices only have the left and right buttons, so possible values are 0 or 2. Touch devices also generate similar events when one taps on them. Also there's event.buttons property that has all currently pressed buttons as an integer, one bit per button. In practice this property is very rarely used, you can find details at MDN if you ever need it. ## Modifiers: shift, alt, ctrl and meta All mouse events include the information about pressed modifier keys. Event properties: - shiftKey: key:Shift - altKey: key:Alt (or key:Opt for Mac) - ctrlKey: key:Ctrl - metaKey: key:Cmd for Mac They are true if the corresponding key was pressed during the event. For instance, the button below only works on key:Alt+Shift+click: ## Coordinates: clientX/Y, pageX/Y All mouse events provide coordinates in two flavours: 1. Window-relative: clientX and clientY. 2. Document-relative: pageX and pageY. We already covered the difference between them in the chapter <info:coordinates>. In short, document-relative coordinates pageX/Y are counted from the left-upper corner of the document, and do not change when the page is scrolled, while clientX/Y are counted from the current window left-upper corner. When the page is scrolled, they change. For instance, if we have a window of the size 500x500, and the mouse is in the left-upper corner, then clientX and clientY are 0, no matter how the page is scrolled. And if the mouse is in the center, then clientX and clientY are 250, no matter what place in the document it is. They are similar to position:fixed in that aspect. <input onmousemove="this.value=event.clientX+':'+event.clientY" value="Mouse over me"> ## Preventing selection on mousedown Double mouse click has a side effect that may be disturbing in some interfaces: it selects text. For instance, double-clicking on the text below selects it in addition to our handler: If one presses the left mouse button and, without releasing it, moves the mouse, that also makes the selection, often unwanted. There are multiple ways to prevent the selection, that you can read in the chapter <info:selection-range>. In this particular case the most reasonable way is to prevent the browser action on mousedown. It prevents both these selections: Now the bold element is not selected on double clicks, and pressing the left button on it won't start the selection. Please note: the text inside it is still selectable. However, the selection should start not on the text itself, but before or after it. Usually that's fine for users. <div !oncopy="alert('Copying forbidden!');return false"/!> Dear user, The copying is forbidden for you. If you know JS or HTML, then you can get everything from the page source though. </div> ## Summary Mouse events have the following properties: - Button: button. - Modifier keys (true if pressed): altKey, ctrlKey, shiftKey and metaKey (Mac). - If you want to handle key:Ctrl, then don't forget Mac users, they usually use key:Cmd, so it's better to check if (e.metaKey || e.ctrlKey). - Window-relative coordinates: clientX/clientY. - Document-relative coordinates: pageX/pageY. The default browser action of mousedown is text selection, if it's not good for the interface, then it should be prevented. In the next chapter we'll see more details about events that follow pointer movement and how to track element changes under it.
Moving the mouse: mouseover/out, mouseenter/leave
Let's dive into more details about events that happen when the mouse moves between elements. ## Events mouseover/mouseout, relatedTarget The mouseover event occurs when a mouse pointer comes over an element, and mouseout -- when it leaves. These events are special, because they have property relatedTarget. This property complements target. When a mouse leaves one element for another, one of them becomes target, and the other one - relatedTarget. For mouseover: - event.target -- is the element where the mouse came over. - event.relatedTarget -- is the element from which the mouse came (relatedTarget -> target). For mouseout the reverse: - event.target -- is the element that the mouse left. - event.relatedTarget -- is the new under-the-pointer element, that mouse left for (target -> relatedTarget). ## Skipping elements The mousemove event triggers when the mouse moves. But that doesn't mean that every pixel leads to an event. The browser checks the mouse position from time to time. And if it notices changes then triggers the events. That means that if the visitor is moving the mouse very fast then some DOM-elements may be skipped: If the mouse moves very fast from #FROM to #TO elements as painted above, then intermediate <div> elements (or some of them) may be skipped. The mouseout event may trigger on #FROM and then immediately mouseover on #TO. That's good for performance, because there may be many intermediate elements. We don't really want to process in and out of each one. On the other hand, we should keep in mind that the mouse pointer doesn't "visit" all elements along the way. It can "jump". In particular, it's possible that the pointer jumps right inside the middle of the page from out of the window. In that case relatedTarget is null, because it came from "nowhere": ## Mouseout when leaving for a child An important feature of mouseout -- it triggers, when the pointer moves from an element to its descendant, e.g. from #parent to #child in this HTML: If we're on #parent and then move the pointer deeper into #child, we get mouseout on #parent! That may seem strange, but can be easily explained. *According to the browser logic, the mouse cursor may be only over a single element at any time -- the most nested one and top by z-index.* So if it goes to another element (even a descendant), then it leaves the previous one. Please note another important detail of event processing. The mouseover event on a descendant bubbles up. So, if #parent has mouseover handler, it triggers: As shown, when the pointer moves from #parent element to #child, two handlers trigger on the parent element: mouseout and mouseover: If we don't examine event.target inside the handlers, then it may seem that the mouse pointer left #parent element, and then immediately came back over it. But that's not the case! The pointer is still over the parent, it just moved deeper into the child element. If there are some actions upon leaving the parent element, e.g. an animation runs in parent.onmouseout, we usually don't want it when the pointer just goes deeper into #parent. To avoid it, we can check relatedTarget in the handler and, if the mouse is still inside the element, then ignore such event. Alternatively we can use other events: mouseenter and mouseleave, that we'll be covering now, as they don't have such problems. ## Events mouseenter and mouseleave Events mouseenter/mouseleave are like mouseover/mouseout. They trigger when the mouse pointer enters/leaves the element. But there are two important differences: 1. Transitions inside the element, to/from descendants, are not counted. 2. Events mouseenter/mouseleave do not bubble. These events are extremely simple. When the pointer enters an element -- mouseenter triggers. The exact location of the pointer inside the element or its descendants doesn't matter. When the pointer leaves an element -- mouseleave triggers. ## Event delegation Events mouseenter/leave are very simple and easy to use. But they do not bubble. So we can't use event delegation with them. Imagine we want to handle mouse enter/leave for table cells. And there are hundreds of cells. The natural solution would be -- to set the handler on <table> and process events there. But mouseenter/leave don't bubble. So if such event happens on <td>, then only a handler on that <td> is able to catch it. Handlers for mouseenter/leave on <table> only trigger when the pointer enters/leaves the table as a whole. It's impossible to get any information about transitions inside it. So, let's use mouseover/mouseout. Let's start with simple handlers that highlight the element under mouse: In our case we'd like to handle transitions between table cells <td>: entering a cell and leaving it. Other transitions, such as inside the cell or outside of any cells, don't interest us. Let's filter them out. Here's what we can do: - Remember the currently highlighted <td> in a variable, let's call it currentElem. - On mouseover -- ignore the event if we're still inside the current <td>. - On mouseout -- ignore if we didn't leave the current <td>. Here's an example of code that accounts for all possible situations: [js src="mouseenter-mouseleave-delegation-2/script.js"] Once again, the important features are: 1. It uses event delegation to handle entering/leaving of any <td> inside the table. So it relies on mouseover/out instead of mouseenter/leave that don't bubble and hence allow no delegation. 2. Extra events, such as moving between descendants of <td> are filtered out, so that onEnter/Leave runs only if the pointer leaves or enters <td> as a whole. ## Summary We covered events mouseover, mouseout, mousemove, mouseenter and mouseleave. These things are good to note: - A fast mouse move may skip intermediate elements. - Events mouseover/out and mouseenter/leave have an additional property: relatedTarget. That's the element that we are coming from/to, complementary to target. Events mouseover/out trigger even when we go from the parent element to a child element. The browser assumes that the mouse can be only over one element at one time -- the deepest one. Events mouseenter/leave are different in that aspect: they only trigger when the mouse comes in and out the element as a whole. Also they do not bubble.
Drag'n'Drop with mouse events
Drag'n'Drop is a great interface solution. Taking something and dragging and dropping it is a clear and simple way to do many things, from copying and moving documents (as in file managers) to ordering (dropping items into a cart). In the modern HTML standard there's a section about Drag and Drop with special events such as dragstart, dragend, and so on. These events allow us to support special kinds of drag'n'drop, such as handling dragging a file from OS file-manager and dropping it into the browser window. Then JavaScript can access the contents of such files. But native Drag Events also have limitations. For instance, we can't prevent dragging from a certain area. Also we can't make the dragging "horizontal" or "vertical" only. And there are many other drag'n'drop tasks that can't be done using them. Also, mobile device support for such events is very weak. So here we'll see how to implement Drag'n'Drop using mouse events. ## Drag'n'Drop algorithm The basic Drag'n'Drop algorithm looks like this: 1. On mousedown - prepare the element for moving, if needed (maybe create a clone of it, add a class to it or whatever). 2. Then on mousemove move it by changing left/top with position:absolute. 3. On mouseup - perform all actions related to finishing the drag'n'drop. These are the basics. Later we'll see how to add other features, such as highlighting current underlying elements while we drag over them. Here's the implementation of dragging a ball: If we run the code, we can notice something strange. On the beginning of the drag'n'drop, the ball "forks": we start dragging its "clone". That's because the browser has its own drag'n'drop support for images and some other elements. It runs automatically and conflicts with ours. To disable it: Now everything will be all right. Another important aspect -- we track mousemove on document, not on ball. From the first sight it may seem that the mouse is always over the ball, and we can put mousemove on it. But as we remember, mousemove triggers often, but not for every pixel. So after swift move the pointer can jump from the ball somewhere in the middle of document (or even outside of the window). So we should listen on document to catch it. ## Correct positioning In the examples above the ball is always moved so that its center is under the pointer: Not bad, but there's a side effect. To initiate the drag'n'drop, we can mousedown anywhere on the ball. But if "take" it from its edge, then the ball suddenly "jumps" to become centered under the mouse pointer. It would be better if we keep the initial shift of the element relative to the pointer. For instance, if we start dragging by the edge of the ball, then the pointer should remain over the edge while dragging. Let's update our algorithm: 1. When a visitor presses the button (mousedown) - remember the distance from the pointer to the left-upper corner of the ball in variables shiftX/shiftY. We'll keep that distance while dragging. To get these shifts we can substract the coordinates: ```js // onmousedown let shiftX = event.clientX - ball.getBoundingClientRect().left; let shiftY = event.clientY - ball.getBoundingClientRect().top; ``` 2. Then while dragging we position the ball on the same shift relative to the pointer, like this: ```js // onmousemove // ball has position:absolute ball.style.left = event.pageX - !shiftX/! + 'px'; ball.style.top = event.pageY - !shiftY/! + 'px'; ``` The final code with better positioning: The difference is especially noticeable if we drag the ball by its right-bottom corner. In the previous example the ball "jumps" under the pointer. Now it fluently follows the pointer from the current position. ## Potential drop targets (droppables) In previous examples the ball could be dropped just "anywhere" to stay. In real-life we usually take one element and drop it onto another. For instance, a "file" into a "folder" or something else. Speaking abstract, we take a "draggable" element and drop it onto "droppable" element. We need to know: - where the element was dropped at the end of Drag'n'Drop -- to do the corresponding action, - and, preferably, know the droppable we're dragging over, to highlight it. The solution is kind-of interesting and just a little bit tricky, so let's cover it here. What may be the first idea? Probably to set mouseover/mouseup handlers on potential droppables? But that doesn't work. The problem is that, while we're dragging, the draggable element is always above other elements. And mouse events only happen on the top element, not on those below it. For instance, below are two <div> elements, red one on top of the blue one (fully covers). There's no way to catch an event on the blue one, because the red is on top: The same with a draggable element. The ball is always on top over other elements, so events happen on it. Whatever handlers we set on lower elements, they won't work. That's why the initial idea to put handlers on potential droppables doesn't work in practice. They won't run. So, what to do? There's a method called document.elementFromPoint(clientX, clientY). It returns the most nested element on given window-relative coordinates (or null if given coordinates are out of the window). If there are multiple overlapping elements on the same coordinates, then the topmost one is returned. We can use it in any of our mouse event handlers to detect the potential droppable under the pointer, like this: Please note: we need to hide the ball before the call (*). Otherwise we'll usually have a ball on these coordinates, as it's the top element under the pointer: elemBelow=ball. So we hide it and immediately show again. We can use that code to check what element we're "flying over" at any time. And handle the drop when it happens. An extended code of onMouseMove to find "droppable" elements: In the example below when the ball is dragged over the soccer goal, the goal is highlighted. [codetabs height=250 src="ball4"] Now we have the current "drop target", that we're flying over, in the variable currentDroppable during the whole process and can use it to highlight or any other stuff. ## Summary We considered a basic Drag'n'Drop algorithm. The key components: 1. Events flow: ball.mousedown -> document.mousemove -> ball.mouseup (don't forget to cancel native ondragstart). 2. At the drag start -- remember the initial shift of the pointer relative to the element: shiftX/shiftY and keep it during the dragging. 3. Detect droppable elements under the pointer using document.elementFromPoint. We can lay a lot on this foundation. - On mouseup we can intellectually finalize the drop: change data, move elements around. - We can highlight the elements we're flying over. - We can limit dragging by a certain area or direction. - We can use event delegation for mousedown/up. A large-area event handler that checks event.target can manage Drag'n'Drop for hundreds of elements. - And so on. There are frameworks that build architecture over it: DragZone, Droppable, Draggable and other classes. Most of them do the similar stuff to what's described above, so it should be easy to understand them now. Or roll your own, as you can see that that's easy enough to do, sometimes easier than adapting a third-party solution.
Pointer events
Pointer events are a modern way to handle input from a variety of pointing devices, such as a mouse, a pen/stylus, a touchscreen, and so on. ## The brief history Let's make a small overview, so that you understand the general picture and the place of Pointer Events among other event types. - Long ago, in the past, there were only mouse events. Then touch devices became widespread, phones and tablets in particular. For the existing scripts to work, they generated (and still generate) mouse events. For instance, tapping a touchscreen generates mousedown. So touch devices worked well with web pages. But touch devices have more capabilities than a mouse. For example, it's possible to touch multiple points at once ("multi-touch"). Although, mouse events don't have necessary properties to handle such multi-touches. - So touch events were introduced, such as touchstart, touchend, touchmove, that have touch-specific properties (we don't cover them in detail here, because pointer events are even better). Still, it wasn't enough, as there are many other devices, such as pens, that have their own features. Also, writing code that listens for both touch and mouse events was cumbersome. - To solve these issues, the new standard Pointer Events was introduced. It provides a single set of events for all kinds of pointing devices. As of now, Pointer Events Level 2 specification is supported in all major browsers, while the newer Pointer Events Level 3 is in the works and is mostly compatible with Pointer Events level 2. Unless you develop for old browsers, such as Internet Explorer 10, or for Safari 12 or below, there's no point in using mouse or touch events any more -- we can switch to pointer events. Then your code will work well with both touch and mouse devices. That said, there are some important peculiarities that one should know in order to use Pointer Events correctly and avoid surprises. We'll make note of them in this article. ## Pointer event types Pointer events are named similarly to mouse events: As we can see, for every mouse<event>, there's a pointer<event> that plays a similar role. Also there are 3 additional pointer events that don't have a corresponding mouse... counterpart, we'll explain them soon. ## Pointer event properties Pointer events have the same properties as mouse events, such as clientX/Y, target, etc., plus some others: - pointerId - the unique identifier of the pointer causing the event. Browser-generated. Allows us to handle multiple pointers, such as a touchscreen with stylus and multi-touch (examples will follow). - pointerType - the pointing device type. Must be a string, one of: "mouse", "pen" or "touch". We can use this property to react differently on various pointer types. - isPrimary - is true for the primary pointer (the first finger in multi-touch). Some pointer devices measure contact area and pressure, e.g. for a finger on the touchscreen, there are additional properties for that: - width - the width of the area where the pointer (e.g. a finger) touches the device. Where unsupported, e.g. for a mouse, it's always 1. - height - the height of the area where the pointer touches the device. Where unsupported, it's always 1. - pressure - the pressure of the pointer tip, in range from 0 to 1. For devices that don't support pressure must be either 0.5 (pressed) or 0. - tangentialPressure - the normalized tangential pressure. - tiltX, tiltY, twist - pen-specific properties that describe how the pen is positioned relative to the surface. These properties aren't supported by most devices, so they are rarely used. You can find the details about them in the specification if needed. ## Multi-touch One of the things that mouse events totally don't support is multi-touch: a user can touch in several places at once on their phone or tablet, or perform special gestures. Pointer Events allow handling multi-touch with the help of the pointerId and isPrimary properties. Here's what happens when a user touches a touchscreen in one place, then puts another finger somewhere else on it: 1. At the first finger touch: - pointerdown with isPrimary=true and some pointerId. 2. For the second finger and more fingers (assuming the first one is still touching): - pointerdown with isPrimary=false and a different pointerId for every finger. Please note: the pointerId is assigned not to the whole device, but for each touching finger. If we use 5 fingers to simultaneously touch the screen, we have 5 pointerdown events, each with their respective coordinates and a different pointerId. The events associated with the first finger always have isPrimary=true. We can track multiple touching fingers using their pointerId. When the user moves and then removes a finger, we get pointermove and pointerup events with the same pointerId as we had in pointerdown. ## Event: pointercancel The pointercancel event fires when there's an ongoing pointer interaction, and then something happens that causes it to be aborted, so that no more pointer events are generated. Such causes are: - The pointer device hardware was physically disabled. - The device orientation changed (tablet rotated). - The browser decided to handle the interaction on its own, considering it a mouse gesture or zoom-and-pan action or something else. We'll demonstrate pointercancel on a practical example to see how it affects us. Let's say we're implementing drag'n'drop for a ball, just as in the beginning of the article <info:mouse-drag-and-drop>. Here is the flow of user actions and the corresponding events: 1) The user presses on an image, to start dragging - pointerdown event fires 2) Then they start moving the pointer (thus dragging the image) - pointermove fires, maybe several times 3) And then the surprise happens! The browser has native drag'n'drop support for images, that kicks in and takes over the drag'n'drop process, thus generating pointercancel event. - The browser now handles drag'n'drop of the image on its own. The user may even drag the ball image out of the browser, into their Mail program or a File Manager. - No more pointermove events for us. So the issue is that the browser "hijacks" the interaction: pointercancel fires in the beginning of the "drag-and-drop" process, and no more pointermove events are generated. We'd like to implement the drag'n'drop on our own, so let's tell the browser not to take it over. Prevent the default browser action to avoid pointercancel. We need to do two things: 1. Prevent native drag'n'drop from happening: - We can do this by setting ball.ondragstart = () => false, just as described in the article <info:mouse-drag-and-drop>. - That works well for mouse events. 2. For touch devices, there are other touch-related browser actions (besides drag'n'drop). To avoid problems with them too: - Prevent them by setting #ball { touch-action: none } in CSS. - Then our code will start working on touch devices. After we do that, the events will work as intended, the browser won't hijack the process and doesn't emit pointercancel. Now we can add the code to actually move the ball, and our drag'n'drop will work for mouse devices and touch devices. ## Pointer capturing Pointer capturing is a special feature of pointer events. The idea is very simple, but may seem quite odd at first, as nothing like that exists for any other event type. The main method is: - elem.setPointerCapture(pointerId) -- binds events with the given pointerId to elem. After the call all pointer events with the same pointerId will have elem as the target (as if happened on elem), no matter where in document they really happened. In other words, elem.setPointerCapture(pointerId) retargets all subsequent events with the given pointerId to elem. The binding is removed: - automatically when pointerup or pointercancel events occur, - automatically when elem is removed from the document, - when elem.releasePointerCapture(pointerId) is called. Now what is it good for? It's time to see a real-life example. Pointer capturing can be used to simplify drag'n'drop kind of interactions. Let's recall how one can implement a custom slider, described in the <info:mouse-drag-and-drop>. We can make a slider element to represent the strip and the "runner" (thumb) inside it: With styles, it looks like this: [iframe src="slider-html" height=40 edit] <p></p> And here's the working logic, as it was described, after replacing mouse events with similar pointer events: 1. The user presses on the slider thumb -- pointerdown triggers. 2. Then they move the pointer -- pointermove triggers, and our code moves the thumb element along. - ...As the pointer moves, it may leave the slider thumb element, go above or below it. The thumb should move strictly horizontally, remaining aligned with the pointer. In the mouse event based solution, to track all pointer movements, including when it goes above/below the thumb, we had to assign mousemove event handler on the whole document. That's not a cleanest solution, though. One of the problems is that when a user moves the pointer around the document, it may trigger event handlers (such as mouseover) on some other elements, invoke totally unrelated UI functionality, and we don't want that. This is the place where setPointerCapture comes into play. - We can call thumb.setPointerCapture(event.pointerId) in pointerdown handler, - Then future pointer events until pointerup/cancel will be retargeted to thumb. - When pointerup happens (dragging complete), the binding is removed automatically, we don't need to care about it. So, even if the user moves the pointer around the whole document, events handlers will be called on thumb. Nevertheless, coordinate properties of the event objects, such as clientX/clientY will still be correct - the capturing only affects target/currentTarget. Here's the essential code: At the end, pointer capturing gives us two benefits: 1. The code becomes cleaner as we don't need to add/remove handlers on the whole document any more. The binding is released automatically. 2. If there are other pointer event handlers in the document, they won't be accidentally triggered by the pointer while the user is dragging the slider. ### Pointer capturing events There's one more thing to mention here, for the sake of completeness. There are two events associated with pointer capturing: - gotpointercapture fires when an element uses setPointerCapture to enable capturing. - lostpointercapture fires when the capture is released: either explicitly with releasePointerCapture call, or automatically on pointerup/pointercancel. ## Summary Pointer events allow handling mouse, touch and pen events simultaneously, with a single piece of code. Pointer events extend mouse events. We can replace mouse with pointer in event names and expect our code to continue working for mouse, with better support for other device types. For drag'n'drops and complex touch interactions that the browser may decide to hijack and handle on its own - remember to cancel the default action on events and set touch-action: none in CSS for elements that we engage. Additional abilities of pointer events are: - Multi-touch support using pointerId and isPrimary. - Device-specific properties, such as pressure, width/height, and others. - Pointer capturing: we can retarget all pointer events to a specific element until pointerup/pointercancel. As of now, pointer events are supported in all major browsers, so we can safely switch to them, especially if IE10- and Safari 12- are not needed. And even with those browsers, there are polyfills that enable the support of pointer events.
Keyboard: keydown and keyup
Before we get to keyboard, please note that on modern devices there are other ways to "input something". For instance, people use speech recognition (especially on mobile devices) or copy/paste with the mouse. So if we want to track any input into an <input> field, then keyboard events are not enough. There's another event named input to track changes of an <input> field, by any means. And it may be a better choice for such task. We'll cover it later in the chapter <info:events-change-input>. Keyboard events should be used when we want to handle keyboard actions (virtual keyboard also counts). For instance, to react on arrow keys key:Up and key:Down or hotkeys (including combinations of keys). ## Teststand [#keyboard-test-stand] ## Keydown and keyup The keydown events happens when a key is pressed down, and then keyup -- when it's released. ### event.code and event.key The key property of the event object allows to get the character, while the code property of the event object allows to get the "physical key code". For instance, the same key key:Z can be pressed with or without key:Shift. That gives us two different characters: lowercase z and uppercase Z. The event.key is exactly the character, and it will be different. But event.code is the same: If a user works with different languages, then switching to another language would make a totally different character instead of "Z". That will become the value of event.key, while event.code is always the same: "KeyZ". What if a key does not give any character? For instance, key:Shift or key:F1 or others. For those keys, event.key is approximately the same as event.code: Please note that event.code specifies exactly which key is pressed. For instance, most keyboards have two key:Shift keys: on the left and on the right side. The event.code tells us exactly which one was pressed, and event.key is responsible for the "meaning" of the key: what it is (a "Shift"). Let's say, we want to handle a hotkey: key:Ctrl+Z (or key:Cmd+Z for Mac). Most text editors hook the "Undo" action on it. We can set a listener on keydown and check which key is pressed. There's a dilemma here: in such a listener, should we check the value of event.key or event.code? On one hand, the value of event.key is a character, it changes depending on the language. If the visitor has several languages in OS and switches between them, the same key gives different characters. So it makes sense to check event.code, it's always the same. Like this: On the other hand, there's a problem with event.code. For different keyboard layouts, the same key may have different characters. For example, here are US layout ("QWERTY") and German layout ("QWERTZ") under it (from Wikipedia): For the same key, US layout has "Z", while German layout has "Y" (letters are swapped). Literally, event.code will equal KeyZ for people with German layout when they press key:Y. If we check event.code == 'KeyZ' in our code, then for people with German layout such test will pass when they press key:Y. That sounds really odd, but so it is. The specification explicitly mentions such behavior. So, event.code may match a wrong character for unexpected layout. Same letters in different layouts may map to different physical keys, leading to different codes. Luckily, that happens only with several codes, e.g. keyA, keyQ, keyZ (as we've seen), and doesn't happen with special keys such as Shift. You can find the list in the specification. To reliably track layout-dependent characters, event.key may be a better way. On the other hand, event.code has the benefit of staying always the same, bound to the physical key location. So hotkeys that rely on it work well even in case of a language switch. Do we want to handle layout-dependant keys? Then event.key is the way to go. Or we want a hotkey to work even after a language switch? Then event.code may be better. ## Auto-repeat If a key is being pressed for a long enough time, it starts to "auto-repeat": the keydown triggers again and again, and then when it's released we finally get keyup. So it's kind of normal to have many keydown and a single keyup. For events triggered by auto-repeat, the event object has event.repeat property set to true. ## Default actions Default actions vary, as there are many possible things that may be initiated by the keyboard. For instance: - A character appears on the screen (the most obvious outcome). - A character is deleted (key:Delete key). - The page is scrolled (key:PageDown key). - The browser opens the "Save Page" dialog (key:Ctrl+S) - ...and so on. Preventing the default action on keydown can cancel most of them, with the exception of OS-based special keys. For instance, on Windows key:Alt+F4 closes the current browser window. And there's no way to stop it by preventing the default action in JavaScript. For instance, the <input> below expects a phone number, so it does not accept keys except digits, +, () or -: The onkeydown handler here uses checkPhoneKey to check for the key pressed. If it's valid (from 0..9 or one of +-()), then it returns true, otherwise false. As we know, the false value returned from the event handler, assigned using a DOM property or an attribute, such as above, prevents the default action, so nothing appears in the <input> for keys that don't pass the test. (The true value returned doesn't affect anything, only returning false matters) Please note that special keys, such as key:Backspace, key:Left, key:Right, do not work in the input. That's a side effect of the strict filter checkPhoneKey. These keys make it return false. Let's relax the filter a little bit by allowing arrow keys key:Left, key:Right and key:Delete, key:Backspace: Now arrows and deletion works well. Even though we have the key filter, one still can enter anything using a mouse and right-click + Paste. Mobile devices provide other means to enter values. So the filter is not 100% reliable. The alternative approach would be to track the oninput event -- it triggers after any modification. There we can check the new input.value and modify it/highlight the <input> when it's invalid. Or we can use both event handlers together. ## Legacy In the past, there was a keypress event, and also keyCode, charCode, which properties of the event object. There were so many browser incompatibilities while working with them, that developers of the specification had no way, other than deprecating all of them and creating new, modern events (described above in this chapter). The old code still works, as browsers keep supporting them, but there's totally no need to use those any more. ## Mobile Keyboards When using virtual/mobile keyboards, formally known as IME (Input-Method Editor), the W3C standard states that a KeyboardEvent's e.keyCode should be 229 and e.key should be "Unidentified". While some of these keyboards might still use the right values for e.key, e.code, e.keyCode... when pressing certain keys such as arrows or backspace, there's no guarantee, so your keyboard logic might not always work on mobile devices. ## Summary Pressing a key always generates a keyboard event, be it symbol keys or special keys like key:Shift or key:Ctrl and so on. The only exception is key:Fn key that sometimes presents on a laptop keyboard. There's no keyboard event for it, because it's often implemented on lower level than OS. Keyboard events: - keydown -- on pressing the key (auto-repeats if the key is pressed for long), - keyup -- on releasing the key. Main keyboard event properties: - code -- the "key code" ("KeyA", "ArrowLeft" and so on), specific to the physical location of the key on keyboard. - key -- the character ("A", "a" and so on), for non-character keys, such as key:Esc, usually has the same value as code. In the past, keyboard events were sometimes used to track user input in form fields. That's not reliable, because the input can come from various sources. We have input and change events to handle any input (covered later in the chapter <info:events-change-input>). They trigger after any kind of input, including copy-pasting or speech recognition. We should use keyboard events when we really want keyboard. For example, to react on hotkeys or special keys.
Scrolling
The scroll event allows reacting to a page or element scrolling. There are quite a few good things we can do here. For instance: - Show/hide additional controls or information depending on where in the document the user is. - Load more data when the user scrolls down till the end of the page. Here's a small function to show the current scroll: The scroll event works both on the window and on scrollable elements. ## Prevent scrolling How do we make something unscrollable? We can't prevent scrolling by using event.preventDefault() in onscroll listener, because it triggers after the scroll has already happened. But we can prevent scrolling by event.preventDefault() on an event that causes the scroll, for instance keydown event for key:pageUp and key:pageDown. If we add an event handler to these events and event.preventDefault() in it, then the scroll won't start. There are many ways to initiate a scroll, so it's more reliable to use CSS, overflow property. Here are few tasks that you can solve or look through to see applications of onscroll.
Form properties and methods
Forms and control elements, such as <input> have a lot of special properties and events. Working with forms will be much more convenient when we learn them. ## Navigation: form and elements Document forms are members of the special collection document.forms. That's a so-called "named collection": it's both named and ordered. We can use both the name or the number in the document to get the form. When we have a form, then any element is available in the named collection form.elements. For instance: There may be multiple elements with the same name. This is typical with radio buttons and checkboxes. In that case, form.elements[name] is a collection. For instance: These navigation properties do not depend on the tag structure. All control elements, no matter how deep they are in the form, are available in form.elements. <body> <form id="form"> <fieldset name="userFields"> <legend>info</legend> <input name="login" type="text"> </fieldset> </form> <script> alert(form.elements.login); // <input name="login"> let fieldset = form.elements.userFields; alert(fieldset); // HTMLFieldSetElement // we can get the input by name both from the form and from the fieldset alert(fieldset.elements.login == form.elements.login); // true </script> </body> <form id="form"> <input name="login"> </form> <script> alert(form.elements.login == form.login); // true, the same <input> form.login.name = "username"; // change the name of the input // form.elements updated the name: alert(form.elements.login); // undefined alert(form.elements.username); // input // form allows both names: the new one and the old one alert(form.username == form.login); // true </script> ## Backreference: element.form For any element, the form is available as element.form. So a form references all elements, and elements reference the form. Here's the picture: For instance: ## Form elements Let's talk about form controls. ### input and textarea We can access their value as input.value (string) or input.checked (boolean) for checkboxes and radio buttons. Like this: ### select and option A <select> element has 3 important properties: 1. select.options -- the collection of <option> subelements, 2. select.value -- the value of the currently selected <option>, 3. select.selectedIndex -- the number of the currently selected <option>. They provide three different ways of setting a value for a <select>: 1. Find the corresponding <option> element (e.g. among select.options) and set its option.selected to true. 2. If we know a new value: set select.value to the new value. 3. If we know the new option number: set select.selectedIndex to that number. Here is an example of all three methods: Unlike most other controls, <select> allows to select multiple options at once if it has multiple attribute. This attribute is rarely used, though. For multiple selected values, use the first way of setting values: add/remove the selected property from <option> subelements. Here's an example of how to get selected values from a multi-select: The full specification of the <select> element is available in the specification <https://html.spec.whatwg.org/multipage/forms.html#the-select-element>. ### new Option In the specification there's a nice short syntax to create an <option> element: This syntax is optional. We can use document.createElement('option') and set attributes manually. Still, it may be shorter, so here are the parameters: - text -- the text inside the option, - value -- the option value, - defaultSelected -- if true, then selected HTML-attribute is created, - selected -- if true, then the option is selected. The difference between defaultSelected and selected is that defaultSelected sets the HTML-attribute (that we can get using option.getAttribute('selected')), while selected sets whether the option is selected or not. In practice, one should usually set _both_ values to true or false. (Or, simply omit them; both default to false.) For instance, here's a new "unselected" option: The same option, but selected: Option elements have properties: option.selected : Is the option selected. option.index : The number of the option among the others in its <select>. option.text : Text content of the option (seen by the visitor). ## References - Specification: <https://html.spec.whatwg.org/multipage/forms.html>. ## Summary Form navigation: document.forms : A form is available as document.forms[name/index]. form.elements : Form elements are available as form.elements[name/index], or can use just form[name/index]. The elements property also works for <fieldset>. element.form : Elements reference their form in the form property. Value is available as input.value, textarea.value, select.value, etc. (For checkboxes and radio buttons, use input.checked to determine whether a value is selected.) For <select>, one can also get the value by the index select.selectedIndex or through the options collection select.options. These are the basics to start working with forms. We'll meet many examples further in the tutorial. In the next chapter we'll cover focus and blur events that may occur on any element, but are mostly handled on forms.
Focusing: focus/blur
An element receives the focus when the user either clicks on it or uses the key:Tab key on the keyboard. There's also an autofocus HTML attribute that puts the focus onto an element by default when a page loads and other means of getting the focus. Focusing on an element generally means: "prepare to accept the data here", so that's the moment when we can run the code to initialize the required functionality. The moment of losing the focus ("blur") can be even more important. That's when a user clicks somewhere else or presses key:Tab to go to the next form field, or there are other means as well. Losing the focus generally means: "the data has been entered", so we can run the code to check it or even to save it to the server and so on. There are important peculiarities when working with focus events. We'll do the best to cover them further on. ## Events focus/blur The focus event is called on focusing, and blur -- when the element loses the focus. Let's use them for validation of an input field. In the example below: - The blur handler checks if the field has an email entered, and if not -- shows an error. - The focus handler hides the error message (on blur it will be checked again): Modern HTML allows us to do many validations using input attributes: required, pattern and so on. And sometimes they are just what we need. JavaScript can be used when we want more flexibility. Also we could automatically send the changed value to the server if it's correct. ## Methods focus/blur Methods elem.focus() and elem.blur() set/unset the focus on the element. For instance, let's make the visitor unable to leave the input if the value is invalid: It works in all browsers except Firefox (bug). If we enter something into the input and then try to use key:Tab or click away from the <input>, then onblur returns the focus back. Please note that we can't "prevent losing focus" by calling event.preventDefault() in onblur, because onblur works after the element lost the focus. In practice though, one should think well, before implementing something like this, because we generally should show errors to the user, but should not prevent their progress in filling our form. They may want to fill other fields first. ## Allow focusing on any element: tabindex By default, many elements do not support focusing. The list varies a bit between browsers, but one thing is always correct: focus/blur support is guaranteed for elements that a visitor can interact with: <button>, <input>, <select>, <a> and so on. On the other hand, elements that exist to format something, such as <div>, <span>, <table> -- are unfocusable by default. The method elem.focus() doesn't work on them, and focus/blur events are never triggered. This can be changed using HTML-attribute tabindex. Any element becomes focusable if it has tabindex. The value of the attribute is the order number of the element when key:Tab (or something like that) is used to switch between them. That is: if we have two elements, the first has tabindex="1", and the second has tabindex="2", then pressing key:Tab while in the first element -- moves the focus into the second one. The switch order is: elements with tabindex from 1 and above go first (in the tabindex order), and then elements without tabindex (e.g. a regular <input>). Elements without matching tabindex are switched in the document source order (the default order). There are two special values: - tabindex="0" puts an element among those without tabindex. That is, when we switch elements, elements with tabindex=0 go after elements with tabindex ≥ 1. Usually it's used to make an element focusable, but keep the default switching order. To make an element a part of the form on par with <input>. - tabindex="-1" allows only programmatic focusing on an element. The key:Tab key ignores such elements, but method elem.focus() works. For instance, here's a list. Click the first item and press key:Tab: The order is like this: 1 - 2 - 0. Normally, <li> does not support focusing, but tabindex full enables it, along with events and styling with :focus. ## Delegation: focusin/focusout Events focus and blur do not bubble. For instance, we can't put onfocus on the <form> to highlight it, like this: The example above doesn't work, because when user focuses on an <input>, the focus event triggers on that input only. It doesn't bubble up. So form.onfocus never triggers. There are two solutions. First, there's a funny historical feature: focus/blur do not bubble up, but propagate down on the capturing phase. This will work: Second, there are focusin and focusout events -- exactly the same as focus/blur, but they bubble. Note that they must be assigned using elem.addEventListener, not on<event>. So here's another working variant: ## Summary Events focus and blur trigger on an element focusing/losing focus. Their specials are: - They do not bubble. Can use capturing state instead or focusin/focusout. - Most elements do not support focus by default. Use tabindex to make anything focusable. The current focused element is available as document.activeElement.
Events: change, input, cut, copy, paste
Let's cover various events that accompany data updates. ## Event: change The change event triggers when the element has finished changing. For text inputs that means that the event occurs when it loses focus. For instance, while we are typing in the text field below -- there's no event. But when we move the focus somewhere else, for instance, click on a button -- there will be a change event: For other elements: select, input type=checkbox/radio it triggers right after the selection changes: ## Event: input The input event triggers every time after a value is modified by the user. Unlike keyboard events, it triggers on any value change, even those that does not involve keyboard actions: pasting with a mouse or using speech recognition to dictate the text. For instance: If we want to handle every modification of an <input> then this event is the best choice. On the other hand, input event doesn't trigger on keyboard input and other actions that do not involve value change, e.g. pressing arrow keys key:⇦ key:⇨ while in the input. ## Events: cut, copy, paste These events occur on cutting/copying/pasting a value. They belong to ClipboardEvent class and provide access to the data that is cut/copied/pasted. We also can use event.preventDefault() to abort the action, then nothing gets copied/pasted. For instance, the code below prevents all cut/copy/paste events and shows the text we're trying to cut/copy/paste: Please note: inside cut and copy event handlers a call to event.clipboardData.getData(...) returns an empty string. That's because technically the data isn't in the clipboard yet. If we use event.preventDefault() it won't be copied at all. So the example above uses document.getSelection() to get the selected text. You can find more details about document selection in the article <info:selection-range>. It's possible to copy/paste not just text, but everything. For instance, we can copy a file in the OS file manager, and paste it. That's because clipboardData implements DataTransfer interface, commonly used for drag'n'drop and copy/pasting. It's a bit beyond our scope now, but you can find its methods in the DataTransfer specification. Also, there's an additional asynchronous API of accessing the clipboard: navigator.clipboard. More about it in the specification Clipboard API and events, not supported by Firefox. ### Safety restrictions The clipboard is a "global" OS-level thing. A user may switch between various applications, copy/paste different things, and a browser page shouldn't see all that. So most browsers allow seamless read/write access to the clipboard only in the scope of certain user actions, such as copying/pasting etc. It's forbidden to generate "custom" clipboard events with dispatchEvent in all browsers except Firefox. And even if we manage to dispatch such event, the specification clearly states that such "synthetic" events must not provide access to the clipboard. Even if someone decides to save event.clipboardData in an event handler, and then access it later -- it won't work. To reiterate, event.clipboardData works solely in the context of user-initiated event handlers. On the other hand, navigator.clipboard is the more recent API, meant for use in any context. It asks for user permission, if needed. ## Summary Data change events:
Forms: event and method submit
The submit event triggers when the form is submitted, it is usually used to validate the form before sending it to the server or to abort the submission and process it in JavaScript. The method form.submit() allows to initiate form sending from JavaScript. We can use it to dynamically create and send our own forms to server. Let's see more details of them. ## Event: submit There are two main ways to submit a form: 1. The first -- to click <input type="submit"> or <input type="image">. 2. The second -- press key:Enter on an input field. Both actions lead to submit event on the form. The handler can check the data, and if there are errors, show them and call event.preventDefault(), then the form won't be sent to the server. In the form below: 1. Go into the text field and press key:Enter. 2. Click <input type="submit">. Both actions show alert and the form is not sent anywhere due to return false: <form onsubmit="return false"> <input type="text" size="30" value="Focus here and press enter"> <input type="submit" value="Submit" !onclick="alert('click')"/!> </form> ## Method: submit To submit a form to the server manually, we can call form.submit(). Then the submit event is not generated. It is assumed that if the programmer calls form.submit(), then the script already did all related processing. Sometimes that's used to manually create and send a form, like this:
Page: DOMContentLoaded, load, beforeunload, unload
The lifecycle of an HTML page has three important events: - DOMContentLoaded -- the browser fully loaded HTML, and the DOM tree is built, but external resources like pictures <img> and stylesheets may not yet have loaded. - load -- not only HTML is loaded, but also all the external resources: images, styles etc. - beforeunload/unload -- the user is leaving the page. Each event may be useful: - DOMContentLoaded event -- DOM is ready, so the handler can lookup DOM nodes, initialize the interface. - load event -- external resources are loaded, so styles are applied, image sizes are known etc. - 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. ## DOMContentLoaded The DOMContentLoaded event happens on the document object. We must use addEventListener to catch it: For instance: In the example, the DOMContentLoaded handler runs when the document is loaded, so it can see all the elements, including <img> below. But it doesn't wait for the image to load. So alert shows zero sizes. At first sight, the DOMContentLoaded event is very simple. The DOM tree is ready -- here's the event. There are few peculiarities though. ### DOMContentLoaded and scripts 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. So DOMContentLoaded definitely happens after such scripts: In the example above, we first see "Library loaded...", and then "DOM ready!" (all scripts are executed). ### DOMContentLoaded and styles 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 until the stylesheet loads: The reason for this is that the script may want to get coordinates and other style-dependent properties of elements, like in the example above. Naturally, it has to wait for styles to load. As DOMContentLoaded waits for scripts, it now waits for styles before them as well. ### Built-in browser autofill Firefox, Chrome and Opera autofill forms on DOMContentLoaded. For instance, if the page has a form with login and password, and the browser remembered the values, then on DOMContentLoaded it may try to autofill them (if approved by the user). 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. ## window.onload [#window-onload] The load event on the window object triggers when the whole page is loaded including styles, images and other resources. This event is available via the onload property. The example below correctly shows image sizes, because window.onload waits for all images: ## window.onunload 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. The notable exception is sending analytics. Let's say we gather data about how the page is used: mouse clicks, scrolls, viewed page areas, and so on. Naturally, unload event is when the user leaves us, and we'd like to save the data on our server. 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, but still performs sendBeacon. Here's how to use it: - The request is sent as POST. - We can send not only a string, but also forms and other formats, as described in the chapter <info:fetch>, but usually it's a stringified object. - The data is limited by 64kb. 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 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. 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: For historical reasons, returning a non-empty string also counts as canceling the event. Some time ago browsers used to show it as a message, but as the modern specification says, they shouldn't. Here's an example: 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. window.addEventListener("beforeunload", (event) => { // doesn't work, so this event handler doesn't do anything event.preventDefault(); }); window.addEventListener("beforeunload", (event) => { // works, same as returning from window.onbeforeunload event.returnValue = "There are unsaved changes. Leave now?"; }); ## 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. 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. There are 3 possible values: - "loading" -- the document is loading. - "interactive" -- the document was fully read. - "complete" -- the document was fully read and all resources (like images) are loaded too. So we can check document.readyState and setup a handler or execute the code immediately if it's ready. Like this: There's also the readystatechange event that triggers when the state changes, so we can print all these states like this: The readystatechange event is an alternative mechanics of tracking the document loading state, it appeared long ago. Nowadays, it is rarely used. Let's see the full events flow for the completeness. Here's a document with <iframe>, <img> and handlers that log events: The working example is in the sandbox. The typical output: 1. [1] initial readyState:loading 2. [2] readyState:interactive 3. [2] DOMContentLoaded 4. [3] iframe onload 5. [4] img onload 6. [4] readyState:complete 7. [4] window onload 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 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. ## Summary Page load events: - The DOMContentLoaded event triggers on document when the DOM is ready. We can apply JavaScript to elements at this stage. - 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. - The 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. - The 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). - The 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. - complete -- the document and resources are loaded, happens at about the same time as window.onload, but before it.
Scripts: async, defer
In modern websites, scripts are often "heavier" than HTML: their download size is larger, and processing time is also longer. When the browser loads HTML and comes across a <script>...</script> tag, it can't continue building the DOM. It must execute the script right now. The same happens for external scripts <script src="..."></script>: the browser must wait for the script to download, execute the downloaded script, and only then can it process the rest of the page. That leads to two important issues: 1. Scripts can't see DOM elements below them, so they can't add handlers etc. 2. If there's a bulky script at the top of the page, it "blocks the page". Users can't see the page content till it downloads and runs: There are some workarounds to that. For instance, we can put a script at the bottom of the page. Then it can see elements above it, and it doesn't block the page content from showing: But this solution is far from perfect. For example, the browser notices the script (and can start downloading it) only after it downloaded the full HTML document. For long HTML documents, that may be a noticeable delay. Such things are invisible for people using very fast connections, but many people in the world still have slow internet speeds and use a far-from-perfect mobile internet connection. Luckily, there are two <script> attributes that solve the problem for us: defer and async. ## defer The defer attribute tells the browser not to wait for the script. Instead, the browser will continue to process the HTML, build DOM. The script loads "in the background", and then runs when the DOM is fully built. Here's the same example as above, but with defer: In other words: - Scripts with defer never block the page. - Scripts with defer always execute when the DOM is ready (but before DOMContentLoaded event). The following example demonstrates the second part: 1. The page content shows up immediately. 2. DOMContentLoaded event handler waits for the deferred script. It only triggers when the script is downloaded and executed. Deferred scripts keep their relative order, just like regular scripts. Let's say, we have two deferred scripts: the long.js and then small.js: Browsers scan the page for scripts and download them in parallel, to improve performance. So in the example above both scripts download in parallel. The small.js probably finishes first. ...But the defer attribute, besides telling the browser "not to block", ensures that the relative order is kept. So even though small.js loads first, it still waits and runs after long.js executes. That may be important for cases when we need to load a JavaScript library and then a script that depends on it. ## async The async attribute is somewhat like defer. It also makes the script non-blocking. But it has important differences in the behavior. The async attribute means that a script is completely independent: - The browser doesn't block on async scripts (like defer). - Other scripts don't wait for async scripts, and async scripts don't wait for them. - DOMContentLoaded and async scripts don't wait for each other: - DOMContentLoaded may happen both before an async script (if an async script finishes loading after the page is complete) - ...or after an async script (if an async script is short or was in HTTP-cache) In other words, async scripts load in the background and run when ready. The DOM and other scripts don't wait for them, and they don't wait for anything. A fully independent script that runs when loaded. As simple, as it can get, right? Here's an example similar to what we've seen with defer: two scripts long.js and small.js, but now with async instead of defer. They don't wait for each other. Whatever loads first (probably small.js) -- runs first: - The page content shows up immediately: async doesn't block it. - DOMContentLoaded may happen both before and after async, no guarantees here. - A smaller script small.js goes second, but probably loads before long.js, so small.js runs first. Although, it might be that long.js loads first, if cached, then it runs first. In other words, async scripts run in the "load-first" order. Async scripts are great when we integrate an independent third-party script into the page: counters, ads and so on, as they don't depend on our scripts, and our scripts shouldn't wait for them: ## Dynamic scripts There's one more important way of adding a script to the page. We can create a script and append it to the document dynamically using JavaScript: The script starts loading as soon as it's appended to the document (*). Dynamic scripts behave as "async" by default. That is: - They don't wait for anything, nothing waits for them. - The script that loads first -- runs first ("load-first" order). This can be changed if we explicitly set script.async=false. Then scripts will be executed in the document order, just like defer. In this example, loadScript(src) function adds a script and also sets async to false. So long.js always runs first (as it's added first): Without script.async=false, scripts would execute in default, load-first order (the small.js probably first). Again, as with the defer, the order matters if we'd like to load a library and then another script that depends on it. ## Summary Both async and defer have one common thing: downloading of such scripts doesn't block page rendering. So the user can read page content and get acquainted with the page immediately. But there are also essential differences between them: In practice, defer is used for scripts that need the whole DOM and/or their relative execution order is important. And async is used for independent scripts, like counters or ads. And their relative execution order does not matter.
Resource loading: onload and onerror
The browser allows us to track the loading of external resources -- scripts, iframes, pictures and so on. There are two events for it: - onload -- successful load, - onerror -- an error occurred. ## Loading a script Let's say we need to load a third-party script and call a function that resides there. We can load it dynamically, like this: ...But how to run the function that is declared inside that script? We need to wait until the script loads, and only then we can call it. ### script.onload The main helper is the load event. It triggers after the script was loaded and executed. For instance: So in onload we can use script variables, run functions etc. ...And what if the loading failed? For instance, there's no such script (error 404) or the server is down (unavailable). ### script.onerror Errors that occur during the loading of the script can be tracked in an error event. For instance, let's request a script that doesn't exist: Please note that we can't get HTTP error details here. We don't know if it was an error 404 or 500 or something else. Just that the loading failed. ## Other resources The load and error events also work for other resources, basically for any resource that has an external src. For example: There are some notes though: - Most resources start loading when they are added to the document. But <img> is an exception. It starts loading when it gets a src (*). - For <iframe>, the iframe.onload event triggers when the iframe loading finished, both for successful load and in case of an error. That's for historical reasons. ## Crossorigin policy There's a rule: scripts from one site can't access contents of the other site. So, e.g. a script at https://facebook.com can't read the user's mailbox at https://gmail.com. Or, to be more precise, one origin (domain/port/protocol triplet) can't access the content from another one. So even if we have a subdomain, or just another port, these are different origins with no access to each other. This rule also affects resources from other domains. If we're using a script from another domain, and there's an error in it, we can't get error details. For example, let's take a script error.js that consists of a single (bad) function call: Now load it from the same site where it's located: We can see a good error report, like this: Now let's load the same script from another domain: The report is different, like this: Details may vary depending on the browser, but the idea is the same: any information about the internals of a script, including error stack traces, is hidden. Exactly because it's from another domain. Why do we need error details? There are many services (and we can build our own) that listen for global errors using window.onerror, save errors and provide an interface to access and analyze them. That's great, as we can see real errors, triggered by our users. But if a script comes from another origin, then there's not much information about errors in it, as we've just seen. Similar cross-origin policy (CORS) is enforced for other types of resources as well. To allow cross-origin access, the <script> tag needs to have the crossorigin attribute, plus the remote server must provide special headers. There are three levels of cross-origin access: 1. No crossorigin attribute -- access prohibited. 2. crossorigin="anonymous" -- access allowed if the server responds with the header Access-Control-Allow-Origin with * or our origin. Browser does not send authorization information and cookies to remote server. 3. crossorigin="use-credentials" -- access allowed if the server sends back the header Access-Control-Allow-Origin with our origin and Access-Control-Allow-Credentials: true. Browser sends authorization information and cookies to remote server. In our case, we didn't have any crossorigin attribute. So the cross-origin access was prohibited. Let's add it. We can choose between "anonymous" (no cookies sent, one server-side header needed) and "use-credentials" (sends cookies too, two server-side headers needed). If we don't care about cookies, then "anonymous" is the way to go: Now, assuming that the server provides an Access-Control-Allow-Origin header, everything's fine. We have the full error report. ## Summary Images <img>, external styles, scripts and other resources provide load and error events to track their loading: - load triggers on a successful load, - error triggers on a failed load. The only exception is <iframe>: for historical reasons it always triggers load, for any load completion, even if the page is not found. The readystatechange event also works for resources, but is rarely used, because load/error events are simpler.
Mutation observer
MutationObserver is a built-in object that observes a DOM element and fires a callback when it detects a change. We'll first take a look at the syntax, and then explore a real-world use case, to see where such thing may be useful. ## Syntax MutationObserver is easy to use. First, we create an observer with a callback-function: And then attach it to a DOM node: config is an object with boolean options "what kind of changes to react on": - childList -- changes in the direct children of node, - subtree -- in all descendants of node, - attributes -- attributes of node, - attributeFilter -- an array of attribute names, to observe only selected ones. - characterData -- whether to observe node.data (text content), Few other options: - attributeOldValue -- if true, pass both the old and the new value of attribute to callback (see below), otherwise only the new one (needs attributes option), - characterDataOldValue -- if true, pass both the old and the new value of node.data to callback (see below), otherwise only the new one (needs characterData option). Then after any changes, the callback is executed: changes are passed in the first argument as a list of MutationRecord objects, and the observer itself as the second argument. MutationRecord objects have properties: - type -- mutation type, one of - "attributes": attribute modified - "characterData": data modified, used for text nodes, - "childList": child elements added/removed, - target -- where the change occurred: an element for "attributes", or text node for "characterData", or an element for a "childList" mutation, - addedNodes/removedNodes -- nodes that were added/removed, - previousSibling/nextSibling -- the previous and next sibling to added/removed nodes, - attributeName/attributeNamespace -- the name/namespace (for XML) of the changed attribute, - oldValue -- the previous value, only for attribute or text changes, if the corresponding option is set attributeOldValue/characterDataOldValue. For example, here's a <div> with a contentEditable attribute. That attribute allows us to focus on it and edit. If we run this code in the browser, then focus on the given <div> and change the text inside <b>edit</b>, console.log will show one mutation: If we make more complex editing operations, e.g. remove the <b>edit</b>, the mutation event may contain multiple mutation records: So, MutationObserver allows to react on any changes within DOM subtree. ## Usage for integration When such thing may be useful? Imagine the situation when you need to add a third-party script that contains useful functionality, but also does something unwanted, e.g. shows ads <div class="ads">Unwanted ads</div>. Naturally, the third-party script provides no mechanisms to remove it. Using MutationObserver, we can detect when the unwanted element appears in our DOM and remove it. There are other situations when a third-party script adds something into our document, and we'd like to detect, when it happens, to adapt our page, dynamically resize something etc. MutationObserver allows to implement this. ## Usage for architecture There are also situations when MutationObserver is good from architectural standpoint. Let's say we're making a website about programming. Naturally, articles and other materials may contain source code snippets. Such snippet in an HTML markup looks like this: For better readability and at the same time, to beautify it, we'll be using a JavaScript syntax highlighting library on our site, like Prism.js. To get syntax highlighting for above snippet in Prism, Prism.highlightElem(pre) is called, which examines the contents of such pre elements and adds special tags and styles for colored syntax highlighting into those elements, similar to what you see in examples here, on this page. When exactly should we run that highlighting method? Well, we can do it on DOMContentLoaded event, or put the script at the bottom of the page. The moment our DOM is ready, we can search for elements pre[class*="language"] and call Prism.highlightElem on them: Everything's simple so far, right? We find code snippets in HTML and highlight them. Now let's go on. Let's say we're going to dynamically fetch materials from a server. We'll study methods for that later in the tutorial. For now it only matters that we fetch an HTML article from a webserver and display it on demand: The new article HTML may contain code snippets. We need to call Prism.highlightElem on them, otherwise they won't get highlighted. Where and when to call Prism.highlightElem for a dynamically loaded article? We could append that call to the code that loads an article, like this: ...But, imagine if we have many places in the code where we load our content - articles, quizzes, forum posts, etc. Do we need to put the highlighting call everywhere, to highlight the code in content after loading? That's not very convenient. And what if the content is loaded by a third-party module? For example, we have a forum written by someone else, that loads content dynamically, and we'd like to add syntax highlighting to it. No one likes patching third-party scripts. Luckily, there's another option. We can use MutationObserver to automatically detect when code snippets are inserted into the page and highlight them. So we'll handle the highlighting functionality in one place, relieving us from the need to integrate it. ### Dynamic highlight demo Here's the working example. If you run this code, it starts observing the element below and highlighting any code snippets that appear there: Here, below, there's an HTML-element and JavaScript that dynamically fills it using innerHTML. Please run the previous code (above, observes that element), and then the code below. You'll see how MutationObserver detects and highlights the snippet. <p id="highlight-demo" style="border: 1px solid #ddd">A demo-element with <code>id="highlight-demo"</code>, run the code above to observe it.</p> The following code populates its innerHTML, that causes the MutationObserver to react and highlight its contents: Now we have MutationObserver that can track all highlighting in observed elements or the whole document. We can add/remove code snippets in HTML without thinking about it. ## Additional methods There's a method to stop observing the node: - observer.disconnect() -- stops the observation. When we stop the observing, it might be possible that some changes were not yet processed by the observer. In such cases, we use - observer.takeRecords() -- gets a list of unprocessed mutation records - those that happened, but the callback has not handled them. These methods can be used together, like this: ## Summary MutationObserver can react to changes in DOM - attributes, text content and adding/removing elements. We can use it to track changes introduced by other parts of our code, as well as to integrate with third-party scripts. MutationObserver can track any changes. The config "what to observe" options are used for optimizations, not to spend resources on unneeded callback invocations.
Selection and Range
In this chapter we'll cover selection in the document, as well as selection in form fields, such as <input>. JavaScript can access an existing selection, select/deselect DOM nodes as a whole or partially, remove the selected content from the document, wrap it into a tag, and so on. You can find some recipes for common tasks at the end of the chapter, in "Summary" section. Maybe that covers your current needs, but you'll get much more if you read the whole text. The underlying Range and Selection objects are easy to grasp, and then you'll need no recipes to make them do what you want. ## Range The basic concept of selection is Range, that is essentially a pair of "boundary points": range start and range end. A Range object is created without parameters: Then we can set the selection boundaries using range.setStart(node, offset) and range.setEnd(node, offset). As you might guess, further we'll use the Range objects for selection, but first let's create few such objects. ### Selecting the text partially The interesting thing is that the first argument node in both methods can be either a text node or an element node, and the meaning of the second argument depends on that. If node is a text node, then offset must be the position in its text. For example, given the element <p>Hello</p>, we can create the range containing the letters "ll" as follows: Here we take the first child of <p> (that's the text node) and specify the text positions inside it: ### Selecting element nodes Alternatively, if node is an element node, then offset must be the child number. That's handy for making ranges that contain nodes as a whole, not stop somewhere inside their text. For example, we have a more complex document fragment: Here's its DOM structure with both element and text nodes: <div class="select-p-domtree"></div> <script> let selectPDomtree = { "name": "P", "nodeType": 1, "children": [{ "name": "#text", "nodeType": 3, "content": "Example: " }, { "name": "I", "nodeType": 1, "children": [{ "name": "#text", "nodeType": 3, "content": "italic" }, { "name": "#text", "nodeType": 3, "content": " and " }, { "name": "B", "nodeType": 1, "children": [{ "name": "#text", "nodeType": 3, "content": "bold" drawHtmlTree(selectPDomtree, 'div.select-p-domtree', 690, 320); </script> Let's make a range for "Example: <i>italic</i>". As we can see, this phrase consists of exactly two children of <p>, with indexes 0 and 1: - The starting point has <p> as the parent node, and 0 as the offset. So we can set it as range.setStart(p, 0). - The ending point also has <p> as the parent node, but 2 as the offset (it specifies the range up to, but not including offset). So we can set it as range.setEnd(p, 2). Here's the demo. If you run it, you can see that the text gets selected: Here's a more flexible test stand where you can set range start/end numbers and explore other variants: E.g. selecting in the same <p> from offset 1 to 4 gives us the range <i>italic</i> and <b>bold</b>: ### Selecting a bigger fragment Let's make a bigger selection in our example, like this: We already know how to do that. We just need to set the start and the end as a relative offset in text nodes. We need to create a range, that: - starts from position 2 in <p> first child (taking all but two first letters of "Ex<b>ample:</b> ") - ends at the position 3 in <b> first child (taking first three letters of "<b>bol</b>d", but no more): As you can see, it's fairly easy to make a range of whatever we want. If we'd like to take nodes as a whole, we can pass elements in setStart/setEnd. Otherwise, we can work on the text level. ## Range properties The range object that we created in the example above has following properties: - startContainer, startOffset -- node and offset of the start, - in the example above: first text node inside <p> and 2. - endContainer, endOffset -- node and offset of the end, - in the example above: first text node inside <b> and 3. - collapsed -- boolean, true if the range starts and ends on the same point (so there's no content inside the range), - in the example above: false - commonAncestorContainer -- the nearest common ancestor of all nodes within the range, - in the example above: <p> ## Range selection methods There are many convenient methods to manipulate ranges. We've already seen setStart and setEnd, here are other similar methods. Set range start: - setStart(node, offset) set start at: position offset in node - setStartBefore(node) set start at: right before node - setStartAfter(node) set start at: right after node Set range end (similar methods): - setEnd(node, offset) set end at: position offset in node - setEndBefore(node) set end at: right before node - setEndAfter(node) set end at: right after node Technically, setStart/setEnd can do anything, but more methods provide more convenience. In all these methods, node can be both a text or element node: for text nodes offset skips that many of characters, while for element nodes that many child nodes. Even more methods to create ranges: - selectNode(node) set range to select the whole node - selectNodeContents(node) set range to select the whole node contents - collapse(toStart) if toStart=true set end=start, otherwise set start=end, thus collapsing the range - cloneRange() creates a new range with the same start/end ## Range editing methods Once the range is created, we can manipulate its content using these methods: - deleteContents() -- remove range content from the document - extractContents() -- remove range content from the document and return as DocumentFragment - cloneContents() -- clone range content and return as DocumentFragment - insertNode(node) -- insert node into the document at the beginning of the range - surroundContents(node) -- wrap node around range content. For this to work, the range must contain both opening and closing tags for all elements inside it: no partial ranges like <i>abc. With these methods we can do basically anything with selected nodes. Here's the test stand to see them in action: There also exist methods to compare ranges, but these are rarely used. When you need them, please refer to the spec or MDN manual. ## Selection Range is a generic object for managing selection ranges. Although, creating a Range doesn't mean that we see a selection on screen. We may create Range objects, pass them around -- they do not visually select anything on their own. The document selection is represented by Selection object, that can be obtained as window.getSelection() or document.getSelection(). A selection may include zero or more ranges. At least, the Selection API specification says so. In practice though, only Firefox allows to select multiple ranges in the document by using key:Ctrl+click (key:Cmd+click for Mac). Here's a screenshot of a selection with 3 ranges, made in Firefox: Other browsers support at maximum 1 range. As we'll see, some of Selection methods imply that there may be many ranges, but again, in all browsers except Firefox, there's at maximum 1. Here's a small demo that shows the current selection (select something and click) as text: <button onclick="alert(document.getSelection())">alert(document.getSelection())</button> ## Selection properties As said, a selection may in theory contain multiple ranges. We can get these range objects using the method: - getRangeAt(i) -- get i-th range, starting from 0. In all browsers except Firefox, only 0 is used. Also, there exist properties that often provide better convenience. Similar to a range, a selection object has a start, called "anchor", and the end, called "focus". The main selection properties are: - anchorNode -- the node where the selection starts, - anchorOffset -- the offset in anchorNode where the selection starts, - focusNode -- the node where the selection ends, - focusOffset -- the offset in focusNode where the selection ends, - isCollapsed -- true if selection selects nothing (empty range), or doesn't exist. - rangeCount -- count of ranges in the selection, maximum 1 in all browsers except Firefox. ## Selection events There are events on to keep track of selection: - elem.onselectstart -- when a selection starts specifically on element elem (or inside it). For instance, when the user presses the mouse button on it and starts to move the pointer. - Preventing the default action cancels the selection start. So starting a selection from this element becomes impossible, but the element is still selectable. The visitor just needs to start the selection from elsewhere. - document.onselectionchange -- whenever a selection changes or starts. - Please note: this handler can be set only on document, it tracks all selections in it. ### Selection tracking demo Here's a small demo. It tracks the current selection on the document and shows its boundaries: ### Selection copying demo There are two approaches to copying the selected content: 1. We can use document.getSelection().toString() to get it as text. 2. Otherwise, to copy the full DOM, e.g. if we need to keep formatting, we can get the underlying ranges with getRangeAt(...). A Range object, in turn, has cloneContents() method that clones its content and returns as DocumentFragment object, that we can insert elsewhere. Here's the demo of copying the selected content both as text and as DOM nodes: ## Selection methods We can work with the selection by adding/removing ranges: - getRangeAt(i) -- get i-th range, starting from 0. In all browsers except Firefox, only 0 is used. - addRange(range) -- add range to selection. All browsers except Firefox ignore the call, if the selection already has an associated range. - removeRange(range) -- remove range from the selection. - removeAllRanges() -- remove all ranges. - empty() -- alias to removeAllRanges. There are also convenience methods to manipulate the selection range directly, without intermediate Range calls: - collapse(node, offset) -- replace selected range with a new one that starts and ends at the given node, at position offset. - setPosition(node, offset) -- alias to collapse. - collapseToStart() - collapse (replace with an empty range) to selection start, - collapseToEnd() - collapse to selection end, - extend(node, offset) - move focus of the selection to the given node, position offset, - setBaseAndExtent(anchorNode, anchorOffset, focusNode, focusOffset) - replace selection range with the given start anchorNode/anchorOffset and end focusNode/focusOffset. All content in-between them is selected. - selectAllChildren(node) -- select all children of the node. - deleteFromDocument() -- remove selected content from the document. - containsNode(node, allowPartialContainment = false) -- checks whether the selection contains node (partially if the second argument is true) For most tasks these methods are just fine, there's no need to access the underlying Range object. For example, selecting the whole contents of the paragraph <p>: The same thing using ranges: ## Selection in form controls Form elements, such as input and textarea provide special API for selection, without Selection or Range objects. As an input value is a pure text, not HTML, there's no need for such objects, everything's much simpler. Properties: - input.selectionStart -- position of selection start (writeable), - input.selectionEnd -- position of selection end (writeable), - input.selectionDirection -- selection direction, one of: "forward", "backward" or "none" (if e.g. selected with a double mouse click), Events: - input.onselect -- triggers when something is selected. Methods: - input.select() -- selects everything in the text control (can be textarea instead of input), - input.setSelectionRange(start, end, [direction]) -- change the selection to span from position start till end, in the given direction (optional). - input.setRangeText(replacement, [start], [end], [selectionMode]) -- replace a range of text with the new text. Optional arguments start and end, if provided, set the range start and end, otherwise user selection is used. The last argument, selectionMode, determines how the selection will be set after the text has been replaced. The possible values are: - "select" -- the newly inserted text will be selected. - "start" -- the selection range collapses just before the inserted text (the cursor will be immediately before it). - "end" -- the selection range collapses just after the inserted text (the cursor will be right after it). - "preserve" -- attempts to preserve the selection. This is the default. Now let's see these methods in action. ### Example: tracking selection For example, this code uses onselect event to track selection: Please note: - onselect triggers when something is selected, but not when the selection is removed. - document.onselectionchange event should not trigger for selections inside a form control, according to the spec, as it's not related to document selection and ranges. Some browsers generate it, but we shouldn't rely on it. ### Example: moving cursor We can change selectionStart and selectionEnd, that sets the selection. An important edge case is when selectionStart and selectionEnd equal each other. Then it's exactly the cursor position. Or, to rephrase, when nothing is selected, the selection is collapsed at the cursor position. So, by setting selectionStart and selectionEnd to the same value, we move the cursor. For example: ### Example: modifying selection To modify the content of the selection, we can use input.setRangeText() method. Of course, we can read selectionStart/End and, with the knowledge of the selection, change the corresponding substring of value, but setRangeText is more powerful and often more convenient. That's a somewhat complex method. In its simplest one-argument form it replaces the user selected range and removes the selection. For example, here the user selection will be wrapped by ...: With more arguments, we can set range start and end. In this example we find "THIS" in the input text, replace it and keep the replacement selected: ### Example: insert at cursor If nothing is selected, or we use equal start and end in setRangeText, then the new text is just inserted, nothing is removed. We can also insert something "at the cursor" using setRangeText. Here's a button that inserts "HELLO" at the cursor position and puts the cursor immediately after it. If the selection is not empty, then it gets replaced (we can detect it by comparing selectionStart!=selectionEnd and do something else instead): ## Making unselectable To make something unselectable, there are three ways: 1. Use CSS property user-select: none. ```html run <style> #elem { user-select: none; </style> <div>Selectable <div id="elem">Unselectable</div> Selectable</div> ``` This doesn't allow the selection to start at elem. But the user may start the selection elsewhere and include elem into it. Then elem will become a part of document.getSelection(), so the selection actually happens, but its content is usually ignored in copy-paste. 2. Prevent default action in onselectstart or mousedown events. ```html run <div>Selectable <div id="elem">Unselectable</div> Selectable</div> <script> elem.onselectstart = () => false; </script> ``` This prevents starting the selection on elem, but the visitor may start it at another element, then extend to elem. That's convenient when there's another event handler on the same action that triggers the select (e.g. mousedown). So we disable the selection to avoid conflict, still allowing elem contents to be copied. 3. We can also clear the selection post-factum after it happens with document.getSelection().empty(). That's rarely used, as this causes unwanted blinking as the selection appears-disappears. ## References - DOM spec: Range - Selection API - HTML spec: APIs for the text control selections ## Summary We covered two different APIs for selections: 1. For document: Selection and Range objects. 2. For input, textarea: additional methods and properties. The second API is very simple, as it works with text. The most used recipes are probably: 1. Getting the selection: ```js let selection = document.getSelection(); let cloned = / element to clone the selected nodes to /; // then apply Range methods to selection.getRangeAt(0) // or, like here, to all ranges to support multi-select for (let i = 0; i < selection.rangeCount; i++) { cloned.append(selection.getRangeAt(i).cloneContents()); ``` 2. Setting the selection: ```js let selection = document.getSelection(); // directly: selection.setBaseAndExtent(...from...to...); // or we can create a range and: selection.removeAllRanges(); selection.addRange(range); ``` And finally, about the cursor. The cursor position in editable elements, like <textarea> is always at the start or the end of the selection. We can use it to get cursor position or to move the cursor by setting elem.selectionStart and elem.selectionEnd.
Event loop: microtasks and macrotasks
Browser JavaScript execution flow, as well as in Node.js, is based on an event loop. Understanding how event loop works is important for optimizations, and sometimes for the right architecture. In this chapter we first cover theoretical details about how things work, and then see practical applications of that knowledge. ## Event Loop The event loop concept is very simple. There's an endless loop, where the JavaScript engine waits for tasks, executes them and then sleeps, waiting for more tasks. The general algorithm of the engine: 1. While there are tasks: - execute them, starting with the oldest task. 2. Sleep until a task appears, then go to 1. That's a formalization of what we see when browsing a page. The JavaScript engine does nothing most of the time, it only runs if a script/handler/event activates. Examples of tasks: - When an external script <script src="..."> loads, the task is to execute it. - When a user moves their mouse, the task is to dispatch mousemove event and execute handlers. - When the time is due for a scheduled setTimeout, the task is to run its callback. - ...and so on. Tasks are set -- the engine handles them -- then waits for more tasks (while sleeping and consuming close to zero CPU). It may happen that a task comes while the engine is busy, then it's enqueued. The tasks form a queue, the so-called "macrotask queue" (v8 term): For instance, while the engine is busy executing a script, a user may move their mouse causing mousemove, and setTimeout may be due and so on, these tasks form a queue, as illustrated in the picture above. Tasks from the queue are processed on a "first come – first served" basis. When the engine browser is done with the script, it handles mousemove event, then setTimeout handler, and so on. So far, quite simple, right? Two more details: 1. Rendering never happens while the engine executes a task. It doesn't matter if the task takes a long time. Changes to the DOM are painted only after the task is complete. 2. If a task takes too long, the browser can't do other tasks, such as processing user events. So after some time, it raises an alert like "Page Unresponsive", suggesting killing the task with the whole page. That happens when there are a lot of complex calculations or a programming error leading to an infinite loop. That was the theory. Now let's see how we can apply that knowledge. ## Use-case 1: splitting CPU-hungry tasks Let's say we have a CPU-hungry task. For example, syntax-highlighting (used to colorize code examples on this page) is quite CPU-heavy. To highlight the code, it performs the analysis, creates many colored elements, adds them to the document -- for a large amount of text that takes a lot of time. While the engine is busy with syntax highlighting, it can't do other DOM-related stuff, process user events, etc. It may even cause the browser to "hiccup" or even "hang" for a bit, which is unacceptable. We can avoid problems by splitting the big task into pieces. Highlight the first 100 lines, then schedule setTimeout (with zero-delay) for the next 100 lines, and so on. To demonstrate this approach, for the sake of simplicity, instead of text-highlighting, let's take a function that counts from 1 to 1000000000. If you run the code below, the engine will "hang" for some time. For server-side JS that's clearly noticeable, and if you are running it in-browser, then try to click other buttons on the page -- you'll see that no other events get handled until the counting finishes. The browser may even show a "the script takes too long" warning. Let's split the job using nested setTimeout calls: Now the browser interface is fully functional during the "counting" process. A single run of count does a part of the job (), and then re-schedules itself (*) if needed: 1. First run counts: i=1...1000000. 2. Second run counts: i=1000001..2000000. 3. ...and so on. Now, if a new side task (e.g. onclick event) appears while the engine is busy executing part 1, it gets queued and then executes when part 1 finished, before the next part. Periodic returns to the event loop between count executions provide just enough "air" for the JavaScript engine to do something else, to react to other user actions. The notable thing is that both variants -- with and without splitting the job by setTimeout -- are comparable in speed. There's not much difference in the overall counting time. To make them closer, let's make an improvement. We'll move the scheduling to the beginning of the count(): Now when we start to count() and see that we'll need to count() more, we schedule that immediately, before doing the job. If you run it, it's easy to notice that it takes significantly less time. Why? That's simple: as you remember, there's the in-browser minimal delay of 4ms for many nested setTimeout calls. Even if we set 0, it's 4ms (or a bit more). So the earlier we schedule it - the faster it runs. Finally, we've split a CPU-hungry task into parts - now it doesn't block the user interface. And its overall execution time isn't much longer. ## Use case 2: progress indication Another benefit of splitting heavy tasks for browser scripts is that we can show progress indication. As mentioned earlier, changes to DOM are painted only after the currently running task is completed, irrespective of how long it takes. On one hand, that's great, because our function may create many elements, add them one-by-one to the document and change their styles -- the visitor won't see any "intermediate", unfinished state. An important thing, right? Here's the demo, the changes to i won't show up until the function finishes, so we'll see only the last value: ...But we also may want to show something during the task, e.g. a progress bar. If we split the heavy task into pieces using setTimeout, then changes are painted out in-between them. This looks prettier: Now the <div> shows increasing values of i, a kind of a progress bar. ## Use case 3: doing something after the event In an event handler we may decide to postpone some actions until the event bubbled up and was handled on all levels. We can do that by wrapping the code in zero delay setTimeout. In the chapter <info:dispatch-events> we saw an example: custom event menu-open is dispatched in setTimeout, so that it happens after the "click" event is fully handled. ## Macrotasks and Microtasks Along with macrotasks, described in this chapter, there are microtasks, mentioned in the chapter <info:microtask-queue>. Microtasks come solely from our code. They are usually created by promises: an execution of .then/catch/finally handler becomes a microtask. Microtasks are used "under the cover" of await as well, as it's another form of promise handling. There's also a special function queueMicrotask(func) that queues func for execution in the microtask queue. *Immediately after every macrotask, the engine executes all tasks from microtask queue, prior to running any other macrotasks or rendering or anything else.* For instance, take a look: What's going to be the order here? 1. code shows first, because it's a regular synchronous call. 2. promise shows second, because .then passes through the microtask queue, and runs after the current code. 3. timeout shows last, because it's a macrotask. The richer event loop picture looks like this (order is from top to bottom, that is: the script first, then microtasks, rendering and so on): All microtasks are completed before any other event handling or rendering or any other macrotask takes place. That's important, as it guarantees that the application environment is basically the same (no mouse coordinate changes, no new network data, etc) between microtasks. If we'd like to execute a function asynchronously (after the current code), but before changes are rendered or new events handled, we can schedule it with queueMicrotask. Here's an example with "counting progress bar", similar to the one shown previously, but queueMicrotask is used instead of setTimeout. You can see that it renders at the very end. Just like the synchronous code: ## Summary A more detailed event loop algorithm (though still simplified compared to the specification): 1. Dequeue and run the oldest task from the macrotask queue (e.g. "script"). 2. Execute all microtasks: - While the microtask queue is not empty: - Dequeue and run the oldest microtask. 3. Render changes if any. 4. If the macrotask queue is empty, wait till a macrotask appears. 5. Go to step 1. To schedule a new macrotask: - Use zero delayed setTimeout(f). That may be used to split a big calculation-heavy task into pieces, for the browser to be able to react to user events and show progress between them. Also, used in event handlers to schedule an action after the event is fully handled (bubbling done). To schedule a new microtask - Use queueMicrotask(f). - Also promise handlers go through the microtask queue. There's no UI or network event handling between microtasks: they run immediately one after another. So one may want to queueMicrotask to execute a function asynchronously, but within the environment state.