` element identified by the CSS selector `letterpile`—with
+a call to `letterpile.children.add()`.
Each button element in the letter pile
-has a mouse click handler called moveLetter().
-If the button is in the letterpile,
+has a mouse click handler called `moveLetter()`.
+If the button is in the letter pile,
the mouse click handler moves the button to the end of the word.
If the button is in the word,
the mouse click handler moves the button back to the letter pile.
@@ -441,7 +518,7 @@ The `+=` operator is a compound assignment operator,
which combines an operation (`+`) with an assignment.
The `scrabbleValues` variable is a
-
Map—a
+[`Map`]({{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/Map-class.html){:target="_blank" rel="noopener"}—a
data structure that contains key/value pairs.
Use the square bracket syntax to retrieve a value by its key
and the `length` property to get the number of pairs it contains.
diff --git a/src/_tutorials/web/low-level-html/connect-dart-html.md b/src/_tutorials/web/low-level-html/connect-dart-html.md
index 1b4c836833..899e246cff 100644
--- a/src/_tutorials/web/low-level-html/connect-dart-html.md
+++ b/src/_tutorials/web/low-level-html/connect-dart-html.md
@@ -1,13 +1,11 @@
---
title: Connect Dart and HTML
-description: Shows basic scaffolding of a Dart web app.
+description: Learn how to set up basic scaffolding of a Dart web app.
nextpage:
url: /tutorials/web/low-level-html/add-elements
title: Add elements to the DOM
---
-{% include not-null-safe.md %}
-
This tutorial is the first of a series on
basic, low-level web programming with the dart:html library.
If you use a web framework,
@@ -23,7 +21,7 @@ but you might not need to use the dart:html library at all.
* Compile a web app's Dart code to JavaScript to run the app in any modern browser.
* An HTML file hosts your Dart code in a browser page.
* The DOM models a browser page in a tree/node structure.
-* Use querySelector() with an ID to get an element from the DOM.
+* Use `querySelector()` with an ID to get an element from the DOM.
* CSS selectors are patterns used to select matching elements in the DOM.
* Use CSS rules to style elements.
@@ -31,7 +29,7 @@ but you might not need to use the dart:html library at all.
To write a low-level web app with Dart,
you need to understand
-several topics—the DOM tree, nodes, elements,
+several topics—the DOM tree, nodes, elements,
HTML, and the Dart language and libraries.
The interdependencies are circular,
@@ -54,17 +52,17 @@ for more interesting and useful web apps.
## About the Dart, HTML, and CSS triumvirate {#source-files}
If you've used
-
DartPad,
-you've already seen the DART, HTML, and CSS tabs
+[DartPad]({{site.dartpad}}){:target="_blank" rel="noopener"},
+you may have already seen the Dart, HTML, and CSS tabs
that let you write the code for a web app.
Each of these three languages
is responsible for a different aspect of the web app.
-| Language | Purpose |
-|---|---|
-| Dart | Implements the interactivity and dynamic behavior of the web app |
-| HTML | Describes the content of the web app's page (the elements in the document and the structure) |
-| CSS | Governs the appearance of page elements |
+| Language | Purpose |
+|----------|----------------------------------------------------------------------------------------------|
+| Dart | Implements the interactivity and dynamic behavior of the web app |
+| HTML | Describes the content of the web app's page (the elements in the document and the structure) |
+| CSS | Governs the appearance of page elements |
{: .table}
A Dart program can
@@ -104,12 +102,11 @@ the resulting web browser page in Chrome.
HTML uses tags to describe the document.
For example, the simple HTML code above
-uses the \
tag for the page title,
-\<h1> for a level-one header,
-and \<p> for a paragraph.
+uses the `<title>` tag for the page title,
+`<h1>` for a level-one header,
+and `<p>` for a paragraph.
Some tags in the HTML code,
-such as
-\<head> and \<body>,
+such as `<head>` and `<body>`,
are not visible on the web page,
but do contribute to the structure of the document.
@@ -123,9 +120,9 @@ text nodes, and attribute nodes.
Here is the DOM tree for the simple HTML file above.
<img class="scale-img-max" src="/tutorials/web/images/simple-dom-tree.png"
- alt="The DOM tree for a simple HTML file">
+ alt="A Dart dynamically changing the DOM">
-Notice that some tags, such as the \<p> paragraph tag,
+Notice that some tags, such as the `<p>` paragraph tag,
are represented by multiple nodes.
The paragraph itself is an element node.
The text within the paragraph is a text node
@@ -153,7 +150,7 @@ or even insert an entire subtree of nodes.
## Create a new Dart app {#create-dart-app}
-1. Go to <a href="{{site.dartpad}}" target="_blank" rel="noopener">DartPad.</a>
+1. Go to the [DartPad]({{site.dartpad}}){:target="_blank" rel="noopener"}.
2. Click the **New Pad** button to undo any changes you might have made
the last time you visited DartPad.
3. Click **Dart**.
@@ -162,27 +159,27 @@ or even insert an entire subtree of nodes.
{{site.alert.note}}
These instructions feature DartPad,
- which hides some of the HTML boilerplate code.
+ which hides some HTML boilerplate code.
If you want to use any other editor,
then we recommend starting with a small Dart web app sample
- and modifying the non-script tags inside the \<body> section.
+ and modifying the non-script tags inside the `<body>` section.
[HTML and Dart connections](#connections) shows the full HTML code.
{{site.alert.end}}
## Edit the HTML source code {#create-html}
1. Click **HTML**, at the upper left of DartPad.
- The view switches from Dart code to the (non-existent) HTML code.
+ The view switches from Dart code to the (currently non-existent) HTML code.
2. Add the following HTML code:
- {% prettify html tag=pre+code %}
+ ```html
<p id="RipVanWinkle">
RipVanWinkle paragraph.
</p>
- {% endprettify %}
+ ```
-3. Click **HTML OUTPUT** to see how a browser would render your HTML.
+3. Expand the output pane to see how a browser would render your HTML.
## About the HTML source code {#about-html-code}
@@ -191,41 +188,39 @@ This HTML code is similar to the HTML code in the
various diagrams earlier in this tutorial,
but it's even simpler.
-In DartPad you need only the tags you really care about—in
-this case, \<p>.
-You don't need surrounding tags such as
-\<html> and \<body>.
+In DartPad you need only the tags you really care about—in this case: `<p>`.
+You don't need surrounding tags such as `<html>` and `<body>`.
Because DartPad knows where your Dart code is,
-you don't need a \<script> tag.
+you don't need a `<script>` tag.
{{site.alert.info}}
[HTML and Dart connections](#connections) shows the full HTML code
- that you need to run your web app outside of DartPad.
+ that you need to run your web app outside DartPad.
{{site.alert.end}}
-The paragraph tag has the identifier "RipVanWinkle".
+The paragraph tag has the identifier `RipVanWinkle`.
The Dart code you create in the next step uses this ID
to get the paragraph element.
## Edit the Dart source code {#dart-editor-happiness}
-1. Click **DART**, at the upper right of DartPad.
+1. Click **Dart** at the upper right of DartPad.
The view switches from HTML code to Dart code.
2. Change the Dart code to the following:
- {% prettify dart tag=pre+code %}
+ ```dart
import 'dart:html';
void main() {
- querySelector('#RipVanWinkle').text = 'Wake up, sleepy head!';
+ querySelector('#RipVanWinkle')!.text = 'Wake up, sleepy head!';
}
- {% endprettify %}
+ ```
3. Click **Run** to execute your code.
-The text in the HTML OUTPUT tab changes to "Wake up, sleepy head!"
+The text in the output pane changes to "Wake up, sleepy head!"
## About the Dart source code {#about-dart-code}
@@ -235,64 +230,106 @@ Let's step through the Dart code.
### Importing libraries
The import directive imports the specified library,
-making all of the classes and functions
+making all the classes and functions
in that library
available to your program.
-<pre class="prettyprint lang-dart allow-scroll">
-<a href="#" class="dart-popover" data-toggle="popover" data-html="true" data-trigger="hover focus" data-content="Imports Dart's HTML classes and functions">import 'dart:html';</a>
-</pre>
+The following `import` statement imports Dart's HTML library,
+which contains key classes and functions for programming the DOM:
+
+```dart
+import 'dart:html';
+```
This program imports Dart's HTML library,
which contains key classes and functions for programming the DOM.
Key classes include:
-| Dart class | Description |
-|---|---|
-| <a href="{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Node-class.html" target="_blank" rel="noopener">Node</a> | Implements a DOM node. |
-| <a href="{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Element-class.html" target="_blank" rel="noopener">Element</a> | A subclass of Node; implements a web page element. |
+| Dart class | Description |
+|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
+| <a href="{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Node-class.html" target="_blank" rel="noopener">Node</a> | Implements a DOM node. |
+| <a href="{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Element-class.html" target="_blank" rel="noopener">Element</a> | A subclass of Node; implements a web page element. |
| <a href="{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Document-class.html" target="_blank" rel="noopener">Document</a> | Another subclass of Node; implements the document object. |
{: .table}
-The Dart core library contains another useful class:
-<a href="{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/List-class.html" target="_blank" rel="noopener">List,</a>
+The `dart:core` library, which is automatically imported,
+contains many other useful classes, such as:
+[`List`]({{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/List-class.html){:target="_blank" rel="noopener"},
a parameterized class that can specify the type of its members.
-An instance of Element keeps its list of child Elements
-in a List\<Element>.
+An instance of `Element` keeps its list of child Element objects
+in a `List<Element>`.
### Using the querySelector() function
-This app's main() function contains a single
+This app's `main()` function contains a single
line of code that is a little like a run-on sentence
with multiple things happening one after another.
Let's deconstruct it.
-querySelector() is a top-level function provided by the Dart HTML library
-that gets an Element object from the DOM.
+`querySelector()` is a top-level function provided by the `dart:html` library
+that gets an `Element` object from the DOM.
-<pre class="prettyprint lang-dart allow-scroll">
-<a href="#" class="dart-popover" data-toggle="popover" data-html="true" data-trigger="hover focus" data-content="Returns the matching Element">querySelector('#RipVanWinkle')</a>.text = 'Wake up, sleepy head!';
-</pre>
+{% prettify dart tag=pre+code %}
+[!querySelector!]('#RipVanWinkle')!.text = 'Wake up, sleepy head!';
+{% endprettify %}
-The argument to querySelector(), a string,
-is a CSS selector that identifies the object.
+The argument to `querySelector()` is a string
+containing a CSS selector that identifies the object.
Most commonly CSS selectors specify classes, identifiers, or attributes.
We'll look at these in more detail later,
when we add a CSS file to the mini app.
In this case, RipVanWinkle is the unique ID for a paragraph element
declared in the HTML file,
-and #RipVanWinkle specifies that ID.
-
-<pre class="prettyprint lang-dart allow-scroll">
-querySelector(<a href="#" class="dart-popover" data-toggle="popover" data-html="true" data-trigger="hover focus" data-content="ID from HTML file">'#RipVanWinkle'</a>).text = 'Wake up, sleepy head!';
-</pre>
+and `#RipVanWinkle` specifies that ID.
Another useful function for getting elements from the DOM
-is querySelectorAll(),
-which returns multiple Element objects via
-a list of elements—List<Element>—all
+is `querySelectorAll()`,
+which returns multiple `Element` objects via
+a list of elements—`List<Element>`—all
of which match the provided selector.
+### Handling nullable elements
+
+Because DOM elements might be missing,
+the `querySelector()` function returns a nullable result,
+as indicated by the `?` in the function's return type (`Element?`).
+A `null` return value means that
+no element matches the specified CSS selector.
+
+To use the `text` property of a returned `Element?`,
+the type must be promoted to `Element`.
+Because we wrote the HTML and know that the element is always present,
+we can use the
+[null assertion operator](/null-safety/understanding-null-safety#null-assertion-operator) (`!`)
+when referring to the element's properties:
+
+{% prettify dart tag=pre+code %}
+querySelector('#RipVanWinkle')[!!!].text = 'Wake up, sleepy head!';
+{% endprettify %}
+
+If the element with the `#RipVanWinkle` ID
+isn't guaranteed to be present in the DOM,
+you can instead use the conditional member access operator (`?.`)
+to set `text` only if the returned element is not `null`:
+
+{% prettify dart tag=pre+code %}
+querySelector('#RipVanWinkle')[!?!].text = 'Wake up, sleepy head!';
+{% endprettify %}
+
+If you plan to access the element multiple times
+and know its type,
+another option is to
+[typecast](/guides/language/language-tour#type-test-operators)
+the queried element to the expected type:
+
+{% prettify dart tag=pre+code %}
+final paragraph = querySelector('#RipVanWinkle') [!as ParagraphElement!];
+paragraph.text = 'Wake up, sleepy head!';
+{% endprettify %}
+
+To learn more about nullable types and null safety in general,
+see [Sound null safety](/null-safety).
+
### Setting the text of an Element
In the DOM, the text of a page element is contained
@@ -312,12 +349,12 @@ would be represented with a subtree of text nodes and other objects.
In Dart,
you can simply use the Element `text` property,
-which has a getter
-that walks the subtree of nodes for you and extracts their text.
+which has a getter and setter
+that walk the subtree of nodes for you and extract or set their text:
-<pre class="prettyprint lang-dart allow-scroll">
-querySelector('#RipVanWinkle')<a href="#" class="dart-popover" data-toggle="popover" data-html="true" data-trigger="hover focus" data-content="Convenience API to the Element's text">.text</a> = 'Wake up, sleepy head!';
-</pre>
+{% prettify dart tag=pre+code %}
+querySelector('#RipVanWinkle')![!.text!] = 'Wake up, sleepy head!';
+{% endprettify %}
However, if the text node has styles (and thus a subtree),
getting text and then setting it immediately is likely
@@ -325,17 +362,17 @@ to change the DOM, as a result of losing subtree information.
Often, as with our RipVanWinkle example,
this simplification has no adverse effects.
-The assignment operator (=) sets the text
-of the Element returned by the querySelector() function
+The assignment operator (`=`) sets the text
+of the `Element` returned by the `querySelector()` function
to the string "Wake up, sleepy head!".
-<pre class="prettyprint lang-dart allow-scroll">
-querySelector('#RipVanWinkle').text <a href="#" class="dart-popover" data-toggle="popover" data-html="true" data-trigger="hover focus" data-content="Dynamically changes the DOM">=</a> 'Wake up, sleepy head!';
-</pre>
+{% prettify dart tag=pre+code %}
+querySelector('#RipVanWinkle')!.text [!=!] 'Wake up, sleepy head!';
+{% endprettify %}
This causes the browser to immediately re-render
-the browser page containing this app, thus
-dynamically displaying the text on the browser page.
+the browser page containing this app,
+thus dynamically displaying the text on the browser page.
## HTML and Dart connections {#connections}
@@ -350,27 +387,24 @@ from a Dart app to a browser page.
In DartPad, the only visible connection between
the Dart code and the HTML code
-is the RipVanWinkle ID.
+is the `RipVanWinkle` ID.
<img class="scale-img-max" src="/tutorials/web/images/dart-html-connect.png"
alt="The RipVanWinkle ID is used by both Dart and HTML">
-To run your app outside of DartPad, you need to compile your Dart
-code to JavaScript. [Use the **webdev build** command][build]
+To run your app outside DartPad,
+you need to compile your Dart code to JavaScript.
+Use the [`webdev build`][build] command
to compile your app to deployable JavaScript.
Then you need to make another connection between the HTML and
-generated JavaScript: you must add a \<script> tag to the HTML
+generated JavaScript:
+you must add a `<script>` tag to the HTML
to tell the browser where to find the compiled Dart code.
-{% comment %}
-PENDING: We should include or link to instructions
-on how to convert a DartPad app into one you can run in the browser.
-{% endcomment %}
-
Here's the full HTML code for this app,
assuming that the Dart code is in a file named `main.dart`:
-```dart
+```html
<!DOCTYPE html>
<html>
@@ -394,26 +428,26 @@ Most HTML uses cascading style sheets (CSS) to define _styles_
that control the appearance of page elements.
Let's customize the CSS for the mini app.
-1. Click **CSS**.
+1. Click **CSS** at the upper left of DartPad.
The view switches from Dart code to the (non-existent) CSS code.
2. Add the following CSS code:
- {% prettify none tag=pre+code %}
+ ```css
#RipVanWinkle {
font-size: 20px;
- font-family: 'Open Sans', sans-serif;
+ font-family: 'Roboto', sans-serif;
text-align: center;
margin-top: 20px;
background-color: SlateBlue;
color: Yellow;
}
- {% endprettify %}
+ ```
-The display under HTML OUTPUT immediately changes
+The display in the output pane immediately changes
to reflect the new styles,
which apply only to the page element
-that has the ID RipVanWinkle.
+that has the ID `RipVanWinkle`.
## About CSS selectors {#about-css-selectors}
@@ -421,7 +455,7 @@ that has the ID RipVanWinkle.
IDs, classes, and other information about elements
are established in HTML.
Your Dart code can use this information
-to get elements using a CSS selector—a pattern
+to get elements using a CSS selector—a pattern
used to select matching elements in the DOM.
CSS selectors allow the CSS, HTML, and Dart code
to refer to the same objects.
@@ -431,27 +465,27 @@ a class, or an attribute.
Selectors can also be nested.
CSS selectors are important in Dart programs
-because you use them with querySelector() and querySelectorAll()
+because you use them with `querySelector()` and `querySelectorAll()`
to get matching elements from the DOM.
-Most often Dart programs use ID selectors with querySelector()
-and class selectors with querySelectorAll().
+Most often Dart programs use ID selectors with `querySelector()`
+and class selectors with `querySelectorAll()`.
Here are some examples of CSS selectors:
-| Selector type | Example | Description |
-|---|---|
-| ID selector | #RipVanWinkle | Matches a single, unique element |
-| HTML element | p | Matches all paragraphs |
-| HTML element | h1 | Matches all level-one headers |
-| Class | _.classname_ | Matches all items with the class _classname_ |
-| Asterisk | * | Matches all elements |
-| Attribute | input[type="button"] | Matches all button input elements |
+| Selector type | Example | Description |
+|---------------|----------------------------------|----------------------------------------------|
+| ID selector | `#RipVanWinkle` | Matches a single, unique element |
+| HTML element | `p` | Matches all paragraphs |
+| HTML element | `h1` | Matches all level-one headers |
+| Class | <code>.<em>classname</em></code> | Matches all items with the class _classname_ |
+| Asterisk | `*` | Matches all elements |
+| Attribute | `input[type="button"]` | Matches all button input elements |
{: .table}
{{site.alert.tip}}
As you saw,
the mini app used a CSS selector,
- the ID `#RipVanWinkle`,
+ the ID `RipVanWinkle`,
even when there was no CSS file.
You do not need a CSS file for a Dart program.
Nor do you need a CSS file to use CSS selectors.
@@ -467,19 +501,19 @@ A CSS rule has two main parts: a selector and a set of declarations.
<img class="scale-img-max" src="/tutorials/web/images/css-rule-explained.png"
alt="The parts of a CSS rule">
-In the mini app, the selector #RipVanWinkle is an ID selector,
-as signaled by the hash tag (#);
+In the mini app, the selector `#RipVanWinkle` is an ID selector,
+as signaled by the hashtag (`#`);
it matches a single, unique element with the specified ID,
-our now tired RipVanWinkle paragraph element.
-RipVanWinkle is the ID in the HTML file.
+our now tired `RipVanWinkle` paragraph element.
+`RipVanWinkle` is the ID in the HTML file.
It is referred to in the CSS file and in the Dart code
-using a hash tag(#).
-Classnames are specified in the HTML file without a period (.)
-and referred to in the CSS file and in Dart code with a period (.).
+using a hashtag(`#`).
+Classnames are specified in the HTML file without a period (`.`)
+and referred to in the CSS file and in Dart code with a period (`.`).
Between the curly brackets of a CSS rule is
a list of declarations,
-each of which ends in a semi-colon (;).
+each of which ends in a semi-colon (`;`).
Each declaration specifies a property and its value.
Together the set of declarations define the _style sheet_
for all matching elements.
@@ -489,20 +523,18 @@ of the matching element(s) on the web page.
<img class="scale-img-max" src="/tutorials/web/images/css-property-value.png"
alt="A declaration specifies an attribute and its value">
-The CSS rule for the RipVanWinkle paragraph
+The CSS rule for the `RipVanWinkle` paragraph
specifies several properties;
for example, it sets the text color to Yellow.
## Other resources
-{% comment %}
-PENDING: Link to WebStorm docs? DartPad docs?
-{% endcomment %}
-
-* The <a href="/guides/language/language-tour">language tour</a>
+* The [language tour](/guides/language/language-tour)
provides thorough coverage of the Dart language.
-* <a href="/tools">Dart tools page</a>
+* The Dart [tools page](/tools)
lists IDEs and editors that have Dart plugins.
+* The [DartPad documentation](/tools/dartpad)
+ walks through the basics of using the DartPad web editor.
## What next?
diff --git a/src/_tutorials/web/low-level-html/remove-elements.md b/src/_tutorials/web/low-level-html/remove-elements.md
index 06c134f0f9..4c808410c7 100644
--- a/src/_tutorials/web/low-level-html/remove-elements.md
+++ b/src/_tutorials/web/low-level-html/remove-elements.md
@@ -1,25 +1,30 @@
---
title: Remove DOM elements
-description: Remove a child element from the DOM.
+description: Learn how to set up basic scaffolding of a Dart web app.
+js: [{url: 'https://dartpad.dev/inject_embed.dart.js', defer: true}]
prevpage:
url: /tutorials/web/low-level-html/add-elements
title: Add elements to the DOM
---
-{% include not-null-safe.md %}
-
<div class="panel" markdown="1">
#### <a id="whats-the-point" class="anchor" href="#whats-the-point" aria-hidden="true"><span class="octicon octicon-link"></span></a>What's the point?
-* Use _element_.remove() to remove an element from the DOM.
-* Remove all children from an element with _element_.children.clear().
+* Use `element.remove()` to remove an element from the DOM.
+* Remove all children from an element with `element.children.clear()`.
* Function expressions are a convenient way to define single-use functions.
-* => is a shorthand syntax for defining functions that contain just one expression.
+* `=>` is a shorthand syntax for defining functions that contain just one expression.
</div>
+
+{{site.alert.note}}
+ This page uses embedded DartPads to display runnable examples.
+ {% include dartpads-embedded-troubleshooting.md %}
+{{site.alert.end}}
+
This tutorial shows you how to delete elements from the DOM.
A new and improved version of the todo app from
[the previous tutorial](add-elements)
@@ -31,92 +36,128 @@ either one at a time, or all at once.
Below is a revised version
of the todo app from the previous tutorial
that allows you to delete items.
-Stop procrastinating and remove items from your to do list.
-
-{% comment %}
-https://gist.github.com/Sfshaza/582b9a8d36786566ba08
-------------------------------------------------------------------
-main.dart:
-------------------------------------------------------------------
-
-// Copyright (c) 2012, the Dart project authors.
-// Please see the AUTHORS file for details.
-// All rights reserved. Use of this source code
-// is governed by a BSD-style license that can be
-// found in the LICENSE file.
+**Try it!**
+Click **Run** to start the web app.
+Then type in the app's input field, and press the return key;
+a new item appears in the list.
+Enter a few more items.
+Point the mouse cursor at one of the items in the list;
+the item turns red and gets slightly larger.
+Click it and it disappears from the list.
+Use the **Delete All** button
+to remove all the items in the list at once.
+```dart:run-dartpad:mode-html:ga_id-try_the_app
+{$ begin main.dart $}
import 'dart:html';
-InputElement toDoInput;
-UListElement toDoList;
-ButtonElement deleteAll;
+final InputElement toDoInput = querySelector('#to-do-input') as InputElement;
+final UListElement toDoList = querySelector('#to-do-list') as UListElement;
+final ButtonElement deleteAll = querySelector('#delete-all') as ButtonElement;
void main() {
- toDoInput = querySelector('#to-do-input');
- toDoList = querySelector('#to-do-list');
toDoInput.onChange.listen(addToDoItem);
- deleteAll = querySelector('#delete-all');
- deleteAll.onClick.listen((e) =>
- toDoList.children.clear());
+ deleteAll.onClick.listen((_) => toDoList.children.clear());
}
void addToDoItem(Event e) {
- var newToDo = new LIElement();
- newToDo.text = toDoInput.value;
- newToDo.onClick.listen((e) => newToDo.remove());
+ final newToDo = LIElement()..text = toDoInput.value;
+ newToDo.onClick.listen((_) => newToDo.remove());
toDoInput.value = '';
toDoList.children.add(newToDo);
}
-{% endcomment %}
+{$ end main.dart $}
+{$ begin index.html $}
+<h2>Todo</h2>
+
+<div>
+ <input id="to-do-input" type="text" placeholder="What needs to be done?">
+</div>
+
+<div>
+ <ul id="to-do-list">
+ </ul>
+</div>
-**Try it!**
-Click **Run** to start the web app.
-Then type in the app's input field, and press the return key;
-a new item appears in the list.
-Enter a few more items.
-Point the mouse cursor at one of the items in the list;
-the item turns red and gets slightly larger.
-Click it and it disappears from the list.
-Use the **Delete All** button
-to remove all of the items in the list at once.
+<button id="delete-all" type="button" style="float:right">Delete All</button>
+{$ end index.html $}
+{$ begin styles.css $}
+body {
+ font-family: 'Roboto', sans-serif;
+ background-color: WhiteSmoke;
+ margin: 15px;
+ color: black;
+}
-{{site.alert.note}}
- {% include dartpad-embedded-troubleshooting.md %}
-{{site.alert.end}}
+h2 {
+ color: black;
+}
+
+#to-do-input {
+ font-family: 'Roboto', sans-serif;
+ font-size: 14px;
+ font-weight: normal;
+ padding: 5px 0px 5px 5px;
+ width: 100%;
+ border: 1px solid Silver;
+ background-color: White;
+}
-<iframe
-src="{{site.dartpad-embed-html}}?id=582b9a8d36786566ba08&ga_id=try_the_app"
- width="100%"
- height="500px"
- style="border: 1px solid #ccc;">
-</iframe>
+#to-do-list {
+ padding: 0;
+ margin: 0;
+ list-style-position: inside;
+}
+
+#to-do-list li {
+ padding: 5px 0px 5px 5px;
+ border-bottom: 1px dotted Silver;
+}
+
+#to-do-list li:hover {
+ color: blue;
+ cursor: pointer;
+}
+
+#delete-all {
+ margin-top: 8px;
+ background-color: #F8F8F8;
+ border: 1px dotted #ccc;
+ border-radius: 1em;
+ float: right;
+}
+
+#delete-all:hover {
+ background-color: #ddd;
+}
+{$ end styles.css $}
+```
The remaining sections describe
key aspects of the code
added to the todo app for this tutorial.
Specifically, they look at
the Dart code that removes one or more elements from the DOM
-and the CSS code that makes the text red and larger.
+and the CSS code that makes the text blue and larger.
## Changing the appearance when cursor is over an element
-As you saw, an item in the list turns red and gets bigger
+As you saw, an item in the list turns blue and gets bigger
when the user points at it.
The mouse cursor also changes shape.
These visual clues are an important part of the user interface
in this example because they are the only indication to the user
that something will happen when the item is clicked.
-This behavior is coded in the todo_with_delete app's CSS file with this rule:
+This behavior is coded in the app's CSS file with this rule:
-{% prettify dart tag=pre+code %}
+```css
#to-do-list li:hover {
- color: red;
- font-size: 18px;
- cursor:pointer;
+ color: blue;
+ cursor: pointer;
}
-{% endprettify %}
+```
We've used this CSS trick
instead of providing a familiar user interface,
@@ -128,25 +169,24 @@ to keep the code simpler.
An element is removed from
the DOM when it is removed from its parent's list of children.
The
-<a href="{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/List-class.html" target="_blank" rel="noopener">List</a>
-class provides functions for finding an item in the list
+[`List`]({{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/List-class.html){:target="_blank" rel="noopener"}class provides functions for finding an item in the list
and removing it.
But, in this case,
-using the element's remove() function
+using the element's `remove()` function
is shorter and more concise than
-using functions from the List class.
+using functions from the `List` class.
<img class="scale-img-max" src="/tutorials/web/images/remove-element.png"
alt="Use element.remove() to remove an element from the DOM">
-In the todo_with_delete app,
+In the app,
the user clicks an item to delete it.
This is achieved with one line of Dart code.
When a new to do item is created,
the code registers a mouse click handler on the new element.
When the user clicks that new element,
its event handler causes the element to remove itself from the DOM
-with remove().
+with `remove()`.
<img class="scale-img-max" src="/tutorials/web/images/remove-element-code.png"
alt="Registering an event handler to delete an item">
@@ -163,78 +203,72 @@ all elements are removed from the list.
<img class="scale-img-max" src="/tutorials/web/images/remove-all-elements.png"
alt="Use element.children.clear() to remove all of an element's children">
-In this case, using the List class's clear() function
+In this case, using the `List` class's `clear()` function
yields the most concise code.
-Here's the code from the todo_with_delete app
+Here's the code from the app
that implements the **Delete All** button.
-<ol>
-<li markdown="1">
-The HTML code creates a button with the ID delete-all.
-(The CSS styles it.)
-
-{% prettify dart tag=pre+code %}
-<button id="delete-all" type="button" style="float:right"> Delete All </button>
-{% endprettify %}
+1. The HTML code creates a button with the ID `delete-all`.
+ (The CSS styles it.)
-</li>
+ ```html
+ <button id="delete-all" type="button" style="float:right">Delete All</button>
+ ```
-<li markdown="1">
-The Dart code gets the button element from the DOM
-using querySelector() and the button's ID, #delete-all.
-The code registers a mouse click handler on the button;
-the handler removes all of the child elements from the to do list.
-Here is all of the Dart code related to the **Delete All** button.
+2. The Dart code gets the button element from the DOM
+ using `querySelector()` and the button's ID, `delete-all`.
+ The code registers a mouse click handler on the button;
+ the handler removes all of the child elements from the to do list.
+ Here is all the Dart code related to the **Delete All** button.
-<img class="scale-img-max" src="/tutorials/web/images/remove-all-code.png"
- alt="Remove all child elements from an Element">
-
-</li>
-</ol>
+ <img class="scale-img-max" src="/tutorials/web/images/remove-all-code.png"
+ alt="Remove all child elements from an Element">
## About function expressions and =>
-The todo_with_delete app uses
+The app uses
some interesting Dart syntax
when adding an event listener to the **Delete All** button.
-The argument passed into the listen() function
+The argument passed into the `listen()` function
is an example of a _function expression_,
which is a shorthand way of defining functions
-and it uses the => syntax to define the function concisely.
+and it uses the `=>` syntax to define the function concisely.
+For more details,
+see the language tour's coverage of
+[functions](/guides/language/language-tour#functions).
<img class="scale-img-max" src="/tutorials/web/images/event-listener-exp.png"
alt="A one-line function definition">
It is equivalent to writing this:
-{% prettify dart tag=pre+code %}
-deleteAll.onClick.listen((e) {
+```dart
+deleteAll.onClick.listen((_) {
toDoList.children.clear();
});
-{% endprettify %}
+```
or even this:
-{% prettify dart tag=pre+code %}
+```dart
...
void main() {
...
deleteAll.onClick.listen(deleteAllElements);
}
-
void deleteAllElements(Event e) {
toDoList.children.clear();
}
...
-{% endprettify %}
+```
Function expressions are often used
when registering event handlers on an element
and can extend over multiple lines.
When registering event handlers,
-the function must be an EventListener.
+the function must be an `EventListener`.
That is,
-it returns no value and takes an Event object as a parameter.
+it returns no value and takes an `Event` object as a parameter.
## What next?
-An Element has at most one parent Element.
-An Element's parent is final and cannot be changed.
-So you cannot move an Element by changing its parent.
-Get an Element's parent with the getter `parent`.
-For example, if you have an Element with the name `anElement`
+An `Element` object has at most one parent `Element`.
+An `Element` object's parent is final and cannot be changed.
+So you cannot move an `Element` by changing its parent.
+Get an `Element`'s parent with the getter `parent`.
+For example, if you have an `Element` with the name `anElement`
you would refer to its parent element with `anElement.parent`.
-An Element maintains references to its child elements in a list.
-
You can change the tree structure by adding children to
-and removing children from an Element's list of children.
+and removing children from an element's list of children.
-When you change an Element or its child Elements in your Dart program,
+When you change an `Element` or its child elements in your Dart program,
you change the DOM and therefore the web page.
The browser re-renders the page automatically.
@@ -178,10 +233,10 @@ The following diagram shows a partial DOM tree for the todo app.
-Of interest are the two page elements that have IDs:
+Of interest are the two-page elements that have IDs:
`to-do-input` and `to-do-list`.
-The first identifies the <input> element into which the user types.
-The second identifies the <ul> (unordered list) element
+The first identifies the `` element into which the user types.
+The second identifies the `
Rather than dissect this busy line of code,
think of it as a Dart idiom
-for adding an event handler to an Element.
+for adding an event handler to an `Element` object.
-A change event is just one of many different types of events
+A change event is just one of many types of events
that an input element can generate.
For example, you can use `click` to handle mouse clicks,
or `keyDown` for when the user presses a key on the keyboard.
## About EventListener functions {#about-event-listeners}
-The argument passed to the listen() method is a _callback function_
+The argument passed to the `listen()` method is a _callback function_
of type
-EventListener.
-EventListener is a typedef defined in the dart:html library as follows:
+[`EventListener`]({{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/EventListener.html){:target="_blank" rel="noopener"}.
+`EventListener` is a typedef defined in the `dart:html` library as follows:
-{% prettify dart tag=pre+code %}
+```dart
typedef void EventListener(Event event)
-{% endprettify %}
+```
-As you can see, an EventListener returns no value (void) and takes an
-Event
-object as an argument.
-Any function with this signature is an EventListener.
-Based on its signature, the addToDoItem() function is an EventListener.
+As you can see, an EventListener returns no value (`void`) and takes an
+[`Event`]({{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Event-class.html){:target="_blank" rel="noopener"}object as an argument.
+Any function with this signature is an `EventListener`.
+Based on its signature, the `addToDoItem()` function is an `EventListener`.
-{% prettify dart tag=pre+code %}
+```dart
void addToDoItem(Event e) { ... }
-{% endprettify %}
+```
-The Event object passed into an EventListener function
-carries information about the Event that occurred.
-For example, the Event object knows which Element fired the event,
+The `Event` object passed into an `EventListener` function
+carries information about the `Event` that occurred.
+For example, the `Event` object knows which `Element` fired the event,
and when.
For location-specific events such as mouse clicks,
-the Event object also knows where the event occurred.
+the `Event` object also knows where the event occurred.
-The addToDoItem() function ignores the Event object passed to it.
+The `addToDoItem()` function ignores the Event object passed to it.
## Adding an element to the DOM tree {#add-elem}
@@ -282,7 +337,8 @@ The change event handler has the following code:
The final line of code is where the DOM gets changed.
-An Element keeps references to all of its children in a list called `children`.
+An `Element` object keeps references to all of its children
+in a list called `children`.
By adding and removing elements to and from this list,
the code changes the DOM.
When the DOM changes, the browser re-renders the browser page.
@@ -297,18 +353,18 @@ Let's take a look at the CSS file for this app.
alt="The effect of CSS styles">
This code uses three different kinds of CSS selectors.
-The first is an HTML element selector that matches the \ element
+The first is an HTML element selector that matches the `` element
and sets some basic style attributes,
such as the background color,
for the entire page.
Next in the file are two ID selectors:
-#to-do-input controls the appearance of the input field
-and #to-do-list sets the appearance of the unordered list element
+`#to-do-input` controls the appearance of the input field
+and `#to-do-list` sets the appearance of the unordered list element
in general.
The elements in the list are controlled by the final rule,
which uses both an ID selector and an HTML selector.
-This rule matches all \
-The main() function uses dart:html's top-level querySelector()
-function to get the interesting elements from the DOM.
-Because calling querySelector() isn't free,
+The top-level variables are initialized using
+the `dart:html` library's top-level `querySelector()` function
+to get the interesting elements from the DOM.
+Because calling `querySelector()` isn't free,
if a program refers to an element more than once
-it should stash a reference to the element.
+it should stash a reference to the element if possible.
This program stashes a reference
to the input element
@@ -206,17 +262,17 @@ in a top-level variable called `toDoInput`.
The unordered list
is in the top-level variable `toDoList`.
-Note the types of these variables: InputElement and UListElement.
-These are both subclasses of Element.
-The dart:html library has dozens of Element subclasses,
+Note the types of these variables: `InputElement` and `UListElement`.
+These are both subclasses of `Element`.
+The `dart:html` library has dozens of `Element` subclasses,
many of which correspond to certain HTML tags.
This program uses three:
-| HTML tag | Dart class |
-|---|---|
-| \ | InputElement |
-| \