Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(170)

Side by Side Diff: src/site/docs/tutorials/add-elements/index.markdown

Issue 26542002: edit pass on T3,4,5, updated images (Closed) Base URL: https://github.com/dart-lang/dartlang.org.git@master
Patch Set: merging with master Created 7 years, 2 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
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 ![An element with multiple child elements and a parent element](images/relations hips.png) 134 ![An element with multiple child elements and a parent element](images/relations hips.png)
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 ![Dart code reference to anElement's parent](images/parent-reference.png) 143 ![Dart code reference to anElement's parent](images/parent-reference.png)
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&mdash;a type 151 List is an example of a _generic_ (or _parameterized_) type&mdash;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
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 ![The addToDoItem() function explained](images/add-element-code.png) 296 ![The addToDoItem() function explained](images/add-element-code.png)
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 ![The effect of CSS styles](images/css-code.png) 311 ![The effect of CSS styles](images/css-code.png)
315 312
(...skipping 12 matching lines...) Expand all
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&mdash;a simple 341 The program adds each button to a DOM element&mdash;a simple
349 &lt;div&gt; element identified by the CSS selector `letterpile`&mdash;with 342 &lt;div&gt; element identified by the CSS selector `letterpile`&mdash;with
350 a call to letterpile.children.add(). 343 a call to letterpile.children.add().
351 344
352 ![Dart code populates the letter pile with buttons](images/anagram-newletters.pn g) 345 ![Dart code populates the letter pile with buttons](images/anagram-newletters.pn g)
353 346
354 Each button element in the letter pile 347 Each button element in the letter pile
(...skipping 20 matching lines...) Expand all
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 %}
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698