| OLD | NEW |
| 1 --- | 1 --- |
| 2 layout: default | 2 layout: default |
| 3 title: "Add Elements to the DOM" | 3 title: "Add Elements to the DOM" |
| 4 description: "You have an Element object, now what?" | 4 description: "You have an Element object, now what?" |
| 5 has-permalinks: true | 5 has-permalinks: true |
| 6 tutorial: | 6 tutorial: |
| 7 id: add-elements | 7 id: add-elements |
| 8 next: remove-elements/ | 8 next: remove-elements/ |
| 9 next-title: "Remove DOM Elements" | 9 next-title: "Remove DOM Elements" |
| 10 prev: connect-dart-html/ | 10 prev: connect-dart-html/ |
| 11 prev-title: "Connect Dart & HTML" | 11 prev-title: "Connect Dart & HTML" |
| 12 --- | 12 --- |
| 13 | 13 |
| 14 {% capture whats_the_point %} | 14 {% capture whats_the_point %} |
| 15 | 15 |
| 16 * In Dart, page elements are of type Element. | 16 * In Dart, page elements are of type Element. |
| 17 * An Element knows its parent. | 17 * An Element knows its parent. |
| 18 * An Element keeps its children in a List\<Element>. | 18 * An Element keeps its children in a List\<Element>. |
| 19 * Change the DOM by adding or removing children of elements. | 19 * Change the DOM by adding or removing children of elements. |
| 20 * Respond to user input with an EventListener. | 20 * Respond to user input with an EventListener. |
| 21 | 21 |
| 22 {% endcapture %} | 22 {% endcapture %} |
| 23 | 23 |
| 24 {% capture sample_links %} | 24 {% capture sample_links %} |
| 25 | 25 |
| 26 <p> | 26 <p> |
| 27 Get the source code for the samples featured in this target:</p> | 27 Get the source code for the samples featured in this tutorial:</p> |
| 28 | 28 |
| 29 <ul> | 29 <ul> |
| 30 <li> | 30 <li> |
| 31 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web
/target03/todo" | 31 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web
/add-elements/todo" |
| 32 target="_blank">todo</a> | 32 target="_blank">todo</a> |
| 33 </li> | 33 </li> |
| 34 <li> | 34 <li> |
| 35 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web
/target03/anagram" | 35 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web
/add-elements/anagram" |
| 36 target="_blank">anagram</a> | 36 target="_blank">anagram</a> |
| 37 </li> | 37 </li> |
| 38 </ul> | 38 </ul> |
| 39 | 39 |
| 40 {% endcapture %} | 40 {% endcapture %} |
| 41 | 41 |
| 42 {% capture content %} | 42 {% capture content %} |
| 43 | 43 |
| 44 <div class="tute-target-title"> | 44 <div class="tute-target-title"> |
| 45 <h1>{{page.title}}</h1> | 45 <h1>{{page.title}}</h1> |
| 46 <h3>Dynamically add items to the browser page.</h3> | 46 <h3>Dynamically add items to the browser page.</h3> |
| 47 </div> | 47 </div> |
| 48 | 48 |
| 49 As you learned in the previous target, | 49 As you learned in the previous tutorial, |
| 50 the DOM represents the structure | 50 the DOM represents the structure |
| 51 of a web page document using a simple tree structure. | 51 of a web page document using a simple tree structure. |
| 52 Each node in the tree represents an item on the page. | 52 Each node in the tree represents an item on the page. |
| 53 Each node in the tree keeps track of both | 53 Each node in the tree keeps track of both |
| 54 its parent and its children. | 54 its parent and its children. |
| 55 In Dart, the | 55 In Dart, the |
| 56 <a href="https://api.dartlang.org/dart_html/Node.html" target="_blank">Node</a> | 56 <a href="https://api.dartlang.org/dart_html/Node.html" target="_blank">Node</a> |
| 57 class contains the methods and properties | 57 class contains the methods and properties |
| 58 that implement a node's tree functionality. | 58 that implement a node's tree functionality. |
| 59 | 59 |
| 60 HTML page elements are one kind of node that can be in the DOM tree. | 60 HTML page elements are one kind of node that can be in the DOM tree. |
| 61 They have a rectangular area on the page and can receive events. | 61 They have a rectangular area on the page and can receive events. |
| 62 Examples of elements include | 62 Examples of elements include |
| 63 heading elements, paragraph elements, table elements, | 63 heading elements, paragraph elements, table elements, |
| 64 button elements, and so on. | 64 button elements, and so on. |
| 65 | 65 |
| 66 In Dart, | 66 In Dart, |
| 67 elements are implemented by the | 67 elements are implemented by the |
| 68 <a href="https://api.dartlang.org/dart_html/Element.html" target="_blank">Elemen
t</a> | 68 <a href="https://api.dartlang.org/dart_html/Element.html" target="_blank">Elemen
t</a> |
| 69 class, which is a subclass of Node. | 69 class, which is a subclass of Node. |
| 70 Because the nodes you care about most are usually elements, | 70 Because the nodes you care about most are usually elements, |
| 71 this target focuses on Element, | 71 this tutorial focuses on Element, |
| 72 rather than on Node. | 72 rather than on Node. |
| 73 | 73 |
| 74 * [Copy and run the todo app](#copy-app) | 74 * [Copy and run the todo app](#copy-app) |
| 75 * [About parent and child Elements in Dart](#tree-structure) | 75 * [About parent and child Elements in Dart](#tree-structure) |
| 76 * [Setting up the page in HTML](#html-code) | 76 * [Setting up the page in HTML](#html-code) |
| 77 * [Getting an element from the DOM](#dart-code) | 77 * [Getting an element from the DOM](#dart-code) |
| 78 * [Registering an event handler](#event-handler) | 78 * [Registering an event handler](#event-handler) |
| 79 * [About EventListener functions](#about-event-listeners) | 79 * [About EventListener functions](#about-event-listeners) |
| 80 * [Adding an element to the DOM tree](#add-elem) | 80 * [Adding an element to the DOM tree](#add-elem) |
| 81 * [Styling the page elements](#about-css) | 81 * [Styling the page elements](#about-css) |
| 82 * [Moving elements within the DOM tree](#moving-elements) | 82 * [Moving elements within the DOM tree](#moving-elements) |
| 83 * [Other resources](#other-resources) | 83 * [Other resources](#other-resources) |
| 84 * [What next?](#what-next) |
| 84 | 85 |
| 85 ##Copy and run the todo app {#copy-app} | 86 ##Copy and run the todo app {#copy-app} |
| 86 | 87 |
| 87 In this target, you will be working with a sample web app | 88 In this tutorial, you will be working with a sample web app |
| 88 that is a partial implementation of a todo list. | 89 that is a partial implementation of a todo list. |
| 89 This program dynamically changes the DOM, | 90 This program dynamically changes the DOM, |
| 90 and therefore the web page, | 91 and therefore the web page, |
| 91 by adding elements to the DOM tree. | 92 by adding elements to the DOM tree. |
| 92 | 93 |
| 93 **Try it!** Type in the text field and press return. | 94 **Try it!** Type in the text field and press return. |
| 94 The app adds an item to the list. | 95 The app adds an item to the list. |
| 95 Enter a few items into the input field: | 96 Enter a few items into the input field: |
| 96 | 97 |
| 97 <iframe class="running-app-frame" | 98 <iframe class="running-app-frame" |
| 98 style="height:250px;width:300px;" | 99 style="height:250px;width:300px;" |
| 99 src="http://dart-lang.github.io/dart-tutorials-samples/web/target03/todo
/web/todo.html"> | 100 src="examples/todo/todo.html"> |
| 100 </iframe> | 101 </iframe> |
| 101 | 102 |
| 102 You can find the complete source code for this sample on github at | |
| 103 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/tar
get03/todo" | |
| 104 target="_blank">todo</a>. | |
| 105 | |
| 106 This is the beginning of an app to manage a list of things to do. | 103 This is the beginning of an app to manage a list of things to do. |
| 107 Right now, this app is for procrastinators only | 104 Right now, this app is for procrastinators only |
| 108 because the program can only add items to your to do list | 105 because the program can only add items to your to do list |
| 109 but not remove them. | 106 but not remove them. |
| 110 | 107 |
| 111 ##About parent and child Elements in Dart {#tree-structure} | 108 ##About parent and child Elements in Dart {#tree-structure} |
| 112 | 109 |
| 113 The Node class in Dart implements the basic treeing behavior | 110 The Node class in Dart implements the basic treeing behavior |
| 114 for nodes in the Dart DOM. | 111 for nodes in the Dart DOM. |
| 115 The Element class is a subclass of Node that implements | 112 The Element class is a subclass of Node that implements |
| 116 the behavior specific to page element nodes. | 113 the behavior specific to page element nodes. |
| 117 For example, | 114 For example, |
| 118 an element knows the width and height of | 115 an element knows the width and height of |
| 119 its enclosing rectangle on the page | 116 its enclosing rectangle on the page |
| 120 and it can receive events. | 117 and it can receive events. |
| 121 | 118 |
| 122 You can manipulate the DOM tree by adding and deleting nodes. | 119 You can manipulate the DOM tree by adding and deleting nodes. |
| 123 However, many Dart apps are concerned only with page elements. | 120 However, many Dart apps are concerned only with page elements. |
| 124 So for convenience and code simplicity, | 121 So for convenience and code simplicity, |
| 125 the Element class implements API | 122 the Element class implements API |
| 126 for interacting with | 123 for interacting with |
| 127 a subset of the DOM that includes | 124 a subset of the DOM that includes |
| 128 only the nodes that are Elements. | 125 only the nodes that are Elements. |
| 129 You can work with a virtual tree of Elements | 126 You can work with a virtual tree of Elements |
| 130 rather than the more complex tree of Nodes. | 127 rather than the more complex tree of Nodes. |
| 131 This target shows you how to manipulate the | 128 This tutorial shows you how to manipulate the |
| 132 DOM through the Element class. | 129 DOM through the Element class. |
| 133 | 130 |
| 134 An Element has a parent Element | 131 An Element has a parent Element |
| 135 and maintains references to its child Elements in a list. | 132 and maintains references to its child Elements in a list. |
| 136 | 133 |
| 137  | 134  |
| 138 | 135 |
| 139 An Element has at most one parent Element. | 136 An Element has at most one parent Element. |
| 140 An Element's parent is final and cannot be changed. | 137 An Element's parent is final and cannot be changed. |
| 141 So you cannot move an Element by changing its parent. | 138 So you cannot move an Element by changing its parent. |
| 142 Get an Element's parent with the getter `parent`. | 139 Get an Element's parent with the getter `parent`. |
| 143 For example, if you have an Element with the name `anElement` | 140 For example, if you have an Element with the name `anElement` |
| 144 you would refer to its parent element with `anElement.parent`. | 141 you would refer to its parent element with `anElement.parent`. |
| 145 | 142 |
| 146  | 143  |
| 147 | 144 |
| 148 An Element maintains references to its child elements in a list. | 145 An Element maintains references to its child elements in a list. |
| 149 List is a class in the dart:core library | 146 <a href="https://api.dartlang.org/dart_core/List.html" target="_blank">List</a> |
| 147 is a class in the dart:core library |
| 150 that implements an indexable collection with a length. | 148 that implements an indexable collection with a length. |
| 151 A list can be of fixed size or extendable. | 149 A list can be of fixed size or extendable. |
| 152 | 150 |
| 153 List is an example of a _generic_ (or _parameterized_) type—a type | 151 List is an example of a _generic_ (or _parameterized_) type—a type |
| 154 that can declare formal type parameters. | 152 that can declare formal type parameters. |
| 155 This means that a list can be declared | 153 This means that a list can be declared |
| 156 to contain only objects of a particular type. | 154 to contain only objects of a particular type. |
| 157 For example: | 155 For example: |
| 158 | 156 |
| 159 | List declaration | List description| | 157 | List declaration | List description| |
| (...skipping 131 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 291 | 289 |
| 292 The addToDoItem() function ignores the Event object passed to it. | 290 The addToDoItem() function ignores the Event object passed to it. |
| 293 | 291 |
| 294 ##Adding an element to the DOM tree {#add-elem} | 292 ##Adding an element to the DOM tree {#add-elem} |
| 295 | 293 |
| 296 The change event handler has the following code: | 294 The change event handler has the following code: |
| 297 | 295 |
| 298  | 296  |
| 299 | 297 |
| 300 The final line of code is where the DOM gets changed. | 298 The final line of code is where the DOM gets changed. |
| 301 The add() method is defined in the List class in the dart:core library. | |
| 302 | 299 |
| 303 An Element keeps references to all of its children in a list called `children`. | 300 An Element keeps references to all of its children in a list called `children`. |
| 304 By adding and removing elements to and from this list, | 301 By adding and removing elements to and from this list, |
| 305 your code changes the DOM. | 302 the code changes the DOM. |
| 306 When the DOM changes, the browser re-renders the browser page. | 303 When the DOM changes, the browser re-renders the browser page. |
| 307 The effect, in our todo app, is that a new bullet item appears | 304 The effect, in our todo app, is that a new bullet item appears |
| 308 in the to do list. | 305 in the to do list. |
| 309 | 306 |
| 310 ##Styling the page elements {#about-css} | 307 ##Styling the page elements {#about-css} |
| 311 | 308 |
| 312 Let's take a look at the CSS file for this app. | 309 Let's take a look at the CSS file for this app. |
| 313 | 310 |
| 314  | 311  |
| 315 | 312 |
| (...skipping 12 matching lines...) Expand all Loading... |
| 328 element with the ID to-do-list, thus styling | 325 element with the ID to-do-list, thus styling |
| 329 each item in the to do list. | 326 each item in the to do list. |
| 330 | 327 |
| 331 ##Moving elements within the DOM tree {#moving-elements} | 328 ##Moving elements within the DOM tree {#moving-elements} |
| 332 | 329 |
| 333 Here's an example that shows how to move an element within the DOM. | 330 Here's an example that shows how to move an element within the DOM. |
| 334 **Try it!** Form a word by clicking the letter tiles. | 331 **Try it!** Form a word by clicking the letter tiles. |
| 335 | 332 |
| 336 <iframe class="running-app-frame" | 333 <iframe class="running-app-frame" |
| 337 style="height:400px;width:400px;" | 334 style="height:400px;width:400px;" |
| 338 src="http://dart-lang.github.io/dart-tutorials-samples/web/target03/anag
ram/web/anagram.html"> | 335 src="examples/anagram/anagram.html"> |
| 339 </iframe> | 336 </iframe> |
| 340 | 337 |
| 341 You can find the complete source code for this sample on github at | |
| 342 <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/tar
get03/anagram" | |
| 343 target="_blank">anagram</a>. | |
| 344 | |
| 345 When the program starts, | 338 When the program starts, |
| 346 it creates one button element for each of seven | 339 it creates one button element for each of seven |
| 347 randomly selected letters. | 340 randomly selected letters. |
| 348 The program adds each button to a DOM element—a simple | 341 The program adds each button to a DOM element—a simple |
| 349 <div> element identified by the CSS selector `letterpile`—with | 342 <div> element identified by the CSS selector `letterpile`—with |
| 350 a call to letterpile.children.add(). | 343 a call to letterpile.children.add(). |
| 351 | 344 |
| 352  | 345  |
| 353 | 346 |
| 354 Each button element in the letter pile | 347 Each button element in the letter pile |
| (...skipping 20 matching lines...) Expand all Loading... |
| 375 <a href="/docs/cookbook/"> | 368 <a href="/docs/cookbook/"> |
| 376 <i class="icon-food"> </i> Dart Cookbook</a>, | 369 <i class="icon-food"> </i> Dart Cookbook</a>, |
| 377 where you'll find many recipes about manipulating the DOM | 370 where you'll find many recipes about manipulating the DOM |
| 378 and using CSS. | 371 and using CSS. |
| 379 The cookbook also has recipes about basic Dart data types, | 372 The cookbook also has recipes about basic Dart data types, |
| 380 such strings, lists, maps, and numbers. | 373 such strings, lists, maps, and numbers. |
| 381 </li> | 374 </li> |
| 382 | 375 |
| 383 <li> | 376 <li> |
| 384 You can find more information about the DOM and CSS in | 377 You can find more information about the DOM and CSS in |
| 385 <a href="/docs/dart-up-and-running/">Dart Up and Running</a>, | 378 <a href="/docs/dart-up-and-running/">Dart: Up and Running</a>, |
| 386 which also provides thorough coverage of the Dart language, | 379 which also provides thorough coverage of the Dart language, |
| 387 libraries, and tools. | 380 libraries, and tools. |
| 388 </li> | 381 </li> |
| 389 </ul> | 382 </ul> |
| 390 | 383 |
| 384 ##What next? |
| 385 |
| 386 The next tutorial, [Remove DOM Elements](/docs/tutorials/remove-elements/), |
| 387 describes how to remove elements from the DOM and items off your todo list. |
| 388 |
| 391 {% endcapture %} | 389 {% endcapture %} |
| 392 | 390 |
| 393 {% include tutorial.html %} | 391 {% include tutorial.html %} |
| OLD | NEW |